Radio - Web

For development, import Radio from @servicetitan/anvil2. For design, find it in the Anvil2 file.

Anatomy

The Radio uses two primary elements to help users select one option from a set of choices, the radio itself, and its corresponding label.

Radio button
Label

Options

Configure the Radio to accommodate the following scenarios:

States

Default

Disabled

Description

Descriptions provide information to help the user avoid errors.

Behavior

The Radio uses standard form control behaviors.

Usage Guidelines

Standard	Requirement
DoChoose from small option sets	Use Radio buttons to choose between small sets of items, usually 5 or fewer. Since all options are always visible, users can quickly scan and compare them. You can provide additional context through helper text or a help tooltip to help users choose accurately.
DoUse for 2–7 options	Generally use Radio buttons when there are 2–7 options.
DoSimple in-form selection lists	For simple selection lists in a form, use a Radio.
DoControls that need explicit submission	Radio buttons are form controls that require explicit submission.
DoUse in form layouts for multiple options	Radio buttons let users choose from two or more options and require form submission. Use Radio buttons in form layouts when users select between multiple options.
DoMutually exclusive single-select	Use Radio buttons to select a single option from mutually exclusive choices.
DoGroup related Radios	Group related Radio buttons together in a Radio Group. In most cases, include a label.
DoProvide a default option	Provide a default option in a Radio Group when possible. This signals that a selection is required, can expedite tasks, and guides users toward a recommended option. Source: Nielsen Norman.
DoReveal a Text Field for “Other”	When a Radio Group includes an “Other” option, selecting it should reveal a Text Field so users can enter custom text.
Don’tUse for 8+ options	Use a Combobox instead when there are 8 or more options.
Don’tOverlay selection lists	For selection lists that need to be an overlay, use a Listbox with a Combobox instead.
Don’tUse when selection should apply immediately	Segmented Controls apply selection immediately to the UI; use one of those instead when immediate effect is needed.
Don’tUse for an immediate two-state toggle	A Switch toggles between two states and takes effect immediately; use a Switch instead for that.
Don’tUse for multi-select choices	Use Checkboxes instead to make zero to many selections from available options.
Don’tDefault when it risks unexpected effects	Avoid a default selection when it could lead to unexpected downstream effects.

Content

Radio content should clearly communicate options and provide context for informed decisions.

The Radio Group’s title and description communicate its main purpose

Titles should clearly communicate the Radio Group’s purpose at a glance. Descriptions provide additional context about the decision users need to make.

Don’t

Use descriptive Radio input labels

Users rely on labels to understand what each Radio input controls. Use positive, active wording for Radio input labels. Use sentence case (capitalize only the first word and proper nouns) so control labels are easy to scan. Do not use periods for short phrases or single sentences. “Leaky bathroom faucet"
"Clogged kitchen drain"
"No hot water"
"Slow shower drain"
"Overflowing toilet”

“Fix water problem"
"Plumbing emergency"
"Water not working"
"Broken pipe"
"Plumbing issue”

Don’t

Give users the information they need to make an informed decision

When a label doesn’t provide enough context, use descriptions to give users the relevant details they need to decide. Don’t add descriptions when unneeded or solely to match other inputs. Use sentence case, and only include period if more than one sentence is used. Follow the inline help content guidelines.

Don’t

Keyboard Interaction

Navigate the Radio using standard keyboard controls.

Key	Interaction
Arrow keys	Navigate and selects Radios

Accessibility

Include Radio buttons in a Radio Group with multiple mutually exclusive options.
Provide a visible label for each Radio button.
When a Radio button has an error, include helper text to describe the error.

For more guidance on form field labels and context, see input field context association best practices.

Code

Implementation
Radio Props
Radio.Group Props

Common Examples

import { Radio } from "@servicetitan/anvil2";

function ExampleComponent() {
  return (
    <Radio.Group Group legend="Preferred method of communication">
      <Radio name="comm" label="Email" defaultChecked />
      <Radio name="comm" label="Phone" />
      <Radio name="comm" label="Text" />
    </Radio.Group>
  );
}

