SelectorButton

Components/Actions

Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/selectorbutton

Overview

Copy

Selector button triggers a selection panel or modal, such as a font picker or link settings, from a settings panel. Its text can show the current selection.

Do

  • Use it as an entry point to a selection list in an additional panel or modal.
  • Use it to prompt users to open link selection or font picker panels.
  • Show the selected value in the button text after users make a selection.

Don't

  • Don't use it as a primary call to action. Use <Button/> instead.
  • Avoid using obscure placeholder text.

Feature examples

Size

Control selector button size with size prop:

  • large is best for calls to action that require more emphasis.
  • medium is for layouts where other medium sized elements are used.
  • small is default for panels. Provides more compact UI layout.
Copy

Skin

Use the dark skin variant in panels and contexts where the component should visually blend into the UI.

Apply the standard skin in contexts where the button needs to appear more actionable.

Copy

Suffix

Add more context to actions with suffix icons:

  • Indicate that an action will open a popover or navigate users to another page with a suffixIcon.
  • Use suffix to indicate what type of action the button does. When needed suffixIcon can be removed.
Copy

Disabled

To disable a button, use the disabled prop which indicates a button can't be selected.

Copy

Text overflow

Use the ellipsis prop for overflow text. The full text will be displayed in a <Tooltip/> when a user hovers over the button. Control the style of the tooltip using the tooltipProps.

Note: Try to avoid lengthy action labels. CTA text should be short and clear – one to two words, or max three for specific use cases.

Copy

Full width

Use the fullWidth prop to fill the button to 100% of the parent container.

Copy

Common use case examples

Font picker in panels

Use the Selector Button in app settings panels to provide an entry point for opening a font picker.

Copy

Use the Selector Button in panels to provide an entry point for opening the link settings panel.

Copy

Code

Copy

Props

NameTypeDefaultDescription
childrenReactNode—Accepts any item as a child element. For all common cases pass a standard text string.
dataHookstring—Applies a data-hook HTML attribute that can be used in the tests.
disabledboolean—Specifies whether user interactions are disabled.
ellipsisboolean—Specifies whether component handles text overflow with ellipsis. If enabled, a label that exceeds the available space is displayed inside a tooltip when the user hovers over the button.
fullWidthboolean—Sets button width to fill a 100% of a parent container width.
onClickMouseEventHandler—Defines a callback function which is called every time a button is clicked.
refnull | string | (instance: Button | null) => void | RefObject<Button>—Allows getting a ref to the component instance. Once the component unmounts, React will set ref.current to null (or call the ref with null if you passed a callback ref).
showTooltipboolean—Specifies whether the full button label is displayed in a tooltip when label overflows available space. Behaviour is enabled by default. Set property value to false to show ellipsis without a tooltip.
size"small" | "medium" | "large"mediumControls the size of a button.
skin"standard" | "dark"darkControls the text color skin of the button.
suffixIconReactElement—Pass an icon or a component to display at the end of a label (e.g., svg, image, etc.)
tooltipPropsTooltipCommonProps—Allows to pass all common tooltip props. Use it to customize a tooltip created from text ellipsis.

Testkit

Import the driver matching your test environment:

Copy

Driver methods

MethodDescription
getButtonTextContentGets button text
isFocusedChecks whether button is focused
isDisabledChecks whether button is disabled
hasSuffixChecks whether button has suffix
existsChecks whether the component found with the given data hook.
elementGets the component root element.
clickClicks on the component root element.
baseReturns UniDriver for the base element.

Changelog

  • 1.340.0 (2026-10-21) — maintenance release, no component-specific changes
  • 1.339.0 (2026-10-19) — maintenance release, no component-specific changes
  • 1.338.0 (2026-10-15) — maintenance release, no component-specific changes
  • 1.330.0 (2026-09-28) — maintenance release, no component-specific changes
  • 1.329.0 (2026-09-24) — maintenance release, no component-specific changes
  • 1.325.0 (2026-09-17) — maintenance release, no component-specific changes
  • 1.320.0 (2026-09-03) — maintenance release, no component-specific changes
  • 1.313.1 (2026-08-18) — fix: in size="small" the suffix icon container is now 18×18px (was 24×24px), matching the 18px icons small buttons use — the icon no longer overflows the button's content box vertically and the extra gap before the right edge is gone. Medium and large keep the 24×24px container. (#16725) — has visual changes
  • 1.310.0 (2026-08-10) — maintenance release, no component-specific changes
  • 1.292.0 (2026-06-22) — maintenance release, no component-specific changes
  • 1.273.0 (2026-04-30) — maintenance release, no component-specific changes
  • 1.266.0 (2026-04-07) — maintenance release, no component-specific changes
  • 1.265.0 (2026-04-02) — feat: rename text-fill tokens to text-fill-dark (#16086) — has visual changes
  • 1.260.0 (2026-03-17) — maintenance release, no component-specific changes
  • 1.247.2 (2026-01-21) — maintenance release, no component-specific changes
  • 1.214.0 (2025-08-22) — breaking: add tokens (#15201)
  • 1.173.0 (2025-03-25) — maintenance release, no component-specific changes
  • 1.172.1 (2025-03-21) — maintenance release, no component-specific changes
  • 1.115.0 (2024-07-17) — maintenance release, no component-specific changes
  • 1.111.0 (2024-06-26) — fix: fix font size (#13868)
  • 1.109.1 (2024-06-11) — fix: remove default suffix icon (#13828)
  • 1.109.0 (2024-06-07) — feat: create new component (#13806)

Last updated: 22 October 2026

Did this help?