Component Catalog
Use this catalog to find existing iCapture components before writing a new input, selector, dialog, or layout. Keep project code inside src/extensions/ and import the components you need from core.
For stores, registration, translated labels, and form workflow props, continue using Core Reference. For complete working forms, see the aggregate, event, and tracker guides.
Source and scope
This catalog describes components provided by iCapture core that you can reuse in custom extensions. It covers UI controls in src/components/ui, DHIS2 inputs and selectors in src/components/dhis2, and application layout components in src/components/layout.
Each section explains what the components do, their main props, and how to use them. It also identifies components that depend on core form context, metadata, or workflows, so you can choose the right component for your form.
Use this catalog alongside Core Reference for stores, shared functions, and extension configuration. When updating your fork, check the corresponding core component for any changes to its props or behaviour.
Choose the right starting point
| What you need | Start with | Who handles saving? |
|---|---|---|
| Dataset data entry | RhfAggregateDhis2Input |
Core aggregate input and workflow, within the existing aggregate form. |
| Event field, tracker attribute, or tracker stage field | RhfDhis2Input |
Core event/profile workflow. The wrapper updates form values. |
| A metadata-driven input outside those wrappers | Dhis2Input |
Your surrounding form workflow. File resources have a separate upload operation. |
| A local filter, search box, or display setting | UI inputs and selectors | Your component owns local state; these controls do not save records. |
| Existing navigation, completion, or registration actions | Core layout and extension settings | Keep the existing core workflow and configure it where supported. |
Use the RHF wrappers for the form guides. Replacing them with a plain Input would also require reconnecting the existing form state, metadata, feedback, and saving behaviour.
DHIS2 form components
All imports below are default imports from the indicated file, without the .jsx suffix.
| Component | Import path | Main props and behaviour |
|---|---|---|
RhfAggregateDhis2Input |
@/components/dhis2/rhfaggregatedhis2input |
dataElementId, name, optional control, compulsory, dataSetCategoryOptions. Reads core selection/metadata and saves aggregate changes. Requires the existing aggregate form context. |
RhfDhis2Input |
@/components/dhis2/rhfdhis2input |
dataItemId, optional dataItem, control, and input props. Uses the identifier as the RHF field name. Finds attribute/data element metadata or accepts an explicit definition. |
Dhis2Input |
@/components/dhis2/dhis2input |
dataItem, value, onChange, disabled, helpers, options, hiddenOptions, multiSelection, renderAsRadio, postElement. Chooses an input from metadata. |
OrgUnitSelector |
@/components/dhis2/orgunitselector |
orgUnit, onChange, filter, selectableOrgUnits, customHierarchy, disabled, initialOpenState, scrollTo, placeholder. Callback receives the selected organisation unit object, or null. |
Cascader |
@/components/dhis2/cascader |
tree, cascaderLabels, value, onChange, disabled. Value is an array of selected node IDs; selecting a parent clears its descendants. Tree nodes use id, name, optional translations, and children. |
Dhis2FileInput |
@/components/dhis2/dhis2-file-input |
value, onChange, dataItem, eventUid, teiUid. Uploads a file resource and returns its UID; clearing returns an empty string. Existing downloads require the owning event or tracked entity and field metadata. |
GeometryPicker |
@/components/dhis2/geometry-picker |
value, onChange, disabled. Selects a GeoJSON Point; clear returns null. Requires organisation unit boundary data and map services. |
The source also contains src/components/dhis2/orgunitselector copy.jsx. It is an alternative copy with no imports found in this checkout. Use orgunitselector.jsx for new extension code.
Input types selected by Dhis2Input
Option sets take precedence over the value type: an option set normally uses Select; renderAsRadio switches to radio options, and multiSelection or MULTI_TEXT with options uses MultiSelect.
| Value type without an option set | Current control | Value notes |
|---|---|---|
TEXT, EMAIL |
Input |
String. Choosing this control alone does not provide complete format validation. |
NUMBER, INTEGER, INTEGER_POSITIVE, INTEGER_NEGATIVE, INTEGER_ZERO_OR_POSITIVE, PERCENTAGE, PHONE_NUMBER |
Input |
Change handler retains digits, periods, and minus signs. This filtering does not enforce every numeric or phone rule. |
LONG_TEXT |
Textarea |
String. |
DATE |
DatePicker |
Date string. |
TIME |
TimePicker |
Hour/minute string. |
DATETIME |
DateTimePicker |
Combined date/time string. |
AGE |
AgePicker |
Date of birth string, with age entry helpers. |
BOOLEAN |
Yes/no radio controls | "true", "false", or "". Clicking the selected option clears it. |
TRUE_ONLY |
Checkbox |
"true" or "". |
ORGANISATION_UNIT |
OrgUnitSelector |
Wrapper converts the selected object to its ID string. |
CASCADER |
Cascader |
Array of selected node IDs. |
FILE_RESOURCE, IMAGE |
Dhis2FileInput |
File resource UID. Images restrict the accepted types to image/*. |
COORDINATE |
Placeholder text | No working coordinate input in this dispatch. GeometryPicker is a separate Point selector. |
| Other unmatched types | Unsupported message | Check the current switch before depending on another type. |
This table describes Dhis2Input, used by the event/tracker wrapper. Aggregate inputs have their own implementation; do not assume every type above has aggregate auto-save support.
Keep core field status
import RhfDhis2Input from "@/components/dhis2/rhfdhis2input";
export default function ExampleStageField({ dataElementId, status = {}, editing, loading }) {
const fieldStatus = status[dataElementId] || {};
if (fieldStatus.hidden) return null;
return (
<RhfDhis2Input
dataItemId={dataElementId}
disabled={!editing || loading || fieldStatus.disabled}
helpers={fieldStatus.helpers}
/>
);
}
This fragment is for a tracker stage inside its existing form context. Render its label with the tracker DataElementLabel described in Core Reference. Event forms receive their own parent props; use the event guide for that workflow.
Inputs and selectors
These controls are useful for local UI state. They do not register a field with React Hook Form by themselves.
Named export and file under src/components/ui/ |
Main interface |
|---|---|
Input — input.jsx |
Native-style value, onChange(event), type, placeholder, disabled. Read event.target.value. |
Textarea — textarea.jsx |
Native-style multiline input and change event. |
Label — label.jsx |
htmlFor, children, className. Use a matching input ID. |
InputHelper — inputhelper.jsx |
type: error, warning, or info; children or html. Pass trusted HTML only; html is inserted directly. |
Select — select.jsx |
options, value, onChange(value), optional groups, label, placeholder, searchPlaceHolder, disabled, includeOptionCode, popoverClassName. Clear emits "". |
MultiSelect — multiselect.jsx |
options, value, onChange(value), optional groups, label, placeholder, searchPlaceHolder, disabled, showRemove. Value is a comma-separated string, such as "first,followup"; clear emits "". |
Checkbox — checkbox.jsx |
checked, onCheckedChange(checked), disabled. Use this callback rather than native input onChange. |
RadioGroup, RadioGroupItem — radiogroup.jsx |
Group value and onValueChange; each item has a value and can have an id. |
Select options use { value, label }; grouped options also have group, which matches a group object's value. Both selectors filter the options supplied by the caller; they do not fetch options from DHIS2.
import { useState } from "react";
import { Select } from "@/components/ui/select";
import { MultiSelect } from "@/components/ui/multiselect";
const options = [
{ value: "first", label: "First visits" },
{ value: "followup", label: "Follow-up visits" },
];
export default function ServiceFilters() {
const [service, setService] = useState("");
const [services, setServices] = useState("");
return (
<div className="max-w-md space-y-3">
<Select label="One service" options={options} value={service} onChange={setService} />
<MultiSelect label="Several services" options={options} value={services} onChange={setServices} />
</div>
);
}
Dates, times, and ages
| Export | Import path | Value and callback |
|---|---|---|
Named DatePicker |
@/components/ui/datepicker |
value and onChange: yyyy-MM-dd string; clear emits "". |
Named DateRangePicker |
@/components/ui/date-range-picker |
{ from: "yyyy-MM-dd", to: "yyyy-MM-dd" }; clear emits "". Normalize that cleared value when your code expects an object. |
Default TimePicker |
@/components/ui/time-picker |
HH:mm string using separate hour/minute selections. Partial strings can occur while choosing both parts. |
Default DateTimePicker |
@/components/ui/date-time-picker |
Combines the date and time with T. Partial values can occur; it does not convert time zones. |
Named AgePicker |
@/components/ui/agepicker |
Date of birth string. Supports refDate and agePickerLayout (layout1 or layout2); age changes calculate a birth date on blur. Reference date defaults to today. |
Named Calendar, CalendarDayButton |
@/components/ui/calendar |
Lower-level calendar controls used by the pickers. Use a picker when you want its string-value interface. |
All four date/time pickers accept disabled. DatePicker supports minDate, maxDate, defaultMonth, optional allowKeyboard, and dateFormat. Its default maximum date is today; pass maxDate if future dates are needed. Display formats include dd/MM/yyyy, dd-MM-yyyy, and ddMMyyyy, while emitted dates remain yyyy-MM-dd.
DateRangePicker also enforces minDate/maxDate, defaulting from 150 years ago to today. It declares some date formatting/keyboard props but does not implement the same keyboard behaviour as DatePicker.
import { useState } from "react";
import { DatePicker } from "@/components/ui/datepicker";
import TimePicker from "@/components/ui/time-picker";
export default function LocalDateAndTime() {
const [date, setDate] = useState("");
const [time, setTime] = useState("");
return (
<div className="max-w-sm space-y-3">
<DatePicker value={date} onChange={setDate} />
<TimePicker value={time} onChange={setTime} />
</div>
);
}
Reporting periods
Import the default PeriodSelector from @/components/dhis2/period-selector/periodselector.
Main props are periodType, value, onChange, disabled, openFuturePeriods, minYear, and maxYear. The value is a period object, rather than a period ID string. Clearing emits null. The outer picker commits its selection through Apply or when interacting outside the picker.
For example, a monthly period contains id, name, startDate, endDate, and periodType:
{
id: "202601",
name: "January 2026",
startDate: "2026-01-01",
endDate: "2026-01-31",
periodType: "Monthly"
}
The displayed name follows the current language. These are the exact period types dispatched in the inspected source:
periodType |
Implementation under src/components/dhis2/period-selector/ |
|---|---|
Daily |
dailyselector.jsx |
Weekly |
weeklyselector.jsx |
WeeklySaturday |
weeklysaturdayselector.jsx |
WeeklySunday |
weeklysundayselector.jsx |
Monthly |
monthlyselector.jsx |
Quarterly |
quarterlyselector.jsx |
SixMonthly |
sixmonthlyselector.jsx |
Yearly |
yearselector.jsx |
FinancialOct |
financialoctoberselector.jsx |
FinancialApril |
financialaprilselector.jsx |
Use the outer PeriodSelector rather than importing these implementations directly; it supplies their year options and the selection popover. This list does not imply support for every DHIS2 period type. For the selected aggregate reporting period, reuse useSelectionStore().period and the existing control bar instead of adding a second selector.
Files and map points
Local file selection
FilePicker is a default export from @/components/ui/file-picker.
It accepts value as an array, onChange(files), supportTypes (default ["*"]), maxSize in MB (default 5), multiple (default false), and disabled. Newly selected items are browser File objects; existing file descriptors can include name, type, size, url, and id.
It handles selection, previews, size/type checks, and removal. It does not upload to DHIS2. Use Dhis2FileInput for the existing file-resource upload integration, then let the enclosing event/profile workflow save the resource UID as a field value.
import { useState } from "react";
import FilePicker from "@/components/ui/file-picker";
export default function LocalAttachment() {
const [files, setFiles] = useState([]);
return <FilePicker value={files} onChange={setFiles} supportTypes={["image/*"]} maxSize={5} />;
}
Map point selection
GeometryPicker uses a GeoJSON Point with longitude before latitude:
{ type: "Point", coordinates: [105.85, 21.03] }
Its map uses organisation unit boundary polygons and external map tiles. It returns a selected Point through onChange; it does not save a DHIS2 event or edit polygons. This does not replace the unimplemented COORDINATE branch in Dhis2Input automatically.
Actions, layout, and feedback
The following table lists every remaining UI file. Imports are named unless marked default. Family names below describe related exports; import individual parts from the same module.
File under src/components/ui/ |
Exports | Use and main props |
|---|---|---|
button.jsx |
Button, buttonVariants |
variant, size, asChild, native button props. Variants: default, warning, success, destructive, outline, secondary, ghost, link. Sizes: default, sm, lg, icon. |
loadingbutton.jsx |
LoadingButton |
Adds loading; shows a spinner and disables the button while loading. |
button-group.jsx |
ButtonGroup, ButtonGroupText, ButtonGroupSeparator |
Groups related controls; supports group orientation. |
card.jsx |
Card, CardHeader, CardTitle, CardDescription, CardAction, CardContent, CardFooter |
Panel layout and heading/action areas. |
table.jsx |
Table, TableHeader, TableBody, TableFooter, TableHead, TableRow, TableCell, TableCaption |
Styled table parts; your component supplies rows and data. |
accordion.jsx |
Accordion, AccordionItem, AccordionTrigger, AccordionContent |
Expandable sections; item values identify sections. |
tabs.jsx |
Tabs, TabsList, TabsTrigger, TabsContent |
Tab values connect triggers and content; controlled with value/onValueChange. |
separator.jsx |
Separator |
Visual separator with orientation. |
dialog.jsx |
Dialog family | Dialog, trigger, content, header, title, description, footer, close, portal, overlay. Controlled with root open/onOpenChange; showCloseButton belongs to DialogContent. |
alert-dialog.jsx |
AlertDialog family | Confirmation dialog parts, including AlertDialogAction and AlertDialogCancel. Your handler performs the action. |
popover.jsx |
Popover, PopoverTrigger, PopoverContent, PopoverAnchor |
Anchored content; root supports open/onOpenChange. |
popover-button.jsx |
Default PopoverButton |
label, buttonProps, popoverComponent. Combines a loading button trigger and popover. |
dropdown-menu.jsx |
DropdownMenu family | Menu root, trigger, content, items, groups, labels, separator, shortcuts, checkbox/radio and submenu parts. |
command.jsx |
Command family | Search/list composition: Command, CommandDialog, CommandInput, CommandList, CommandEmpty, CommandGroup, CommandItem, CommandSeparator, CommandShortcut. |
tooltip.jsx |
Tooltip, TooltipTrigger, TooltipContent, TooltipProvider |
Contextual hints; compose provider, root, trigger, and content as needed. |
pagination.jsx |
Pagination family | Pagination, content, item, link, previous, next, first, last, ellipsis. Caller handles page changes; links support active state. |
alert.jsx |
Alert, AlertTitle, AlertDescription |
Inline message; variants default and destructive. |
progress.jsx |
Progress |
Progress indicator using a numeric value. |
skeleton.jsx |
Skeleton |
Loading placeholder; set dimensions with className. |
sonner.jsx |
Toaster |
Toast host already mounted by the core application. Use toast from sonner for messages. |
echart.jsx |
EChart |
ECharts wrapper: option, chartSettings, optionSettings, events. Give its container a height. The declared loading prop currently has no active loading-indicator handling. |
Use a core button for a local action
import { useState } from "react";
import { Button } from "@/components/ui/button";
import { Alert, AlertTitle, AlertDescription } from "@/components/ui/alert";
export default function GuideNote() {
const [visible, setVisible] = useState(false);
return (
<div className="space-y-3">
<Button type="button" variant="outline" onClick={() => setVisible(!visible)}>
Show guidance
</Button>
{visible && (
<Alert>
<AlertTitle>Data entry</AlertTitle>
<AlertDescription>Check the selected organisation unit before entering data.</AlertDescription>
</Alert>
)}
</div>
);
}
Set type="button" for local actions inside an existing form so they do not accidentally submit it. The core already provides event/profile save actions; keep those workflows when adding a custom layout.
Display a chart
import { EChart } from "@/components/ui/echart";
export default function ServiceChart() {
return (
<div className="h-64">
<EChart option={{
xAxis: { type: "category", data: ["First visits", "Follow-up visits"] },
yAxis: { type: "value" },
series: [{ type: "bar", data: [12, 8] }],
}} />
</div>
);
}
This example uses local display values. EChart does not fetch analytics or save form data. Its events handlers are bound during initial setup; check the implementation if handlers need to change after mounting.
Core layout and workflow components
These files are part of the application shell and generally read core stores, router state, and selected metadata. Their presence does not make them independent extension widgets. Prefer the existing shell and documented extension settings over mounting a second control bar, registration button, or completion action.
All files below have default exports. Paths are relative to src/components/layout/.
| File | Existing core responsibility |
|---|---|
circularloader.jsx |
CircularLoader: reusable spinner with label and color. |
initloader.jsx |
InitLoader: initialisation progress through value. |
error-dialog.jsx |
Application error dialog using core state. |
offline-notification-dialog.jsx |
Offline notification dialog using core state. |
under-development-alert.jsx |
Static development placeholder. |
headerbar.jsx |
HeaderBarWrapper: DHIS2 application header. |
control-bar/control-bar.jsx |
Composes the main selection and action controls. |
control-bar/change-language-button.jsx |
Language selection. |
control-bar/dataset-categorycombo-section.jsx |
Dataset category context. |
control-bar/dataset-completeness-section.jsx |
Dataset completion/incompletion actions. |
control-bar/event-register-section.jsx |
Event registration action. |
control-bar/help.jsx |
Help information. |
control-bar/org-unit-selection.jsx |
Selected organisation unit control. |
control-bar/period-selection.jsx |
Selected reporting period control. |
control-bar/program-completeness-section.jsx |
Program-associated reporting completion. This is separate from tracker enrollment completion. |
control-bar/program-dataset-selection-classic.jsx |
Alternative dataset/program selector. |
control-bar/program-dataset-selection.jsx |
Dataset/program selector. |
control-bar/run-validations-section.jsx |
Aggregate validation action. |
control-bar/tracker-register-section.jsx |
Tracker registration/search actions. |
Configure the existing core UI
useExtensionStore().setExtensions updates configuration without changing these files. For example, inside the existing extension hook:
import { useEffect } from "react";
import useExtensionStore from "@/store/extensionStore";
export default function useExtensions() {
const setExtensions = useExtensionStore((state) => state.setExtensions);
useEffect(() => {
setExtensions(["controlBar", "customButtonsRight"], <span>Project guidance</span>);
}, [setExtensions]);
// Keep your existing form registration effects here too.
}
This fragment belongs inside the existing hook function in src/extensions/useExtensions.jsx; retain the form registration effects already there. customButtonsLeft and customButtonsRight take rendered React content. The control bar also reads supportedLanguages for its language selector and selectableOrgUnits for its organisation unit selector. These UI settings do not grant DHIS2 permissions.
For form registration paths, tracker props, and core settings, see Core Reference. For application behaviour that depends on permissions, metadata, or selected context, follow Testing and Troubleshooting.
Reuse checklist
- For data entry, start with the appropriate RHF wrapper and keep the existing form context.
- Preserve hidden/disabled states and helpers supplied by core rules.
- Check callback values: native input events, scalar strings, comma-separated strings, period objects, and organisation unit objects have different shapes.
- Keep core save, registration, completion, and error handling connected to their existing workflows.
- Add project components and configuration inside
src/extensions/.