Skip to content

Core Reference

Use this page to find existing iCapture v3 stores, components, functions, and variables you can reuse in custom forms. Import them into files inside src/extensions/. The examples below describe the inspected core source; check your fork when receiving core updates.

Quick lookup

You need to… Reuse
Read the selected dataset, program, organisation unit, or period useSelectionStore
Read metadata already loaded by the application useMetadataStore
Render and automatically save an aggregate input RhfAggregateDhis2Input
Bind an event or tracker field to its existing form RhfDhis2Input
Display a translated metadata label pickTranslation
Connect a custom form to a dataset or program useExtensionStore and setExtensions
Read aggregate completion, expiry, or approval state useAggregateStore
Reuse tracker profile and stage behaviour Tracker labels and the core programStage, status, editing, and loading props
Set the application's name, icon, or extension name Exports in extensionConfig.js

1. Read the current selection — useSelectionStore

import useSelectionStore from "@/store/selectionStore";

// Inside your React component:
const { dataSet, program, orgUnit, period, dataSetCategoryOptions } = useSelectionStore();
Variable What it provides
dataSet The selected aggregate dataset; null before selection.
dataSet.id The dataset identifier used for form registration.
dataSet.dataSetElements The selected dataset's assigned elements; each entry references a data element through dataElement.id.
program The selected event or tracker program; null before selection.
program.programStages Stages in the selected program. The simple event guide uses its single first stage.
programStage.programStageDataElements Stage field assignments, each with a dataElement.id reference and settings such as compulsory. Here, programStage is a stage from program.programStages.
orgUnit The selected organisation unit.
period The selected reporting period; aggregate requests use period.id.
dataSetCategoryOptions The selected dataset category context, or null for the default context. The aggregate workflow uses fields such as attributeOptionCombo, categoryCombo, value, and valid.

Use dataSet.dataSetElements to decide which fields belong in a dataset form. Access the selection only when it exists. This store provides application selection state; it does not load or save field values by itself.

2. Read loaded metadata — useMetadataStore

import useMetadataStore from "@/store/metadataStore";

// Inside your React component:
const { dataElements, categoryOptionCombos, teas, optionSets } = useMetadataStore();
Variable What it provides
dataElements Loaded data element definitions, including identifiers, names, form names, value types, category combinations, and option set references.
categoryOptionCombos Loaded category option combinations. Their categoryCombo reference includes the default indicator used in the aggregate guide.
categoryCombos, categories, categoryOptions Metadata for category dimensions and their options.
dataSets Loaded datasets; use useSelectionStore().dataSet when you need the current selection.
programs, programRules Loaded program definitions and rules.
teas Loaded tracked entity attribute definitions.
optionSets Loaded option sets and their options.
orgUnits Loaded organisation unit metadata.
locale Current metadata locale.
me Loaded current-user information.
systemInfo Loaded system information, extended with application information during initialisation.

Look up a selected dataset element in the loaded definitions:

const foundDataElement = dataElements.find(
  (de) => de.id === field.dataElement.id
);

Here, field is an entry from dataSet.dataSetElements. Use its identifier to find the full definition, then read properties such as foundDataElement.formName and foundDataElement.valueType. Confirm the lookup succeeded before reading properties in a general-purpose component.

To find the default category option combination:

const defaultCombo = categoryOptionCombos.find(
  (combo) => combo.categoryCombo?.isDefault
);

Metadata is loaded by core initialisation. After changing it in DHIS2, reload iCapture so the form uses the updated definitions.

3. Use an aggregate input — RhfAggregateDhis2Input

import RhfAggregateDhis2Input from "@/components/dhis2/rhfaggregatedhis2input";

// Inside the existing aggregate form, with default categories:
<RhfAggregateDhis2Input
  dataElementId={foundDataElement.id}
  name={`${foundDataElement.id}-${defaultCombo.id}-${defaultCombo.id}`}
/>
Property Purpose
dataElementId Finds the data element metadata and corresponding input type.
name Connects to the core aggregate form value using dataElement-categoryOptionCombo-attributeOptionCombo.
control Optional explicit React Hook Form control. The simple guide uses the existing form context.
dataSetCategoryOptions Supplies dataset category context when the dataset uses custom categories.
compulsory Displays the compulsory marker. It does not define a complete validation rule by itself.
disabled Allows the custom layout to disable an input. Core completion, expiry, and approval states also affect editability.

The shared component reads selection and metadata from core stores. Numeric inputs save when the user leaves a changed field. Boolean and date inputs also have immediate-save handling; option set selection has its own save handling. Reuse this behaviour for aggregate fields rather than adding a new save handler.

The core aggregate container loads values and provides the form context. Use this input within that context. Default categories allow the final two identifiers to match; custom categories require the correct category and attribute option combinations.

See Create an Aggregate Form for the complete example.

4. Use an event or tracker input — RhfDhis2Input

import RhfDhis2Input from "@/components/dhis2/rhfdhis2input";

// Inside the existing event or tracker form:
<RhfDhis2Input dataItemId={dataElementId} />

dataItemId becomes the form field name. The component finds the matching tracked entity attribute or data element in useMetadataStore, then renders the shared DHIS2 input for that metadata. For a field such as an event date, dataItem can provide metadata directly, for example { valueType: "DATE" }.

The wrapper binds field values to the existing form. Event and tracker persistence is handled by their core save workflows; this wrapper does not automatically save a whole event when a field changes. Preserve the status, disabled state, and validation feedback supplied by the parent form.

Reuse the event labels

import DataElementLabel from "@/features/event/dataelementlabel";
import EventDateLabel from "@/features/event/eventdatelabel";

<EventDateLabel programStage={programStage} />
<DataElementLabel dataElement={dataElement.id} programStage={programStage.id} />

