SegmentedControl
'%3e%3cpath%20d='M19%2028.5C19%2025.9804%2020.0009%2023.5641%2021.7825%2021.7825C23.5641%2020.0009%2025.9804%2019%2028.5%2019C31.0196%2019%2033.4359%2020.0009%2035.2175%2021.7825C36.9991%2023.5641%2038%2025.9804%2038%2028.5C38%2031.0196%2036.9991%2033.4359%2035.2175%2035.2175C33.4359%2036.9991%2031.0196%2038%2028.5%2038C25.9804%2038%2023.5641%2036.9991%2021.7825%2035.2175C20.0009%2033.4359%2019%2031.0196%2019%2028.5Z'%20fill='%231ABCFE'/%3e%3cpath%20d='M0%2047.5C0%2044.9804%201.00089%2042.5641%202.78249%2040.7825C4.56408%2039.0009%206.98044%2038%209.5%2038H19V47.5C19%2050.0196%2017.9991%2052.4359%2016.2175%2054.2175C14.4359%2055.9991%2012.0196%2057%209.5%2057C6.98044%2057%204.56408%2055.9991%202.78249%2054.2175C1.00089%2052.4359%200%2050.0196%200%2047.5H0Z'%20fill='%230ACF83'/%3e%3cpath%20d='M19%200V19H28.5C31.0196%2019%2033.4359%2017.9991%2035.2175%2016.2175C36.9991%2014.4359%2038%2012.0196%2038%209.5C38%206.98044%2036.9991%204.56408%2035.2175%202.78249C33.4359%201.00089%2031.0196%200%2028.5%200L19%200Z'%20fill='%23FF7262'/%3e%3cpath%20d='M0%209.5C0%2012.0196%201.00089%2014.4359%202.78249%2016.2175C4.56408%2017.9991%206.98044%2019%209.5%2019H19V0H9.5C6.98044%200%204.56408%201.00089%202.78249%202.78249C1.00089%204.56408%200%206.98044%200%209.5H0Z'%20fill='%23F24E1E'/%3e%3cpath%20d='M0%2028.5C0%2031.0196%201.00089%2033.4359%202.78249%2035.2175C4.56408%2036.9991%206.98044%2038%209.5%2038H19V19H9.5C6.98044%2019%204.56408%2020.0009%202.78249%2021.7825C1.00089%2023.5641%200%2025.9804%200%2028.5H0Z'%20fill='%23A259FF'/%3e%3c/g%3e%3cdefs%3e%3cclipPath%20id='clip0_1_137'%3e%3crect%20width='38'%20height='57'%20fill='white'/%3e%3c/clipPath%3e%3c/defs%3e%3c/svg%3e){kind=icon}
Toggle from a set of two or more options. SegmentedControl is essentially a styled wrapper around a group of radio inputs.
Use this component when:
- It's important to see all the options
- It is expected to be a frequent back and forth
- Horizontal treatment is better visually than vertical
- 2-4 items
Use a RadioGroup when:
- It's important to see all the options
- It's expected the user will not change this choice often
- It's not going to stay present on the page (i.e. during set up)
- 2+ items
Importing
The component can be imported via:
Usage
The component accepts an array of options, defined by the SegmentedControlOption interface.
A value and label (or ariaLabel) are, at a minimum, required for each option.
Additionally, a label (or ariaLabel) is required on the SegmentedControl itself,
which provides information on what is being selected.
The control items internally render as radio inputs. Because of this, it's also recommended
to provide a name prop to the component, to tie the radio inputs together.
If no name is provided, one will be generated.
Finally, value and onChange are also required to control the currently selected option.
value should be the value of the currently selected option.
Style variant
By default, the component renders a gray background for the selected option.
For a version of the component with more visual weight, variant="primary"
is available.
This can be used when you need to draw more attention to the control. This variant could be distracting when other primary-style buttons are present on the page, and should be used with caution.
Size
The component supports a size prop, which can be set to sm for a smaller version of it:
Disabled
The component can be disabled via isDisabled:
Full-width
By default, the component renders as an inline block element.
To render it as a full-width block, use the isFullWidth prop:
Icons
The segmented control's options accept an icon key, which should be a valid Pluma Icon name.
It is also possible to render icon-only options, but an ariaLabel on each option
will still be required:
Generally we don't recommend using icon-only options, as icons may not be universally recognizable in regards to its meaning.
Grid Layout / Columns
The columns prop can be used to arrange the segmented control items into a grid.
This is useful when you have a larger number of options that might not fit well in a single row.
The value of columns specifies the number of columns in the grid.
Customizing labels
If a string label is not sufficient, a component can be used to render the label.
In React, the label prop accepts any ReactNode.
API
PlumaSegmentedControl extends Box
The aria-label attribute to be applied on the fieldset.
The aria-labelledby attribute to be applied on the fieldset.
Default:'fieldset'
What element or component should be rendered.
Number of columns to display in a grid layout. When set to a value of 1 or greater, the control will render as a grid with proper ARIA grid semantics and keyboard navigation. When undefined, the control behaves as a traditional horizontal segmented control.
An optional id attribute to assign to the fieldset.
Whether the entire group is disabled.
Whether the control should take up the full width of its container.
The label text to be shown above the control.
The name shared by controls in this group. If none is provided, one will be generated.
Called when the value changes.
An array of options to show in the component.
Default:'md'
The size of the control. medium and small are deprecated, use md and sm instead.
Additional classes to apply to the option item elements
(each array item corresponding to the options array).
Additional classes to apply to the option item elements' input elements
(each array item corresponding to the options array).
The current value.
Default:'default'
The style variant of the control.
An aria-label applied to the option. Use when "label" is not descriptive enough for screen readers, or when the control only shows an icon.
The aria-labelledby attribute to be applied on the fieldset,
if label and ariaLabel aren't suitable.
The name of an icon (from Pluma Icons) to render in the option.
The source URL of a custom image icon to render in the option. When provided, this will be rendered using the Image component with icon sizing. The image will always have alt="" as it is purely decorative.
Whether this specific option is disabled.
The label text to show within this option.
The value associated with this option.
PlumaSegmentedControlItem extends Box
String value that labels the form field.
Element (or elements) that label the form field.
Default:'label'
What element or component should be rendered.
An error message associated with the form field.
Boolean: Ember-only. If the error named block is used,
this prop can be set to true to indicate an error is present,
which will make the error block render.
The name of an icon (from Pluma Icons) to render in the option.
The source URL of a custom image icon to render in the option. When provided, this will be rendered using the Image component with icon sizing. The image will always have alt="" as it is purely decorative.
An optional id to be assigned to the input element. Also used to generate ids for labels and error messages. If one isn't provided, it will be generated.
Whether the form field is disabled.
Whether the form field is in an invalid state.
Whether the option is in the "selected" state.
The label text to show within this option.
The name shared by options in the same control.
The change event handler for the input element.
A change event only fires on radio inputs when they are checked (and not when unchecked).
In React, the event is a React SyntheticEvent; in Ember it's a native change event.
Whether to allow browser autofill and password managers. When false (default), adds attributes to disable password managers (1Password, LastPass, Bitwarden, Dashlane). Set to true for fields where autofill is desired (e.g., email, password, address fields).
Whether the generated label id should be included in the input's aria-labelledby attribute.
Disable this when the label tag surrounds the input as well as it's label text,
for example in an OptionCard component.
By default, form elements will throw an error if no label or aria-label is provided. Disable this to suppress the error, for example when building a custom form element, and you want to handle labeling yourself.
Default:'md'
The size of the control. medium and small are deprecated, use md and sm instead.
Additional classes to be applied to the field node.
Ember-only: this is used internally to detect whether a label
named block is present, and to ignore empty label props if so.
Additional classes to be applied to the input node.
Sets the size attribute on the input element. This controls the visible width of the input in characters.
The value associated with this option.
Whether to apply the center-baseline variant.