FormCheckbox

Renders a checkbox input as a form control, representing a boolean, string, number, or array value.

Code examples

const form = useFormStore({
  defaultValues: {
    acceptTerms: false,
  },
});

<Form store={form}>
  <label>
    <FormCheckbox name={form.names.acceptTerms} />
    Accept terms
  </label>
</Form>
const form = useFormStore({
  defaultValues: {
    acceptTerms: false,
  },
});

<Form store={form}>
  <label>
    <FormCheckbox name={form.names.acceptTerms} />
    Accept terms
  </label>
</Form>

Required Props

`name`

StringLike
StringLike

Field name. This can either be a string corresponding to an existing property name in the values state of the store, or a reference to a field name from the names object in the store, ensuring type safety.

Live examples

FormRadioUsing the FormRadioGroup and FormRadio components to create a Form with custom validation that requires a user to select an option from a list of radio buttons.

Form with SelectCombining Form and Select to create an accessible custom select widget that works with the browser's built-in validation and native form submission.

Optional Props

`accessibleWhenDisabled`

boolean | undefined
boolean | undefined

Indicates whether the element should be focusable even when it is disabled.

This is important when discoverability is a concern. For example:

A toolbar in an editor contains a set of special smart paste functions that are disabled when the clipboard is empty or when the function is not applicable to the current content of the clipboard. It could be helpful to keep the disabled buttons focusable if the ability to discover their functionality is primarily via their presence on the toolbar.

Learn more on Focusability of disabled controls⁠.

Live examples

Combobox with TabsOrganizing Combobox with Tab components that support mouse, keyboard, and screen reader interactions. The UI remains responsive by using React.startTransition.

`autoFocus`

boolean | undefined = false
boolean | undefined = false

Automatically focuses the element upon mounting, similar to the native autoFocus prop. This addresses an issue where the element with the native autoFocus attribute might receive focus before React effects are executed.

The autoFocus prop can also be used with Focusable elements within a Dialog component, establishing the initial focus as the dialog opens.

Note: For this prop to work, the focusable prop must be set to true, if it's not set by default.

Live examples

Warning on Dialog hidePreventing users from accidentally closing a modal Dialog component with unsaved changes by displaying a nested confirmation dialog.

Dialog with React RouterUsing React Router to create a modal Dialog that's controlled by the browser history.

Nested DialogRendering a modal Dialog to confirm an action inside another modal dialog using React.

`checked`

boolean | "mixed" | undefined
boolean | "mixed" | undefined

The checked state of the checkbox. This will override the value inferred from store prop, if provided. This can be "mixed" to indicate that the checkbox is partially checked.

`clickOnEnter`

boolean | undefined = true
boolean | undefined = true

If set to true, pressing the enter key while this element is focused will trigger a click on the element, regardless of whether it's a native button or not. If this prop is set to false, pressing enter will not initiate a click.

`clickOnSpace`

boolean | undefined = true
boolean | undefined = true

If set to true, pressing and releasing the space key while this element is focused will trigger a click on the element, regardless of whether it's a native button or not. If this prop is set to false, space will not initiate a click.

`defaultChecked`

boolean | "mixed" | undefined
boolean | "mixed" | undefined

The default checked state of the checkbox. This prop is ignored if the checked or the store props are provided.

`disabled`

boolean | undefined = false
boolean | undefined = false

Determines if the element is disabled. This sets the aria-disabled attribute accordingly, enabling support for all elements, including those that don't support the native disabled attribute.

This feature can be combined with the accessibleWhenDisabled prop to make disabled elements still accessible via keyboard.

Note: For this prop to work, the focusable prop must be set to true, if it's not set by default.

Live examples

SubmenuRendering nested Menu components to create a dropdown menu with submenus that open when hovering over the parent menu item.

Combobox with TabsOrganizing Combobox with Tab components that support mouse, keyboard, and screen reader interactions. The UI remains responsive by using React.startTransition.

Context menuShowing Menu when right-clicking on an element using the getAnchorRect prop to determine the position of the popover.

`focusable`

boolean | undefined = true
boolean | undefined = true

Determines if Focusable features should be active on non-native focusable elements.

Note: This prop only turns off the additional features provided by the Focusable component. Non-native focusable elements will lose their focusability entirely. However, native focusable elements will retain their inherent focusability, but without added features such as improved autoFocus, accessibleWhenDisabled, onFocusVisible, etc.

