FormRadio

Renders a radio button in a form.

Code examples

const form = useFormStore({
  defaultValues: {
    char: "a",
  },
});
<Form store={form}>
  <FormRadioGroup>
    <FormGroupLabel>Favorite character</FormGroupLabel>
    <FormRadio name={form.names.char} value="a" />
    <FormRadio name={form.names.char} value="b" />
    <FormRadio name={form.names.char} value="c" />
  </FormRadioGroup>
</Form>
const form = useFormStore({
  defaultValues: {
    char: "a",
  },
});
<Form store={form}>
  <FormRadioGroup>
    <FormGroupLabel>Favorite character</FormGroupLabel>
    <FormRadio name={form.names.char} value="a" />
    <FormRadio name={form.names.char} value="b" />
    <FormRadio name={form.names.char} value="c" />
  </FormRadioGroup>
</Form>

Required Props

name

StringLike
StringLike

Name of the field.

value

string | number
string | number

The value of the radio button.

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.

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.

Live examples

checked

boolean | undefined
boolean | undefined

Whether the radio button is 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.

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.

Live examples

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: Item) => Item) | undefined
((props: Item) => Item) | undefined

A memoized function that returns props that will be passed along with the item when it gets registered to the store.

Code examples

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

moveOnKeyPress

BooleanOrCallback<React.KeyboardEvent<HTMLElement>> | undefined = true
BooleanOrCallback<React.KeyboardEvent<HTMLElement>> | undefined = true

Whether pressing arrow keys should move the focus to a different item.

onChange

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

Callback function that is called when the radio button store 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 a programmatic equivalent of the data-focus-visible attribute.

Live examples

preventScrollOnKeyDown

BooleanOrCallback<React.KeyboardEvent<HTMLElement>> | undefined = false
BooleanOrCallback<React.KeyboardEvent<HTMLElement>> | undefined = false

Whether the scroll behavior should be prevented when pressing arrow keys on the first or the last items.

rowId

string | undefined
string | undefined

The id that will be used to group items in the same row. This is usually retrieved by the CompositeRow component through context so in most cases you don't need to set it manually.

shouldRegisterItem

boolean | undefined = true
boolean | undefined = true

Whether the item should be registered to the store.

store

FormStore | undefined
FormStore | undefined

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

tabbable

boolean | undefined
boolean | undefined

When the tabbable prop is set to true, the roving tabindex method is partially disabled for this element. This means that the tabIndex prop won't be assigned -1 when the item is inactive. In addition to using arrow keys, users will be able to tab to this element, leading to the composite widget no longer existing as a single tab stop.

As per the ARIA spec:

Authors SHOULD ensure that a composite widget exists as a single navigation stop within the larger navigation system of the web page.

Additionally, as stated in RFC-2119:

SHOULD This word, or the adjective "RECOMMENDED", mean that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course.

Therefore, while this may be allowed, you should think carefully about the implications of using this prop.

Note: This prop has no effect when the virtualFocus option is enabled.

Live examples

touchOnBlur

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

Whether the field should be marked touched on blur.