Radio

Radio components allow users to select a single option from a set. They are typically used within a RadioGroup for managing selection state and layout.

Installation

$ cbui-cli install @crossbuildui/radio

To get started, please make sure you have installed cbui-cli globally and authenticated your account. This will ensure you can access all the necessary features.

View documents

Import

index.tsx

import { RadioGroup, Radio } from '@/crossbuildui/radio';

RadioGroup Component

The RadioGroup component is a container for Radio buttons. It manages the selection state, layout, and common properties for its children.

Basic Usage

Wrap Radio components within a RadioGroup. Provide a label for the group.

MyComponent.tsx

<RadioGroup label="Favorite Pet">
  <Radio value="dog">Dog</Radio>
  <Radio value="cat">Cat</Radio>
  <Radio value="dragon">Dragon</Radio>
</RadioGroup>

Orientation

Use the orientation prop to lay out radio buttons vertically (default) or horizontally.

MyComponent.tsx

<View style={{gap: 24}}>
  <RadioGroup label="Preferred Contact (Vertical)" orientation="vertical">
    <Radio value="email">Email</Radio>
    <Radio value="phone">Phone</Radio>
    <Radio value="sms">SMS</Radio>
  </RadioGroup>
  <RadioGroup label="Preferred Contact (Horizontal)" orientation="horizontal">
    <Radio value="email">Email</Radio>
    <Radio value="phone">Phone</Radio>
    <Radio value="sms">SMS</Radio>
  </RadioGroup>
</View>

Colors

The color prop on RadioGroup sets the default color for all child Radio components. Individual Radio components can override this.

MyComponent.tsx

<RadioGroup label="Notification Color" defaultValue="primary">
  <Radio value="primary" color="primary">Primary</Radio>
  <Radio value="secondary" color="secondary">Secondary</Radio>
  <Radio value="success" color="success">Success</Radio>
  <Radio value="warning" color="warning">Warning</Radio>
  <Radio value="danger" color="danger">Danger</Radio>
  <Radio value="default" color="default">Default</Radio>
</RadioGroup>

Controlled and Uncontrolled

Manage selection state externally using value and onValueChange, or use defaultValue for an uncontrolled group.

MyComponent.tsx

function ControlledRadioGroup() {
  const [selected, setSelected] = React.useState('apple');

  return (
    <View style={{gap: 8}}>
      <RadioGroup
        label="Choose a fruit:"
        value={selected}
        onValueChange={setSelected}
      >
        <Radio value="apple">Apple</Radio>
        <Radio value="banana">Banana</Radio>
        <Radio value="orange">Orange</Radio>
      </RadioGroup>
      <Text>Selected: {selected}</Text>
    </View>
  );
}

// Uncontrolled (uses defaultValue)
// <RadioGroup label="Choose a color (Uncontrolled)" defaultValue="red">
//   <Radio value="red">Red</Radio>
//   <Radio value="blue">Blue</Radio>
// </RadioGroup>

Description and Error Message

Provide context with description or display validation feedback using errorMessage.

MyComponent.tsx

<View style={{gap: 16}}>
  <RadioGroup
    label="Subscription Tier"
    description="Select your preferred subscription plan."
  >
    <Radio value="free">Free Tier</Radio>
    <Radio value="pro">Pro Tier</Radio>
  </RadioGroup>
  <RadioGroup
    label="Confirm Choice"
    value="no" // Example to show error state
    errorMessage="You must select 'Yes' to proceed."
    // isInvalid prop would typically be used here if available on RadioGroup
  >
    <Radio value="yes">Yes, I confirm</Radio>
    <Radio value="no">No, I do not confirm</Radio>
  </RadioGroup>
</View>

Disabled State

Disable the entire group with isDisabled on RadioGroup, or disable individual Radio components.

MyComponent.tsx

<View style={{gap: 16}}>
  <RadioGroup label="Disabled Group" isDisabled>
    <Radio value="a">Option A (Inherits disabled)</Radio>
    <Radio value="b">Option B (Inherits disabled)</Radio>
  </RadioGroup>
  <RadioGroup label="Group with one disabled Radio">
    <Radio value="c">Option C (Enabled)</Radio>
    <Radio value="d" isDisabled>Option D (Specifically disabled)</Radio>
  </RadioGroup>
</View>

Disable Animation

Set disableAnimation on RadioGroup to turn off selection animations for all child Radio components.

MyComponent.tsx

<RadioGroup label="Animation Options" disableAnimation>
  <Radio value="animated_off">Animation Disabled for this group</Radio>
  <Radio value="another_off">Another one with animation off</Radio>
</RadioGroup>

Styling RadioGroup

Customize RadioGroup slots: base, label, radioWrapper, description, errorMessage.

MyComponent.tsx

