RadioCardGroup

Library: UDS Base
Repository: github.com/telus/universal-design-system
Package: npmjs.com/package/@telus-uds/components-base
Package version: 1.6.1

<RadioCardGroup
  items={[
    {
      title: 'First item',
      content: <Typography>Additional information about the first item.</Typography>
    },
    {
      title: 'Second item',
      content: <Typography>More information about the second item.</Typography>
    },
    {
      title: 'Second item',
      content: (
        <>
          <Typography>Further info on the third item.</Typography>
          <Typography>This info spans two lines.</Typography>
        </>
      )
    }
  ]}
/>

<RadioCardGroup
  items={[
    {
      title: 'First item',
      content: <Typography>Additional information about the first item.</Typography>
    },
    {
      title: 'Second item',
      content: <Typography>More information about the second item.</Typography>
    },
    {
      title: 'Second item',
      content: (
        <>
          <Typography>Further info on the third item.</Typography>
          <Typography>This info spans two lines.</Typography>
        </>
      )
    }
  ]}
/>

Introduction

import { RadioCardGroup } from '@telus-uds/components-base'

A RadioCardGroup renders a group of RadioCards, which display information with a title and separate content section like a card, but may be selected like a radio button.

Guidance

Use RadioCardGroup where the user needs to select one item from multiple options, and where those options need descriptive content beyond a simple single line of text. For example, for choosing between named options where additional content beyond the name is needed to make a choice.

Alternatives

If the options are fairly simple and can be described in a short phrase, consider Radio
If the options require additional information but it is supplementary or of interest to only a minority of users rather than essential information for a majority, consider Radio with a Tooltip
If the options are very simple and can be described in one or two words or numbers, consider ButtonGroup
If selecting an option simply navigates a user to a new page describing that option, rather than saving a selection in the current page or form, consider using basic cards with ButtonLink

Items

Use the items prop to pass an array of objects describing each RadioCard in the group:

title: main text passed to RadioCard's title prop
content: React content passed to RadioCard's children prop
id: identifier used to store which RadioCard is selected (uses title if undefinded)
onChange: optional function called on selection, in addition to updating the group's selection state

<RadioCardGroup
  items={[
    {
      title: 'First item',
      content: <Typography>Additional information about the first item.</Typography>,
      id: 'first',
      onChange: () => alert('First item selected')
    },
    {
      title: 'Second item',
      content: <Typography>Additional information about the second item.</Typography>,
      id: 'second',
      onChange: () => alert('Second item selected')
    }
  ]}
/>

<RadioCardGroup
  items={[
    {
      title: 'First item',
      content: <Typography>Additional information about the first item.</Typography>,
      id: 'first',
      onChange: () => alert('First item selected')
    },
    {
      title: 'Second item',
      content: <Typography>Additional information about the second item.</Typography>,
      id: 'second',
      onChange: () => alert('Second item selected')
    }
  ]}
/>

Controlled

The selection state may be controlled by a parent by passing checkedId and an onChange function that updates the parent's state. If the component is controlled in this way, checkedId must never be undefined; pass null or an empty string if there is no selection.

function ControlledRadioButtonGroup() {
  const [checkedId, setCheckedId] = useState('')
  return (
    <StackView space={3}>
      <Typography>Currently selected: "{checkedId}"</Typography>
      <RadioCardGroup
        checkedId={checkedId}
        onChange={setCheckedId}
        items={[
          { title: 'First item', content: <Typography>More information here.</Typography> },
          { title: 'Second item', content: <Typography>More information here.</Typography> },
          { title: 'Third item', content: <Typography>More information here.</Typography> }
        ]}
      />
    </StackView>
  )
}

function ControlledRadioButtonGroup() {
  const [checkedId, setCheckedId] = useState('')
  return (
    <StackView space={3}>
      <Typography>Currently selected: "{checkedId}"</Typography>
      <RadioCardGroup
        checkedId={checkedId}
        onChange={setCheckedId}
        items={[
          { title: 'First item', content: <Typography>More information here.</Typography> },
          { title: 'Second item', content: <Typography>More information here.</Typography> },
          { title: 'Third item', content: <Typography>More information here.</Typography> }
        ]}
      />
    </StackView>
  )
}

Uncontrolled

If checkedId is not provided, RadioCardGroup manages its own state. An initial selection may be provided by passing initialCheckedId.

<RadioCardGroup
  initialCheckedId="Second item"
  items={[
    { title: 'First item', content: <Typography>More information here.</Typography> },
    { title: 'Second item', content: <Typography>More information here.</Typography> },
    { title: 'Third item', content: <Typography>More information here.</Typography> }
  ]}
/>

<RadioCardGroup
  initialCheckedId="Second item"
  items={[
    { title: 'First item', content: <Typography>More information here.</Typography> },
    { title: 'Second item', content: <Typography>More information here.</Typography> },
    { title: 'Third item', content: <Typography>More information here.</Typography> }
  ]}
