> To build a Wix site agentically, or add Wix features like bookings or a store to a site you already have, follow https://www.wix.com/headless/skill.md
> 
> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - If a reference page seems to be missing its schema (parameters, return types, or type definitions), append `?schema=true` to its `.md` URL (e.g. `https://dev.wix.com/docs/contexts/contexts/stores/category-info/use-category-info-context.md?schema=true`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: SelectorButton Component

## Article: SelectorButton Component

## Article Link: https://dev.wix.com/docs/wix-design-system/components/actions/selector-button-component.md

## Article Content:

# SelectorButton

_Components/Actions_

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

## Overview

```jsx
<Box width="280px">
  <SelectorButton fullWidth suffixIcon={<Icons.Link />}>
    {' '}
    Choose a link
  </SelectorButton>
</Box>;
```

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.

```jsx
<StorybookComponents.Stack width="240px" flexDirection="column">
  <SelectorButton fullWidth size="large" suffixIcon={<Icons.Link />}>
    {' '}
    Large
  </SelectorButton>
  <SelectorButton fullWidth size="medium" suffixIcon={<Icons.Link />}>
    {' '}
    Medium
  </SelectorButton>
  <SelectorButton fullWidth size="small" suffixIcon={<Icons.LinkSmall />}>
    {' '}
    Small
  </SelectorButton>
</StorybookComponents.Stack>;
```

#### 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.

```jsx
<StorybookComponents.Stack flexDirection="column" width="240px">
  <SelectorButton
    fullWidth
    size="medium"
    skin="dark"
    suffixIcon={<Icons.Text />}
  >
    {' '}
    Heading 1
  </SelectorButton>
  <SelectorButton
    fullWidth
    size="medium"
    skin="standard"
    suffixIcon={<Icons.Text />}
  >
    {' '}
    Heading 1
  </SelectorButton>
</StorybookComponents.Stack>;
```

#### 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.

```jsx
<StorybookComponents.Stack flexDirection="column" width="240px">
  <SelectorButton fullWidth size="medium" suffixIcon={<Icons.Text />}>
    {' '}
    Heading 1
  </SelectorButton>
  <SelectorButton fullWidth size="medium" suffixIcon={<Icons.Link />}>
    {' '}
    Choose a link
  </SelectorButton>
  <SelectorButton fullWidth size="medium">
    {' '}
    Select item
  </SelectorButton>
</StorybookComponents.Stack>;
```

#### Disabled

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

```jsx
<StorybookComponents.Stack flexDirection="column" width="240px">
  <SelectorButton disabled fullWidth size="medium" suffixIcon={<Icons.Add />}>
    {' '}
    Disabled
  </SelectorButton>
</StorybookComponents.Stack>;
```

#### 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.

```jsx
<StorybookComponents.Stack flexDirection="column" width="240px">
  <SelectorButton ellipsis fullWidth size="medium" suffixIcon={<Icons.Link />}>
    {' '}
    This is a very long label that does not fit inside a button
  </SelectorButton>
</StorybookComponents.Stack>;
```

#### Full width

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

```jsx
<SelectorButton fullWidth ellipsis size="medium" suffixIcon={<Icons.Add />}>
  {' '}
  Full width
</SelectorButton>;
```

### 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.

```jsx
() => {
  const [value, setValue] = React.useState(50);
  const [opacity, setOpacity] = React.useState(100);
  return (
    <SidePanel
      skin="floating"
      width="420px"
      onCloseButtonClick={() => {}}
      onHelpButtonClick={() => {}}
    >
      <SidePanel.Header title="Wix Comments" />
      <Box height="480px">
        <VerticalTabs size="small" activeTabId={2} onChange={() => {}}>
          <VerticalTabs.TabItem id={0}>Display</VerticalTabs.TabItem>
          <VerticalTabs.TabItem id={1}>Layout</VerticalTabs.TabItem>
          <VerticalTabs.TabItem id={2}>Design</VerticalTabs.TabItem>
          <VerticalTabs.TabItem id={3}>Text</VerticalTabs.TabItem>
        </VerticalTabs>
        <Divider direction="vertical" />
        <SidePanel.Content noPadding>
          <SidePanel.Field>
            <Button
              priority="secondary"
              size="tiny"
              prefixIcon={<Icons.ChevronLeft />}
            >
              Back
            </Button>
          </SidePanel.Field>
          <SidePanel.Field>
            <FieldSet legend="Text font and color" columns="auto 30px">
              <SelectorButton
                fullWidth
                size="small"
                suffixIcon={<Icons.TextSmall />}
              >
                {'Heading 1'}
              </SelectorButton>
              <FillPreview fill="#839788" aspectRatio={1} />
            </FieldSet>
          </SidePanel.Field>
          <SidePanel.Field>
            <FieldSet gap="small" legend="Border width" columns="auto 72px">
              <Slider
                onChange={(newValue) => setValue(Number(newValue))}
                min={0}
                max={100}
                value={value}
                displayMarks={false}
              />
              <Input
                value={value}
                size="small"
                suffix={<Input.Affix>px</Input.Affix>}
                onChange={(e) => setValue(Number(e.target.value))}
              />
            </FieldSet>
          </SidePanel.Field>
          <SidePanel.Section title="Divider">
            <SidePanel.Field>
              <FieldSet
                legend="Color"
                legendSize="small"
                legendPlacement="top"
                alignment="center"
                columns="30px auto 72px"
              >
                <FillPreview fill="#000000" aspectRatio={1} />
                <Box margin="0 8px">
                  <Slider
                    gradientColor="#000000"
                    min={0}
                    max={100}
                    displayMarks={false}
                    onChange={(value) => setOpacity(Number(value))}
                    value={opacity}
                  />
                </Box>
                <NumberInput
                  value={opacity}
                  min={0}
                  max={100}
                  onChange={(value) => setOpacity(value)}
                  suffix={<Input.Affix>%</Input.Affix>}
                  size="small"
                  hideStepper
                />
              </FieldSet>
            </SidePanel.Field>
          </SidePanel.Section>
        </SidePanel.Content>
      </Box>
    </SidePanel>
  );
};
```

#### Panels with links

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

```jsx
<SidePanel onCloseButtonClick={() => {}} skin="floating" width="288px">
  <SidePanel.Header title="Button settings" />
  <SidePanel.Content noPadding>
    <SidePanel.Field>
      <FormField label="Text">
        <Input placeholder="Add button text" size="small" />
      </FormField>
    </SidePanel.Field>
    <SidePanel.Field>
      <FormField label="Name">
        <SelectorButton fullWidth size="small" suffixIcon={<Icons.LinkSmall />}>
          {'Choose a link '}
        </SelectorButton>
      </FormField>
    </SidePanel.Field>
  </SidePanel.Content>
</SidePanel>;
```

## Code

```jsx
import { SelectorButton } from '@wix/design-system';
```

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | — | Accepts any item as a child element. For all common cases pass a standard text string. |
| `dataHook` | `string` | — | Applies a data-hook HTML attribute that can be used in the tests. |
| `disabled` | `boolean` | — | Specifies whether user interactions are disabled. |
| `ellipsis` | `boolean` | — | 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. |
| `fullWidth` | `boolean` | — | Sets button width to fill a 100% of a parent container width. |
| `onClick` | `MouseEventHandler` | — | Defines a callback function which is called every time a button is clicked. |
| `ref` | `null \| 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). |
| `showTooltip` | `boolean` | — | 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"` | `medium` | Controls the size of a button. |
| `skin` | `"standard" \| "dark"` | `dark` | Controls the text color skin of the button. |
| `suffixIcon` | `ReactElement` | — | Pass an icon or a component to display at the end of a label (e.g., svg, image, etc.) |
| `tooltipProps` | `TooltipCommonProps` | — | 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:

```jsx
// UniDriver
import { SelectorButtonUniDriver } from '@wix/design-system/dist/testkit/unidriver';

// Vanilla
import { SelectorButtonTestkit } from '@wix/design-system/dist/testkit';

// Puppeteer
import { SelectorButtonTestkit } from '@wix/design-system/dist/testkit/puppeteer';

// Testing Library
import { SelectorButtonTestkit } from '@wix/design-system/dist/testkit/testing-library';
```

### Driver methods

| Method | Description |
| --- | --- |
| `getButtonTextContent` | Gets button text |
| `isFocused` | Checks whether button is focused |
| `isDisabled` | Checks whether button is disabled |
| `hasSuffix` | Checks whether button has suffix |
| `exists` | Checks whether the component found with the given data hook. |
| `element` | Gets the component root element. |
| `click` | Clicks on the component root element. |
| `base` | Returns 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](invalid-url)) — 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](invalid-url)) — 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](invalid-url))
- **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](invalid-url))
- **1.109.1** (2024-06-11) — fix: remove default suffix icon ([#13828](invalid-url))
- **1.109.0** (2024-06-07) — feat: create new component ([#13806](invalid-url))