Controllers and stores
Some Mantine components can be driven with a hook. Call use<Component> in your component,
get back an object with actions and queries, and pass it to the component with a prop. There are
two kinds of these objects:
- A controller is passed with the
controllerprop. It adds actions and queries to a component that you use as is, for exampleexpandAll()onAccordionornext()onStepper. - A store is passed with the
storeprop. It is a building block for your own component, for exampleuseSelectlets you build a custom select on top ofSelect.
Both are optional. Every component works without them with value, defaultValue and onChange
props, see Controlled vs Uncontrolled.
Controllers
A controller owns the component state. Create it with the hook, pass the same state options
that the component accepts as props, and pass the result to the controller prop:
Use a controller when props are not enough:
- To call an action that depends on state the component owns internally, for example
expandAll()needs the list of mounted items. - To drive the component from outside its subtree, for example from a toolbar or a keyboard shortcut handler.
- To read state that
onChangedoes not report, for exampleisExpanded(item)orgetItems().
Each component documents the actions and queries of its controller on its own page, see the list of components below.
Stores
A store is created with a use<Component> hook and passed to the store prop. Use it as a base
for your own component with its own props and behavior. For example, useSelect reuses the value,
search and dropdown handling of Select to build a select that offers to create an option from the
search text:
Combobox, Tree and DataGrid are building blocks by design, so they work with a store as
well, see the list of components below.
Controller and props
When the controller prop is set, the controller owns the state and the state props of the
component are ignored. Pass them to the hook instead:
The controller prop description in the props table of each component lists the props it
replaces. Other props, for example size, variant and classNames, work the same way
with and without a controller. The same rules apply to the store prop.
Usage with forms
form.getInputProps('field') from @mantine/form returns value, change handler
and other props for the component. How they combine with a controller depends on whether
the controller owns the value.
Most controllers do not own the value. For example, @mantine/dates controllers own the displayed
date, level and dropdown state, while the selected value stays on the component. For these
components, spread form.getInputProps() on the component and pass the controller next to it:
usePinInput, useTimePicker and useMaskedDateInput own the value, so form.getInputProps()
cannot be spread on the component. Instead, create a wrapper component: it passes the props
that the controller replaces to the hook and forwards the rest to the component:
The pattern has three rules:
- Pass every prop that the
controllerprop replaces to the hook, not onlyvalue,defaultValueandonChange. For example,lengthofPinInputandformatofTimePickerare ignored on the component once a controller is set. - Keep
error,onFocusandonBluron the component. - Pass
onChangeto the hook as is, so thatform.reset()clears a partially entered value.
Controller actions, for example clear() or setValue(), call onChange the same way as typing,
so the form stays in sync.
Inside the wrapper you can use controller queries that the form cannot see.
For example, the form treats an incomplete time as empty, while controller.hasValue() knows that
the user has started typing:
The same component works with other form libraries. With
react-hook-form, pass the field props of Controller:
Reading state
The component that called the hook rerenders when the state changes, so queries can be used during render:
Actions and queries keep the same reference for the lifetime of the controller. They are safe as effect dependencies and as props of memoized components, and queries always return the latest value:
Queries that depend on rendered children, for example getItems() on Accordion or
getStepCount() on Stepper, return an empty result before the component is rendered.
Stores work the same way, except useDataGrid, which returns a new object on every render.
TypeScript
Controller and store types are named after the component and exported from the same package as the hook. Use them to type a controller that is created in one component and passed to another:
When the state type depends on an option, the type is inferred from the options passed to the hook:
Components with controllers
@mantine/core:
- Accordion,
useAccordion - Editable,
useEditable - ImageCropper,
useImageCropper - Menubar,
useMenubar - Pagination,
usePagination, also exported from@mantine/hooks - PinInput,
usePinInput - Stepper,
useStepper - Timer,
useTimer
@mantine/dates:
- Calendar,
DatePicker,
MonthPicker,
YearPicker,
WeekPicker and
QuarterPicker,
useCalendar - DatePickerInput,
useDatePickerInput - MonthPickerInput,
useMonthPickerInput - YearPickerInput,
useYearPickerInput - WeekPickerInput,
useWeekPickerInput - QuarterPickerInput,
useQuarterPickerInput - DateInput,
useDateInput - MaskedDateInput,
useMaskedDateInput - DateTimePicker,
useDateTimePicker - InlineDateTimePicker,
useInlineDateTimePicker - TimePicker,
useTimePicker
Components with stores
- Autocomplete,
useAutocomplete - Combobox,
useCombobox - MultiSelect,
useMultiSelect - Select,
useSelect - TagsInput,
useTagsInput - Tree,
useTree - DataGrid,
useDataGrid, exported from@mantine/data-grid