<RadioGroup
  label="Styled Radio Group"
  description="This group has custom styles."
  style={{ padding: 10, backgroundColor: '#f0f0f0', borderRadius: 8 }} // Base style for RadioGroup
  styles={{
    label: { color: 'purple', fontSize: 18, fontWeight: 'bold' },
    radioWrapper: { backgroundColor: '#e6e6fa', padding: 8, borderRadius: 4, gap: 12 },
    description: { color: 'green', fontStyle: 'italic' },
    errorMessage: { color: 'orange', fontWeight: '600' }
  }}
>
  <Radio value="style1">Styled Option 1</Radio>
  <Radio value="style2">Styled Option 2</Radio>
</RadioGroup>

RadioGroup Props

PROP	TYPE	DEFAULT	DESCRIPTION
`children`	`ReactNode \| ReactNode[]`	-	The `Radio` components.
`label`	`ReactNode`	-	Label for the radio group.
`color`	`RadioColor`	`'primary'`	Default color for child Radios.
`orientation`	`'horizontal' \| 'vertical'`	`'vertical'`	Layout orientation.
`value`	`string \| number \| null`	-	Controlled selected value.
`defaultValue`	`string \| number \| null`	-	Initial selected value (uncontrolled).
`onValueChange`	`(value) => void`	-	Callback on selection change.
`description`	`ReactNode`	-	Helper text for the group.
`errorMessage`	`ReactNode`	-	Error message for the group.
`styles`	`RadioGroupSlotsStyles`	-	Custom styles for group slots.
`style`	`StyleProp<ViewStyle>`	-	Style for the outermost container.
`disableAnimation`	`boolean`	`false`	Disable selection animation for child Radios.
`isDisabled`	`boolean`	`false`	Disable the entire group.

Radio Component

The Radio component represents a single selectable option within a RadioGroup.

Sizes

Adjust radio button and label size with sm, md (default), or lg on individual Radio components.

MyComponent.tsx

// Size is set on individual Radio components
<RadioGroup label="T-Shirt Size">
  <Radio value="sm" size="sm">Small</Radio>
  <Radio value="md" size="md">Medium (Default)</Radio>
  <Radio value="lg" size="lg">Large</Radio>
</RadioGroup>

Individual Labels & Descriptions

Each Radio can have its own label (via children or label prop) and an optional description.

MyComponent.tsx

<RadioGroup label="User Preferences">
  <Radio value="email_notifications">
    Email Notifications
  </Radio>
  <Radio value="sms_alerts" label="SMS Alerts (Explicit Label)" />
  <Radio value="push_updates" description="Receive updates via push notifications.">
    Push Updates
  </Radio>
  <Radio
    value="newsletter"
    label="Newsletter Subscription"
    description="Monthly news and offers."
  />
</RadioGroup>

Styling Radio

Customize individual Radio slots: base, indicator, indicatorDot, label, labelWrapper, description.

MyComponent.tsx

<RadioGroup label="Radios with Custom Styling">
  <Radio
    value="custom1"
    style={{ paddingVertical: 12, backgroundColor: '#e0ffff', borderRadius: 6 }} // Base style for this Radio
    styles={{
      indicator: { borderColor: 'teal', borderWidth: 3 },
      indicatorDot: { backgroundColor: 'darkcyan' },
      label: { color: 'navy', fontWeight: 'bold' },
      description: { color: 'dodgerblue' },
      labelWrapper: { marginLeft: 12 }
    }}
    description="Custom styled radio."
  >
    Option Alpha
  </Radio>
  <Radio value="custom2">Option Beta (Default Styling)</Radio>
</RadioGroup>

Radio Props

PROP	TYPE	DEFAULT	DESCRIPTION
`value`	`string \| number`	-	Unique value for this radio. Required.
`children`	`ReactNode`	-	Label content if `label` prop is not used.
`label`	`ReactNode`	-	Explicit label for the radio.
`size`	`RadioSize`	`'md'`	Size of the radio. Inherits from group.
`color`	`RadioColor`	Inherited	Color of the radio. Inherits from group.
`description`	`ReactNode`	-	Helper text for this radio option.
`isDisabled`	`boolean`	`false`	Disable this specific radio. Overrides group.
`styles`	`RadioSlotsStyles`	-	Custom styles for radio slots.
`style`	`StyleProp<ViewStyle>`	-	Style for the outermost Pressable container.

Accessibility

Both RadioGroup and Radio components include accessibility features:

RadioGroup has accessibilityRole="radiogroup". Its label prop is used as accessibilityLabel.
Individual Radio components have accessibilityRole="radio".
accessibilityState on Radio includes { checked: isSelected, disabled: isDisabled }.
The label of a Radio (from children or label prop) is used as its accessibilityLabel if it's a string.

InputOTP Select