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 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, RadioGroupContext, useRadioGroupContext } from '@/crossbuildui/radio';

The isGlass feature for RadioGroup (which styles the individual radio indicators) uses expo-blur. Ensure this library is installed and linked if you plan to use this feature. Animations also rely on react-native-reanimated.

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>

Glass Indicator Effect

Apply a frosted glass effect to the background of selected radio indicators using the isGlass prop on RadioGroup. Customize it with glassIntensity (0-100) and glassTint ('light', 'dark', 'default'). The indicator's border and dot colors adapt for better contrast on the blurred background. This effect is applied to the individual Radio indicators within the group.

MyComponent.tsx

<View style={{gap: 16}}>
  <RadioGroup
    label="Light Glass Radios"
    defaultValue="opt1"
    isGlass
    glassIntensity={70}
    glassTint="light"
  >
    <Radio value="opt1">Option 1 (Light Glass)</Radio>
    <Radio value="opt2">Option 2 (Light Glass)</Radio>
  </RadioGroup>
  <RadioGroup
    label="Dark Glass Radios"
    defaultValue="optA"
    isGlass
    glassIntensity={40}
    glassTint="dark"
  >
    <Radio value="optA" description="Selected indicator dot will be theme foreground">Option A (Dark Glass)</Radio>
    <Radio value="optB">Option B (Dark Glass)</Radio>
  </RadioGroup>
</View>

Using RadioGroup Context

For advanced scenarios or creating custom components that interact deeply with the RadioGroup, you can use the useRadioGroupContext hook. This hook provides access to the RadioGroupContext, which includes properties like name (group identifier), selectedValue, setSelectedValue (setter function), color, size, orientation, isDisabled, and glass props.

Any component calling useRadioGroupContext must be a descendant of a RadioGroup component. This allows for building custom layouts or informational displays related to the group's state.

Context Usage Note

Directly calling setSelectedValue from deep children might make state flow harder to track. Prefer standard Radio interactions where possible.

MyCustomRadioGroupComponent.tsx

import { RadioGroup, Radio, useRadioGroupContext } from '@/crossbuildui/radio';
import { Text, View } from 'react-native';

const RadioGroupInfo = () => {
  const context = useRadioGroupContext();

  if (!context) {
    return <Text>This component must be used within a RadioGroup.</Text>;
  }

  const { name, selectedValue, color, size, orientation, isDisabled } = context;

  return (
    <View style={{ marginTop: 8, padding: 8, backgroundColor: '#f0f0f0', borderRadius: 4 }}>
      <Text>RadioGroup Context Info (Name: {name}):</Text>
      <Text>- Selected: {selectedValue ?? 'None'}</Text>
      <Text>- Color: {color}, Size: {size}, Orientation: {orientation}</Text>
      <Text>- Disabled: {isDisabled ? 'Yes' : 'No'}</Text>
    </View>
  );
};

// <RadioGroup label="Options" color="success" size="sm"><Radio value="1">One</Radio><RadioGroupInfo /></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.
`isGlass`	`boolean`	`false`	Apply glassmorphism to selected radio indicators.
`glassTint`	`'default' \| 'light' \| 'dark'`	Theme-derived	Tint for the glass effect on indicators.
`glassIntensity`	`number`	30	Intensity (0-100) for the glass effect on indicators.

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.

If isGlass is enabled on the parent RadioGroup, the indicator style's backgroundColor will be transparent when selected, allowing the BlurView to show through. The indicatorDot color will adapt to the theme's foreground for contrast.

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