EventDateLabel takes the stage object and displays its configured event date label, using the core translation helper and default label, plus a required marker. DataElementLabel takes data element and stage identifiers, reads their metadata from the core, and displays the translated field label and compulsory marker. Use these within a selected event program.

Preserve field status

The core passes status into a custom event form. For each field, read status[dataElement.id]; for the event date, read status.occurredAt. Skip fields with hidden: true and pass disabled and helpers to the shared input. The helpers carry validation and rule messages. A custom form can use these existing results without recreating the rule engine.

See Create an Event Form for the complete simple example and registration.

5. Display translated labels — pickTranslation

import { pickTranslation } from "@/utils/metadata";

const label = pickTranslation("FORM_NAME", foundDataElement);

The function first looks for a matching translation in the current metadata locale. For FORM_NAME, it then falls back to formName, followed by name. You can pass a locale as the third argument. Common property names include NAME, SHORT_NAME, and FORM_NAME.

The aggregate guide displays foundDataElement.formName directly to keep its example simple. Reuse pickTranslation when your project needs translated labels and the existing name fallback.

6. Register a custom form — setExtensions

import useExtensionStore from "@/store/extensionStore";

// Inside the extension hook:
const setExtensions = useExtensionStore((state) => state.setExtensions);

Use this function in an effect inside src/extensions/useExtensions.jsx to update the appropriate configuration entry. It accepts a dotted path or an array of keys and a value. For example:

setExtensions(["aggregate", "forms", DATA_SET_ID], MonthlyServiceTotals);
Configuration path Expected value
aggregate.forms[DATA_SET_ID] Aggregate form component.
event.forms[PROGRAM_ID] Object containing Form, validations, and rules, with optional disableDhis2ProgramRules.
tracker.programConfig[PROGRAM_ID][STAGE_ID] Tracker stage form component.
tracker.programConfig[PROGRAM_ID].profileForm Tracker profile form component.

Update the specific entry you need so other project configuration is preserved. See Extension Basics for the registration overview.

7. Read aggregate workflow state — useAggregateStore

import useAggregateStore from "@/store/aggregateStore";

// Inside your React component:
const { completeness, expired, approval } = useAggregateStore();
Variable Purpose
completeness The selected dataset context's completion information, or null. The shared input checks completeness.completed.
expired Whether the reporting context is expired, after the core's expiry and exception checks.
approval The current approval information, or null. The shared input checks its state before allowing edits.
currentDataValues Current form values mirrored by the core aggregate container.
dataValues Data values loaded for the reporting context; do not treat this as the live value of every edited input.

Read these values when a custom layout needs to display workflow information. The shared aggregate input already applies the relevant editing restrictions. Store setters update application state; changing a store value is not a substitute for saving to DHIS2.

8. Reuse extension application settings

The core reads these exports from src/extensions/extensionConfig.js:

Variable Purpose
EXTENSION_NAME Project extension name.
APP_NAME Application name override.
APP_ICON Application icon setting.
ENABLE_PWA Enables or disables the configured PWA mode.

Set these in the extension folder when your project needs them. A simple custom form can keep the core defaults.

9. Reuse tracker profile and stage behaviour

Tracker profile

import AttributeLabel from "@/features/tracker/attributelabel";
import RhfDhis2Input from "@/components/dhis2/rhfdhis2input";

<AttributeLabel attribute={trackedEntityAttribute.id} />
<RhfDhis2Input
  dataItemId={trackedEntityAttribute.id}
  disabled={!editing || loading || fieldStatus.disabled}
  helpers={fieldStatus.helpers}
/>

program.programTrackedEntityAttributes lists the selected program's profile attributes. AttributeLabel reads the metadata and the program's mandatory setting. Use the attribute identifier as the input's dataItemId.

The core passes status, editing, and loading to a registered profileForm. It renders the enrollment date fields itself during registration, and handles registration, enrollment, profile editing, and saving. A custom profile component should render its attributes without duplicating those operations.

Tracker stage

import DataElementLabel from "@/features/tracker/dataelementlabel";
import EventDateLabel from "@/features/tracker/eventdatelabel";

Use the tracker versions of these label components. EventDateLabel takes the stage object; DataElementLabel takes the data element identifier and stage identifier.

Prop supplied by the core Meaning
programStage The stage for the currently opened event. Read its programStageDataElements to create fields.
status Per-field rule and validation states, including hidden, disabled, and helpers.
editing Whether the user is currently editing the event or profile.
loading Whether a save or related operation is in progress.

Skip hidden fields and pass the helpers to the shared input. Use disabled={!editing || loading || fieldStatus.disabled} to preserve the parent's read-only and loading states as well as field rules.

One component can be registered for several tracker stage identifiers. The core passes each stage's own metadata, so the component should use the programStage prop rather than always choosing the program's first stage.

The core's useTrackerStore also exposes tei for the current tracked entity and selectedEvent for the opened stage event. These provide application state; store setters do not save records to DHIS2. The simple profile and stage components do not need to manipulate this store.

See Create a Tracker Form for one profile and two stages using these interfaces.

10. Find more reusable components

The Component Catalog expands this reference with the inputs, selectors, date/time controls, reporting periods, files, charts, dialogs, and layout components available in the inspected core source.

You need to… Continue with
Check which metadata value types have an input DHIS2 form components
Add local filters or selections Inputs and selectors
Use date, time, or age controls Dates, times, and ages
Select a reporting period Reporting periods
Select a file or map point Files and map points
Reuse buttons, tables, dialogs, or charts Actions, layout, and feedback
Understand existing shell controls Core layout and workflow components

The catalog distinguishes local UI state from form binding and DHIS2 saving. Continue using the aggregate, event, and tracker wrappers described above for custom data entry forms.