Basic radio input

The Radio component accepts many of the same props as an HTML input with type="radio", such as name, value, checked, and defaultChecked.

Controlling radio state

Use the checked and onClick props to manually control the state of a radio.

Using radio groups

The Radio.Group component acts as a wrapper around a collection of Radio components.

React Accessibility

The Radio component’s label prop allows for any ReactElement to be passed in, but the label should always be populated with some text content that is screen-reader accessible.

For more guidance on form field labels and context, see input field context association best practices.

Markdown in legends

The Radio.Group legend prop supports inline markdown: bold (**text**), italic (*text*), bold and italic (***text***), highlight (==text==), and code (`text`).

Hide the legend

Use hideLabel on Radio.Group to visually hide the legend. The legend string is kept as a screen-reader-only <legend> element so the group remains accessible — any inline markdown is stripped to plain text.

<Radio
  name="option"
  label="Option 1"
  value="option1"
  defaultChecked={false}
  checked={false}
  error={false}
  icons={{ checked: CheckIcon, unchecked: UncheckIcon }}
  onChange={(e, state) => console.log(state)}
/>

`Radio` Props

In addition to the props listed below, the Radio component can accept any valid HTML input props.

(e: ChangeEvent, state: { checked: boolean; value: string | string[] | number }) => void

required

Callback when the radio is changed.

boolean

default:"false"

Controlled checked state.

boolean

default:"false"

Uncontrolled checked state.

string

Description text to display below the radio.

boolean

Error state for the radio.

{ checked?: Svg; unchecked?: Svg }

Overrides for default icons.

ReactElement | string

The label should have accessible string content.

<Radio.Group
  legend="Select an option"
  moreInfo="Additional information"
  required={false}
>
  <Radio name="option" label="Option 1" />
  <Radio name="option" label="Option 2" />
</Radio.Group>

`Radio.Group` Props

In addition to the props listed below, the Radio.Group component can accept any valid HTML fieldset props.

ReactElement | string

required

The legend for the radio group. Supports inline markdown formatting.

Passing ReactElement is deprecated — use a plain string with inline markdown instead.

boolean

default:"false"

Visually hides the legend while keeping it accessible to screen readers.

Omit<FieldLabelProps, "el">

Additional props to pass to the legend FieldLabel component. Supports the aiMark prop for displaying AI-powered field indicators.

boolean

Concepts & Guidelines

Anvil2

Resources

Radio - Web

Anatomy

Options

States

Default

Disabled

Description

Behavior

Usage Guidelines

Content

The Radio Group’s title and description communicate its main purpose

Use descriptive Radio input labels

Give users the information they need to make an informed decision

Keyboard Interaction

Accessibility

Code

Common Examples

Basic radio input

Controlling radio state

Using radio groups

React Accessibility

Markdown in legends

Hide the legend

`Radio` Props

`Radio.Group` Props

​Anatomy

​Options

​States

​Default

​Disabled

​Description

​Behavior

​Usage Guidelines

​Content

​The Radio Group’s title and description communicate its main purpose

​Use descriptive Radio input labels

​Give users the information they need to make an informed decision

​Keyboard Interaction

​Accessibility

​Code

​Common Examples

​Basic radio input

​Controlling radio state

​Using radio groups

​React Accessibility

​Markdown in legends

​Hide the legend

​Radio Props

​Radio.Group Props

Anatomy

Options

States

Default

Disabled

Description

Behavior

Usage Guidelines

Content

The Radio Group’s title and description communicate its main purpose

Use descriptive Radio input labels

Give users the information they need to make an informed decision

Keyboard Interaction

Accessibility

Code

Common Examples

Basic radio input

Controlling radio state

Using radio groups

React Accessibility

Markdown in legends

Hide the legend

`Radio` Props

`Radio.Group` Props