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.