import { Meta, ArgTypes, Story, Controls, Source, } from '@storybook/addon-docs/blocks';

Radio

The @bento/radio package provides accessible, customizable radio controls. It exports the RadioGroup and Radio primitives, enabling you to build groups of radio options with consistent keyboard navigation, focus management, and ARIA support.

The RadioGroup allows a user to select a single item from a list of Radio components.

The Radio is a single radio option that can be selected by the user.

Installation

npm install --save @bento/radio

Props

The following properties are available to be used on the RadioGroup and Radio primitives:

RadioGroup

| Prop | Type | Required | Description | |------|------|----------|------------| | value | string | No | The current value (controlled). | | defaultValue | string | No | The default value (uncontrolled). | | isDisabled | boolean | No | Whether the input is disabled. | | isReadOnly | boolean | No | Whether the input can be selected but not changed by the user. | | isRequired | boolean | No | Whether user input is required on the input before form submission. | | isInvalid | boolean | No | Whether the input value is invalid. | | name | string | No | The name of the input element, used when submitting an HTML form. | | form | string | No | The <form> element to associate the input with. The value of this attribute must be the id of a <form> in the same document. | | children | ReactNode | Yes | Radio children. | | slot | string | No | A named part of a component that can be customized. This is implemented by the consuming component. The exposed slot names of a component are available in the components documentation. | | slots | Record<string, object \| Function> | No | An object that contains the customizations for the slots. The main way you interact with the slot system as a consumer. | | ref | Ref<HTMLDivElement> \| LegacyRef<Component<RadioGroupProps & Slots, any, any>> | No | Allows getting a ref to the component instance. Once the component unmounts, React will set ref.current to null (or call the ref with null if you passed a callback ref). @see {@link https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom React Docs} | | as | "div" | No | |

Radio

| Prop | Type | Required | Description | |------|------|----------|------------| | value | string | Yes | The value of the radio button, used when submitting an HTML form. | | inputRef | Ref<HTMLInputElement> | No | A ref for the HTML input element. | | children | ReactNode | No | The label for the Radio. Accepts any renderable node. | | isDisabled | boolean | No | Whether the radio button is disabled or not. Shows that a selection exists, but is not available in that circumstance. | | autoFocus | boolean | No | Whether the element should receive focus on render. | | slot | string | No | A named part of a component that can be customized. This is implemented by the consuming component. The exposed slot names of a component are available in the components documentation. | | slots | Record<string, object \| Function> | No | An object that contains the customizations for the slots. The main way you interact with the slot system as a consumer. | | ref | Ref<HTMLDivElement> \| LegacyRef<Component<RadioProps & Slots, any, any>> | No | Allows getting a ref to the component instance. Once the component unmounts, React will set ref.current to null (or call the ref with null if you passed a callback ref). @see {@link https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom React Docs} | | as | "div" | No | |

Data Attributes, Slot Map and Props

The data attributes, slot map and props can be used to style and customize the RadioGroup and Radio primitives.

RadioGroup Data Attributes

| Attribute | Description | Example Values | | ---------------- | ------------------------------- | -------------- | | data-disabled | Indicates the group is disabled | "true" | | data-readonly | Indicates the group is readonly | "true" | | data-required | Indicates the group is required | "true" | | data-invalid | Indicates the group is invalid | "true" |

Radio Data Attributes

| Attribute | Description | Example Values | | -------------------- | ------------------------------------ | -------------- | | data-pressed | Indicates the radio is being pressed | "true" | | data-hovered | Indicates the radio is hovered | "true" | | data-focused | Indicates the radio has focus | "true" | | data-focus-visible | Indicates focus should be visible | "true" | | data-selected | Indicates the radio is selected | "true" | | data-disabled | Indicates the radio is disabled | "true" | | data-readonly | Indicates the radio is readonly | "true" | | data-invalid | Indicates the radio is invalid | "true" | | data-required | Indicates the radio is required | "true" |

RadioGroup Slot Map

| Slot Name | Description | | ------------- | --------------------------- | | label | Label for radio group | | description | Description for radio group | | error | Error for radio group |

Radio Slot Map

| Slot Name | Description | | ---------------- | ------------------------ | | icon-checked | Icon for checked radio | | icon-unchecked | Icon for unchecked radio |

Examples

Uncontrolled

The RadioGroup is uncontrolled by default.

import { Radio, RadioGroup } from '@bento/radio';
import { Text } from '@bento/text';
/* v8 ignore next */
import React from 'react';

export function UncontrolledExample() {
  return (
    <RadioGroup onChange={(value: string) => console.log('selected', value)}>
      <Text slot="label">Favorite fruit</Text>
      <Radio value="apple">Apple</Radio>
      <Radio value="banana">Banana</Radio>
      <Radio value="orange" isDisabled>
        Orange
      </Radio>
    </RadioGroup>
  );
}

Controlled

The RadioGroup can be controlled by passing a value and onChange prop.

/* v8 ignore next */
import React, { useState } from 'react';
import { RadioGroup, Radio } from '@bento/radio';
import { Text } from '@bento/text';

export function ControlledExample() {
  const [value, setValue] = useState<string>();
  return (
    <RadioGroup value={value} onChange={setValue}>
      <Text slot="label">Favorite fruit</Text>
      <Radio value="apple">Apple</Radio>
      <Radio value="banana">Banana</Radio>
      <Radio value="orange">Orange</Radio>
    </RadioGroup>
  );
}

Single Radio

Even if you only have one radio option, it must always be placed inside a RadioGroup.

import { Radio, RadioGroup } from '@bento/radio';
import { Text } from '@bento/text';
/* v8 ignore next */
import React, { type ComponentProps } from 'react';

export function SingleRadioExample(props: {
  groupProps?: Partial<ComponentProps<typeof RadioGroup>>;
  radioProps?: Partial<ComponentProps<typeof Radio>>;
}) {
  return (
    // Radios are always required to be in a group
    <RadioGroup name="fruit" {...props.groupProps}>
      <Text slot="label">Favorite fruit (single radio)</Text>
      <Radio value="apple" {...props.radioProps}>
        Apple
      </Radio>
      <Text slot="description">This is the description</Text>
    </RadioGroup>
  );
}