Radio

What is this?

Radio controls allow merchants to make a single choice in a group with at most five options.

Help Text

Loading...

Group Help Text

Loading...

Direction

Loading...

Disabled

Loading...

Error

Use the error prop to define whether user input causes an error or not. It is up to you to determine what triggers it. Additionally, you should add errorText to be displayed.

Loading...

Optional

Loading...

Usage

import { Radio, RadioGroup, useRadioState } from '@vtex/admin-ui'

function Example() {
  const state = useRadioState()

  return (
    <RadioGroup state={state} label="Group label">
      <Radio value="radio-1" label="Label" />
      <Radio value="radio-2" label="Label" />
      <Radio value="radio-3" label="Label" />
    </RadioGroup>
  )
}

Radio Props

Name	Type	Description	Required	Default
value	string, number	The value to be used in the radio button. This is the value that will be returned on form submission.	✅	-
label	string	Radio label	✅	-
helpText	ReactNode	Help text	🚫	-
checked	boolean	Same as the HTML checked attribute	🚫	-
disabled	boolean	Whether is disabled or not	🚫	false
id	string	Same as the HTML attribute	🚫	-
csx	StyleProp	Defines component styles	🚫	{}

RadioGroup Props

Name	Type	Description	Required	Default
state	RadioState	Return of useRadioState hook	✅	-
label	string	Group label	✅	-
helpText	ReactNode	Help text	🚫	-
errorText	ReactNode	Error text	🚫	-
error	boolean	Whether the filed is error or not	🚫	false
direction	row, column	Direction which the children are displayed	🚫	row
optional	ReactNode	Whether the field is optional or not	🚫	-
csx	StyleProp	Defines component styles	🚫	{}

useRadioState

A hook to help control the RadioGroup state.

Params Props

Name	Type	Description	Required	Default
defaultValue	string, number	The initial value of the radio group.	🚫	-
setValue	(value: RadioState["value"]) => void	Function that will be called when setting the radio value state.	🚫	-

Return Props

Name	Type	Description	Required	Default
value	string, number, null	The initial value of the radio group.	🚫	-
setValue	SetState<RadioState["value"]>	Sets the value state.	🚫	-

Accessibility

`Radio` has the role `radio`.
`RadioGroup` has role `radiogroup`.
`Radio` has `aria-checked` set to `true` when it's checked. Otherwise, `aria-checked` is set to `false`.
Always use `Radio` within a `RadioGroup`.

Components

When to use the Select, Checkbox, or Combobox Single components instead of the Radio component?

• Choose the Select component if a single option can be selected and more than five options are available.
• Choose the Checkbox component if more than one option can be selected and there are up to five options.
• Choose the Combobox Single component if a single option can be selected and there are more than five available options.

When to use a vertical or a horizontal Radio Group?

It is more scalable to distribute options in a vertical direction. Only distribute horizontally if — considering localization — all their labels fit in a single line, have up to 20 characters and don’t vary a lot in length.

When to use a Radio instead of a Radio Group?

Never use a single Radio control. It only exists as a separate component to make the component construction and design documentation easier to understand.

Position

How should a Radio component be positioned in a form?

Prefer placing a Radio at the start or end of a form section. However, if the selection affects the state of other fields, place the Radio Group close to the fields it will affect.

Behavior

What should be the default value of a Radio?

• Preselect an option when this can make the merchant more efficient and when it isn’t important for the choice to be conscious.
• Common or recommended options can be preselected. Information that the merchant has previously provided can be preselected to indicate the option that should be chosen.
• When a recommended option is preselected, add (Recommended) to the end of its label so it can still be identified after edits.

When should a Radio be disabled?

• Use a disabled Radio only if, in some condition, it becomes enabled. For example, when an option is incompatible with another option in a form.
• Use a tooltip trigger to explain why the Radio is disabled. Display the information when hovering over the tooltip trigger — not the Radio itself.

When should a Radio Group be optional?

A Radio Group should be optional when its options may not apply. For example, preferences for notifications can be left unselected if the merchant doesn’t want to receive them. Consider adding a Custom option together with fields to capture the merchant’s needs.

Content

What should be the label of a Radio Group?

• Include the name of the entity that is being listed. For example, use the label Fruits when the options are Apple, Orange, and Banana.
• Visually hide the label of the Radio Group when the form section title already contains the name of the entity being listed.
• Use sentence case, but capitalize proper nouns.

What to avoid:

• Don't include redundant words. For example, don't use Product characteristics as the label for a Radio Group inside a form page that includes Product in its title – use only Characteristics.
• Don't use verbs. For example, instead of Select characteristics, use only Characteristics.
• Don't use interrogations.

What should be the order of options in a Radio Group?

Order them using one of the following criteria:

• Most to least frequently used.
• Simplest to most complex.
• Least to most risky.
• Alphabetical order.

What should be the label of a Radio?

• Write the label so that it corresponds to the value of the Radio.
• Use sentence case, but capitalize proper nouns.

What to avoid:

• Don't write Radio labels that vary a lot in length between options.
• Don't write long Radio labels. Use the help text or the Radio Group label to provide additional context when necessary.
• Don't use personal pronouns. For example, write Personal email instead of My email.
• Don't include redundant words. For example, use only S, M, and L instead of Size S, Size M, and Size L.

What should be the help text of a Radio or a Radio Group?

• Include a help text only for critical choices where the consequences of choosing the option need to be explained in more detail.
• Write the help text as if completing the following sentence: If you check this option, you or the system will [help text].
• Start with verbs in the simple present tense. For example, for the value Fragile the help text should be Prints this information on the shipping label and not Print this information on the shipping label.
• Use sentence case but capitalize proper nouns.

What to avoid:

• Don’t include links. Use an alert component if this is necessary.
• Don’t write more than one sentence.
• Don’t use periods or commas.

What should be the error text of a Radio or a Radio Group?

• Prevent errors whenever possible. When an option is selected, disable other incompatible fields or options automatically.
• In a Radio Group, if at least one option needs to be selected and none is chosen, the error text should be Select at least one option.
• Use the imperative form. For example, write Select at least one option instead of At least one option needs to be selected.

What to avoid:

• Don’t use periods or commas.
• Don't use incomplete sentences. For example, write Select at least one option instead of Select at least one.

• What is this?
• Help Text
• Group Help Text
• Direction
• Disabled
• Error
• Optional