Radio button
Use radio buttons to present each item in a list of options where merchants must make a single selection.
Use radio buttons where merchants must make a single selection.
import{LegacyStack,RadioButton}from'@shopify/polaris';import{useState,useCallback}from'react';functionRadioButtonExample(){const[value,setValue]=useState('disabled');consthandleChange=useCallback((_:boolean,newValue:string)=>setValue(newValue),[],);return(<LegacyStackvertical><RadioButtonlabel="Accounts are disabled"helpText="Customers will only be able to check out as guests."checked={value==='disabled'}id="disabled"name="accounts"onChange={handleChange}/><RadioButtonlabel="Accounts are optional"helpText="Customers will be able to check out with a customer account or as a guest."id="optional"name="accounts"checked={value==='optional'}onChange={handleChange}/></LegacyStack>);}
Props
Want to help make this feature better? Pleaseshare your feedback.
- ariaDescribedBy? string
-
Indicates the ID of the element that describes the the radio button.
- label React.ReactNode
-
Label for the radio button.
- labelHidden? boolean
-
Visually hide the label.
- checked? boolean
-
Radio button is selected.
- disabled? boolean
-
Disable input.
- id? string
-
表单输入ID。
- name? string
-
Name for form input.
- value? string
-
Value for form input.
- onChange? (newValue:boolean,id:string) =>void
-
Callback when the radio button is toggled.
- onFocus? () =>void
-
Callback when radio button is focused.
- onBlur? () =>void
-
Callback when focus is removed.
- fill? T|({ [BreakpointinBreakpointsAlias]?:T; })<T><boolean>
-
Grow to fill the space. Equivalent to width: 100%; height: 100%.
- helpText? React.ReactNode
-
Additional text to aide in use.
- bleed? Spacing
-
Spacing around children. Accepts a spacing token or an object of spacing tokens for different screen sizes.
- bleedBlockStart? Spacing
-
Vertical start spacing around children. Accepts a spacing token or an object of spacing tokens for different screen sizes.
- bleedBlockEnd? Spacing
-
Vertical end spacing around children. Accepts a spacing token or an object of spacing tokens for different screen sizes.
- bleedInlineStart? Spacing
-
Horizontal start spacing around children. Accepts a spacing token or an object of spacing tokens for different screen sizes.
- bleedInlineEnd? Spacing
-
Horizontal end spacing around children. Accepts a spacing token or an object of spacing tokens for different screen sizes.
Best practices
Radio buttons should:
- Always be used with an associated label component.
- Be part of a list of radio buttons that:
- Include at least two or more choices.
- Are used to have merchants select only one option.
- Include mutually exclusive options—this means that each option must be independent from every other option in the list. For example: Red, blue, and yellow are mutually exclusive. Red, blue, yellow, red/blue are not mutually exclusive.
- List options in a rational order that makes logical sense.
- Have a default option selected whenever possible.
Content guidelines
单选按钮标签
单选按钮标签should:
- Be introduced with a colon or a heading
- Start with a capital letter
Do
- Option 1
Don’t
- option 1
- Not end in punctuation if it’s a single sentence, word, or a fragment
Do
- Red
Don’t
- Red;
Toggle (Android and iOS only)
Toggle labels should:
- Be clear what merchants are enabling or disabling
- Start with a capital letter
Toggle values should:
- Never be labeled
Related components
- To make simple lists of radio buttons easier to build,use the choice list component
- For long lists of options,consider the select componentto avoid overwhelming merchants
- To present merchants with a list of checkboxes,use the choice list componentwith the “allow multiple” option
- To display non-interactive list of related content,use the content list component
Accessibility
Screen readers convey the state of the radio button automatically.
- Use the
disabled
prop to apply the HTMLdisabled
attribute to the radio button. This prevents merchants from being able to interact with the radio button, and conveys its inactive state to assistive technologies.
- Use the
id
prop to provide a uniqueid
attribute value for the radio button. If anid
isn’t provided, then the component generates one. All radio buttons must have uniqueid
values to work correctly with assistive technologies.
Labeling
- The required
label
prop conveys the purpose of the radio button to all merchants - Use the
labelHidden
prop to visually hide the label but make it available to assistive technologies - When you provide help text via the
helpText
prop or an inline error message via theerror
prop, the help or error content is conveyed to screen reader users with thearia-describedby
attribute
Keyboard support
- Move focus to the radio button group using thetabkey (or转变+tabwhen tabbing backwards)
- Use the up and down arrow keys to change which radio button is selected