/>

Use in forms

For web forms, the name prop may be used to define the name of the group's <fieldset> and input elements, and legend may be used to provide a title with <legend> type for the fieldset.

<RadioCardGroup
  legend="Choose a product"
  name="product-choice"
  items={[
    {
      title: 'First product',
      id: 'x019',
      content: <Typography>A truly high quality product.</Typography>
    },
    {
      title: 'Second product',
      id: 'y022',
      content: <Typography>Another excellent product.</Typography>
    },
    {
      title: 'Third product',
      id: 'z144',
      content: <Typography>Not as good as the others, to be honest.</Typography>
    }
  ]}
/>

<RadioCardGroup
  legend="Choose a product"
  name="product-choice"
  items={[
    {
      title: 'First product',
      id: 'x019',
      content: <Typography>A truly high quality product.</Typography>
    },
    {
      title: 'Second product',
      id: 'y022',
      content: <Typography>Another excellent product.</Typography>
    },
    {
      title: 'Third product',
      id: 'z144',
      content: <Typography>Not as good as the others, to be honest.</Typography>
    }
  ]}
/>

Validation

Validation state may be set by passing 'error' or 'success' to the validation prop.

function ValidationExample() {
  const [validation, setValidation] = useState(null)
  const validate = (id) => setValidation(['a', 'c'].includes(id) ? 'success' : 'error')
  return (
    <RadioCardGroup
      legend="Choose 'a' or 'c'"
      onChange={validate}
      validation={validation}
      feedback={validation && `${validation === 'success' ? 'Valid' : 'Invalid'} item chosen.`}
      items={[
        { title: 'Option "a"', id: 'a', content: <Typography>A valid example option.</Typography> },
        {
          title: 'Option "b"',
          id: 'b',
          content: <Typography>An invalid example option.</Typography>
        },
        { title: 'Option "c"', id: 'c', content: <Typography>A valid example option.</Typography> },
        {
          title: 'Option "d"',
          id: 'd',
          content: <Typography>An invalid example option.</Typography>
        }
      ]}
    />
  )
}

function ValidationExample() {
  const [validation, setValidation] = useState(null)
  const validate = (id) => setValidation(['a', 'c'].includes(id) ? 'success' : 'error')
  return (
    <RadioCardGroup
      legend="Choose 'a' or 'c'"
      onChange={validate}
      validation={validation}
      feedback={validation && `${validation === 'success' ? 'Valid' : 'Invalid'} item chosen.`}
      items={[
        { title: 'Option "a"', id: 'a', content: <Typography>A valid example option.</Typography> },
        {
          title: 'Option "b"',
          id: 'b',
          content: <Typography>An invalid example option.</Typography>
        },
        { title: 'Option "c"', id: 'c', content: <Typography>A valid example option.</Typography> },
        {
          title: 'Option "d"',
          id: 'd',
          content: <Typography>An invalid example option.</Typography>
        }
      ]}
    />
  )
}

RadioCardGroup accepts all the common accessibility props, but also sets accessibility role 'radiogroup' and controls the accessibility state of children like RadioCard and Feedback based on current state.

RadioCard component accepts all the common accessibility props, but also sets some defaults, including accessibility role 'radio' and accessibility state that depends on the other props (checked, inactive) or the internal state in case of uncontrolled RadioCard.

Props

Name	Type	Default	Description
items	arrayOf	[]	Array of objects containing specifics for each RadioCard to be rendered in the group.
tokens	custom		System tokens prop, see tokens for more details
radioCardTokens	custom		Optional theme token overrides for each inner RadioCard component
variant	objectOf		System variant prop, see variants for more details
legend	string		Main text used to describe this group, used in Fieldset's Legend element.
hint	string		Optional additional text giving more detail to help a user make a choice.
tooltip	string		Optional tooltip text content to include alongside the legend and hint.
validation	'error' \| 'success'		Current validation status of the group, passed to the feedback element if there is one.
feedback	string		If provided, a Feedback element is rendered containing this text.
initialCheckedId	string		If provided, the radio card with this id is selected on first render.
checkedId	string		If not undefined, the radio card with this id is selected (or none is selected if `null`), and the element's selection state will be controlled by its parent using the `onChange` function.
onChange	func		Function to call on change in selection state. Is required if the selection state is controlled by a parent using checkedId and the input is not readOnly.
readOnly	bool		If true, the radio cards cannot be selected by the user and simply show their current state.
inactive	bool		If true, the radio card cannot be interacted with, elements are set as `disabled` and if the theme supports `inactive` appearances rules, these are applied.
name	string		On Web, this is passed to the `name` attribute of the fieldset and each radio input.

RadioCardGroup

Introduction​

Guidance​

Alternatives​

Items​

Controlled​

Uncontrolled​

Use in forms​

Validation​

A11y guidelines​

Props​