`getItem`

((props: CollectionStoreItem) => CollectionStoreItem) | undefined
((props: CollectionStoreItem) => CollectionStoreItem) | undefined

A memoized function that returns props to be passed with the item during its registration in the store.

Code examples

const getItem = useCallback((data) => ({ ...data, custom: true }), []);
<CollectionItem getItem={getItem} />
const getItem = useCallback((data) => ({ ...data, custom: true }), []);
<CollectionItem getItem={getItem} />

`id`

string | undefined
string | undefined

The unique ID of the item. This will be used to register the item in the store and for the element's id attribute. If not provided, a unique ID will be automatically generated.

Live examples

Combobox with TabsOrganizing Combobox with Tab components that support mouse, keyboard, and screen reader interactions. The UI remains responsive by using React.startTransition.

Tab with React RouterUsing React Router to create Tab links and tab panels controlled by the browser history, while maintaining keyboard navigation.

Animated TabPanelUsing plain CSS transitions to slide in and out TabPanel components as they are expanded.

Select with Combobox and TabsAbstracting Select to work alongside Combobox and Tab components, presenting a searchable, tabbed dropdown.

`onChange`

React.ChangeEventHandler<HTMLInputElement> | undefined
React.ChangeEventHandler<HTMLInputElement> | undefined

A function that is called when the checkbox's checked state changes.

`onFocusVisible`

BivariantCallback<(event: React.SyntheticEvent<HTMLElement, Event>) => void> | undefined
BivariantCallback<(event: React.SyntheticEvent<HTMLElement, Event>) => void> | undefined

Custom event handler invoked when the element gains focus through keyboard interaction or a key press occurs while the element is in focus. This is the programmatic equivalent of the data-focus-visible attribute.

Note: For this prop to work, the focusable prop must be set to true, if it's not set by default.

Live examples

Navigation MenubarUsing Menubar, Menu, and Portal to create an accessible, tabbable navigation menu widget with links and menu buttons that expand on hover and focus.

Custom CheckboxRendering a visually hidden Checkbox using the VisuallyHidden component to show a custom checkbox presentation in React.

`render`

RenderProp<React.HTMLAttributes<any> & { ref?: React.Ref<any> | undefined; }> | React.ReactElement<any, string | React.JSXElementConstructor<any>> | undefined
RenderProp<React.HTMLAttributes<any> & { ref?: React.Ref<any> | undefined; }> | React.ReactElement<any, string | React.JSXElementConstructor<any>> | undefined

Allows the component to be rendered as a different HTML element or React component. The value can be a React element or a function that takes in the original component props and gives back a React element with the props merged.

Check out the Composition guide for more details.

`shouldRegisterItem`

boolean | undefined = true
boolean | undefined = true

Whether the item should be registered as part of the collection.

`store`

FormStore<FormStoreValues> | undefined
FormStore<FormStoreValues> | undefined

Object returned by the useFormStore hook. If not provided, the closest Form or FormProvider components' context will be used.

`touchOnBlur`

BooleanOrCallback<React.FocusEvent<Element, Element>> | undefined = true
BooleanOrCallback<React.FocusEvent<Element, Element>> | undefined = true

Whether the field should be marked touched on blur.

`value`

string | number | readonly string[] | undefined
string | number | readonly string[] | undefined

The value of the checkbox. This is useful when the same checkbox store is used for multiple Checkbox elements, in which case the value will be an array of checked values.

Live examples

Checkbox groupRendering multiple Checkbox elements in React to form a group of checkboxes. The selected values are stored in an array provided by the CheckboxProvider component.

MenuItemCheckboxRendering a dropdown Menu using the MenuItemCheckbox component with the values and setValues props from MenuProvider to control the checked items.

Code examples

<CheckboxProvider defaultValue={["Apple", "Orange"]}>
  <Checkbox value="Apple" />
  <Checkbox value="Orange" />
  <Checkbox value="Watermelon" />
</CheckboxProvider>
<CheckboxProvider defaultValue={["Apple", "Orange"]}>
  <Checkbox value="Apple" />
  <Checkbox value="Orange" />
  <Checkbox value="Watermelon" />
</CheckboxProvider>

FormCheckbox

Live examples

Live examples

Live examples

Live examples

Code examples

Live examples

Live examples

Live examples

Code examples

Stay tuned