Skip to main content

Radio

The Radio component is used when only one choice may be selected in a series of options.

Import#

Pearl UI exports 2 radio-related components:

  1. Radio: A single radio which can be selected.
  2. RadioGroup: A wrapper which stacks multiple Radio components together and provides a central place to control their state.
import { Radio, RadioGroup } from "pearl-ui";

Usage#

const [checked, setIsChecked] = React.useState(false)
<Radio isChecked={checked} onPress={() => setIsChecked(true)}>Check Me!</Radio>

Radio group#

A RadioGroup component exists to help manage the checked state of its children Radio components and conveniently pass a few shared style props to each as follows:

const [radioGroupValue, setRadioGroupValue] = React.useState([])
<RadioGroup  size="s"  colorScheme="secondary"  defaultValue="1"  value={radioGroupValue}  onChange={(value) => {    setRadioGroupValue(value);  }}>  <Stack direction="vertical" spacing="xs">    <Radio value="1">Value 1</Radio>    <Radio value="2">Value 2</Radio>    <Radio value="3">Value 3</Radio>    <Radio value="4">Value 4</Radio>  </Stack></RadioGroup>

Radio sizes#

Use the size prop to change the size of the radio. You can set the value to the keys available in PearlTheme.components.Radio["sizes"], which are "s", "m", "l", and "xl" in the default theme.

<Radio size="s">Small Radio</Radio>
<Radio size="m">Regular Radio</Radio>
<Radio size="l">Large Radio</Radio>
<Radio size="xl">Extra Large Radio</Radio>

Radio variants#

Use the variant prop to change the visual style of the radio. You can set the value to the keys available in PearlTheme.components.Radio["variants"], which are "filled" and "outline" in the default theme.

<Radio variant="filled">Filled Radio</Radio>
<Radio variant="outline">Outline Radio</Radio>

Radio color scheme#

Use the colorScheme prop to change the color palette of the radio. This is much more powerful than simply passing a backgroundColor style prop as the colorScheme prop changes all the use color values in a palette through a single prop.

You can set the value only to the keys available in PearlTheme.palette that contain a palette of colors represented as an object, which are "primary", "secondary", "neutral", etc in the default Pearl theme.

<Radio colorScheme="primary">Primary Radio</Radio>
<Radio colorScheme="secondary">Secondary Radio</Radio>

Radio checked state#

The isChecked prop is used to define whether the radio is in an active state.

Radio also allows you to update the visual style of the radio when it is checked using some special props prefixed with the word checked.

<Radio isChecked checkedBackgroundColor="cyan" checkedBorderColor="violet">  I am checked!</Radio>

Radio error state#

Similar to the checked state, you can add an error state to the radio based on any validation criteria you use along with special visual styles to go along with it by using some special props prefixed with the word error. The isInvalid prop is used to define whether the radio has an error.

You can also pass the errorMessage prop to add a helper text describing the error below the radio.

<Radio  isInvalid  errorBackgroundColor="pink"  errorBorderColor="red">  Error Radio</Radio>
<Radio  isInvalid  errorBackgroundColor="cyan"  errorBorderColor="violet"  errorMessage="This is an error message!">  Error Radio with message</Radio>

Changing the spacing#

You can use the spacing prop to customize the spacing between the radio and label text. You can set the value to the keys available in PearlTheme.spacing, which are "xs", "s", "l", etc. in the default Pearl theme. By default, this value equals to "xs".

<Radio spacing="l">Radio with lots of spacing</Radio>
<Radio spacing="xs">Radio with less spacing</Radio>

Override Style#

The Radio component also supports a variety of style props which can be used to override the pre-defined variant style in the theme. Manual style props passed into the component have a higher precedance than the default component config.

// passing style prop marginTop="l" adds a top margin to the radio<Radio variant="outline" marginTop="l" borderWidth={2} borderColor="green">  Check Me!</Radio>

Example#

Accessibility#

  • Radio has the role of radio, while the RadioGroup has the role of radiogroup.
  • When Radio is disabled or checked, it is reflected as disabled and checked respectively in screen readers.
  • Radio has the default accessibility label set as the label text passed into it. A custom label can be specified using the accessibilityLabel prop.

Radio Props#

Supported style props#

Radio composes the Stack component, you can pass all Stack props to it.

Additional props#

