Radio group API

Import

Cimpress UI exports two radio-related components:

RadioGroup: container component that groups related radio buttons together, providing a shared label, optional description, error handling, and state management.
Radio: component to display a radio button within a radio group.

import { Radio, RadioGroup } from '@cimpress-ui/react';

Controlled/uncontrolled usage

This component can be used in a controlled or uncontrolled way.

In the controlled way, this component doesn’t maintain its own internal state, and its value is provided by the parent component. Use the controlled way when you need to be able to change the state of this component in other parts of your application.

In the uncontrolled way, this component maintains its own internal state, and can optionally notify the parent component when its internal state changes. Use the uncontrolled way when you don’t need to change the state of this component in other parts of your application.

Preview
Code

import { Radio, RadioGroup, Stack } from '@cimpress-ui/react';
import { useState } from 'react';

export default function Demo() {
  const [value, setValue] = useState('apple');

  return (
    <Stack gap={32}>
      <RadioGroup label="Favorite fruit (controlled)" value={value} onChange={setValue}>
        <Radio value="apple">Apple</Radio>
        <Radio value="banana">Banana</Radio>
        <Radio value="cherry">Cherry</Radio>
      </RadioGroup>

      <RadioGroup label="Favorite fruit (uncontrolled)" defaultValue="apple">
        <Radio value="apple">Apple</Radio>
        <Radio value="banana">Banana</Radio>
        <Radio value="cherry">Cherry</Radio>
      </RadioGroup>
    </Stack>
  );
}

Accessibility notes

Radio cannot be used on its own, and must always be a child of RadioGroup.

RadioGroup is a single tab stop within the page’s tab order. Use the Tab key to navigate to the group, and the arrow keys to navigate between radio buttons within the group.

Radio and RadioGroup require textual labels to remain accessible to assistive technologies. See our accessibility guide for more details.

API reference

Radio

Renders a single option within RadioGroup.

See radio group usage guidelines.

ref Ref<HTMLLabelElement>: The ref type for this component.

RadioProps

value * string: The value of the radio button, used when submitting an HTML form. See MDN.
children StringLikeChildren: The label rendered next to the radio.
id string: The element's unique identifier. See MDN.
data-cim-style-root boolean: Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.
UNSAFE_className string: Sets the CSS className for the element. Only use as a last resort. Use style props instead.

See styling guide.
UNSAFE_style CSSProperties: Sets the CSS style for the element. Only use as a last resort. Use style props instead.

See styling guide.
aria-label string: Defines a string value that labels the current element.
aria-labelledby string: Identifies the element (or elements) that labels the current element.
aria-describedby string: Identifies the element (or elements) that describes the object.
aria-details string: Identifies the element (or elements) that provide a detailed, extended description for the object.
isDisabled boolean: Whether the radio button is disabled or not. Shows that a selection exists, but is not available in that circumstance.
autoFocus boolean: Whether the element should receive focus on render.

StyleProps

margin Responsive<Spacing | "auto">: The amount of margin applied to all edges of this component.
marginX Responsive<Spacing | "auto">: The amount of margin applied to the left and right edges of this component. Takes priority over margin.
marginY Responsive<Spacing | "auto">: The amount of margin applied to the top and bottom edges of this component. Takes priority over margin.
marginTop Responsive<Spacing | "auto">: The amount of margin applied to the top edge of this component. Takes priority over marginY and margin.
marginRight Responsive<Spacing | "auto">: The amount of margin applied to the right edge of this component. Takes priority over marginX and margin.
marginBottom Responsive<Spacing | "auto">: The amount of margin applied to the bottom edge of this component. Takes priority over marginY and margin.
marginLeft Responsive<Spacing | "auto">: The amount of margin applied to the left edge of this component. Takes priority over marginX and margin.

RadioGroup

Allows users to select a single item from a visible list.

See radio group usage guidelines.

ref Ref<HTMLDivElement>: The ref type for this component.

RadioGroupProps

children * ReactNode: Radio buttons belonging to the group.
label * string: The content to display as the label.
direction Responsive<Direction>: Determines the direction in which radio buttons will be stacked.

Defaults to 'vertical' .
id string: The element's unique identifier. See MDN.
data-cim-style-root boolean: Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.
UNSAFE_className string: Sets the CSS className for the element. Only use as a last resort. Use style props instead.

See styling guide.
UNSAFE_style CSSProperties: Sets the CSS style for the element. Only use as a last resort. Use style props instead.

See styling guide.
aria-label string: Defines a string value that labels the current element.
aria-labelledby string: Identifies the element (or elements) that labels the current element.
aria-describedby string: Identifies the element (or elements) that describes the object.
aria-details string: Identifies the element (or elements) that provide a detailed, extended description for the object.
name string: The name of the input element, used when submitting an HTML form. See MDN.
description string: A description for the field. Provides a hint such as specific requirements for what to choose.
error FieldError: An error message for the field.
validate (value: null | string) => undefined | string | true | string[]: A function that returns an error message (or true) if a given value is invalid. Validation errors are displayed to the user when the form is submitted. For real-time validation, use the error prop instead.
isRequired boolean: Whether user input is required on the input before form submission.
isInvalid boolean: Whether the input value is invalid.
isDisabled boolean: Whether the input is disabled.
isReadOnly boolean: Whether the input can be selected but not changed by the user.
value null | string: The current value (controlled).
defaultValue null | string: The default value (uncontrolled).
onChange (value: string) => void: Handler that is called when the value changes.

StyleProps

margin Responsive<Spacing | "auto">: The amount of margin applied to all edges of this component.
marginX Responsive<Spacing | "auto">: The amount of margin applied to the left and right edges of this component. Takes priority over margin.
marginY Responsive<Spacing | "auto">: The amount of margin applied to the top and bottom edges of this component. Takes priority over margin.
marginTop Responsive<Spacing | "auto">: The amount of margin applied to the top edge of this component. Takes priority over marginY and margin.
marginRight Responsive<Spacing | "auto">: The amount of margin applied to the right edge of this component. Takes priority over marginX and margin.
marginBottom Responsive<Spacing | "auto">: The amount of margin applied to the bottom edge of this component. Takes priority over marginY and margin.
marginLeft Responsive<Spacing | "auto">: The amount of margin applied to the left edge of this component. Takes priority over marginX and margin.