NameRequiredTypeDefaultDescription
sizefalsePearlTheme.components.Radio["sizes"]"m"Size of the radio.
variantfalsePearlTheme.components.Radio["variants"]"filled"Variant of the radio.
valuefalsestring | number | undefinedValue of the radio if it is part of a group.
isDisabledfalsebooleanfalseWhether the radio is disabled.
isCheckedfalsebooleanfalseWhether the radio is in a checked state.
isInvalidfalsebooleanfalseWhether the radio is in an error state.
errorMessagefalsestringThe error message to be displayed if the radio is in an error state.
colorSchemefalsePearlTheme.palette"primary"Active color palette of the radio.
spacingfalsePearlTheme.spacing"xs"The spacing between the radio and the label text.
checkedBackgroundColorfalsePearlTheme.palette"primary.500"The background color of the radio when it is in checked state.
checkedBorderColorfalsePearlTheme.palette"primary.500"The border color of the radio when it is in checked state
checkedBorderStartColorfalsePearlTheme.paletteThe border start color of the radio when it is in checked state.
checkedBorderEndColorfalsePearlTheme.paletteThe border end color of the radio when it is in checked state.
checkedBorderTopColorfalsePearlTheme.paletteThe border top color of the radio when it is in checked state.
checkedBorderLeftColorfalsePearlTheme.paletteThe border left color of the radio when it is in checked state.
checkedBorderRightColorfalsePearlTheme.paletteThe border right color of the radio when it is in checked state.
checkedBorderBottomColorfalsePearlTheme.paletteThe border bottom color of the radio when it is in checked state.
errorBackgroundColorfalsePearlTheme.paletteThe background color of the radio when it is in an error state.
errorBorderColorfalsePearlTheme.palette"danger.500"The border color of the radio when it is in an error state
errorBorderStartColorfalsePearlTheme.paletteThe border start color of the radio when it is in an error state.
errorBorderEndColorfalsePearlTheme.paletteThe border end color of the radio when it is in an error state.
errorBorderTopColorfalsePearlTheme.paletteThe border top color of the radio when it is in an error state.
errorBorderLeftColorfalsePearlTheme.paletteThe border left color of the radio when it is in an error state.
errorBorderRightColorfalsePearlTheme.paletteThe border right color of the radio when it is in an error state.
errorBorderBottomColorfalsePearlTheme.paletteThe border bottom color of the radio when it is in an error state.

RadioGroup Props#

Supported style props#

RadioGroup composes the Box component, you can pass all Box props to it.

Additional props#

NameRequiredTypeDefaultDescription
sizefalsePearlTheme.components.Radio["sizes"]"m"Size of all the children radio in the group.
variantfalsePearlTheme.components.Radio["variants"]"filled"Variant of all the children radio in the group.
valuefalsestring | numberActive value of the radio group.
defaultValuefalsestring | numberDefault active value of the radio group.
onChangefalse(value: string | number) => voidMethod that gets invoked when the value of the radio group changes.
isDisabledfalsebooleanfalseWhether the radio group is disabled.
colorSchemefalsePearlTheme["palette"]"primary"Active color palette of all the children radio in the group.

Default component Config#

export default {  parts: ["root", "outerBox", "innerBox", "text", "errorText"],  baseStyle: {    root: {      my: "2xs",      spacing: "xs",    },    outerBox: {      errorBorderColor: "danger.500",      borderRadius: "full",    },    innerBox: {      borderRadius: "full",    },    errorText: {      variant: "caption",      color: "danger.500",      marginBottom: "2xs",    },  },  sizes: {    s: {      outerBox: {        width: 18,        height: 18,        style: { padding: 3 },      },      text: {        variant: "p2",      },    },    m: {      outerBox: {        width: 24,        height: 24,        style: { padding: 5 },      },      text: {        variant: "p2",      },    },    l: {      outerBox: {        width: 30,        height: 30,        style: { padding: 7 },      },      text: {        variant: "p1",      },    },    xl: {      outerBox: {        width: 36,        height: 36,        style: { padding: 9 },      },      text: {        variant: "p1",      },    },  },  variants: {    filled: {      outerBox: {        borderWidth: 2,        checkedBackgroundColor: "primary.500",        backgroundColor: {          light: "neutral.200",          dark: "neutral.900",        },        borderColor: {          light: "neutral.200",          dark: "neutral.600",        },        checkedBorderColor: "primary.500",      },      innerBox: {        backgroundColor: {          light: "neutral.200",          dark: "neutral.900",        },        checkedBackgroundColor: "neutral.50",      },    },    outline: {      outerBox: {        borderWidth: 2,        checkedBackgroundColor: {          light: "neutral.50",          dark: "neutral.800",        },        backgroundColor: {          light: "neutral.50",          dark: "neutral.800",        },        checkedBorderColor: "primary.500",        borderColor: {          light: "neutral.400",          dark: "neutral.500",        },      },      innerBox: {        backgroundColor: {          light: "neutral.50",          dark: "neutral.800",        },        checkedBackgroundColor: "primary.500",      },    },  },  defaults: {    size: "m",    variant: "filled",  },};