> 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: Button Component

## Article: Button Component

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

## Article Content:

# Button

_Components/Actions_

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

## Overview

```jsx
<Box direction="vertical" align="center">
  <Button prefixIcon={<Icons.Add />}>Add Product</Button>
</Box>;
```

Buttons let users initiate actions, like saving changes, navigating or canceling. They're used throughout the UI in various places like pages, widgets and modals.

### Do

- Use it to communicate primary and secondary actions users can take.
- Give secondary action buttons a different style to indicate their lower priority.

### Don't

- Don't use it for links. Use `<TextButton/>` instead.
- Don't use more than one primary button at a time.

### Feature examples

#### Size

Control button size with `size` prop:

- `large` is best for calls to action that require more emphasis.
- `medium` is for main page actions and common use cases.
- `small` fits into smaller UI elements like cards and widgets.
- `tiny` is used for dense layouts.

```jsx
<StorybookComponents.Stack>
  <Button size="large">Large</Button>
  <Button size="medium">Medium</Button>
  <Button size="small">Small</Button>
  <Button size="tiny">Tiny</Button>
</StorybookComponents.Stack>;
```

#### Priority

Each button has a `priority` that signals its importance. Use it to create a clear visual hierarchy across actions on the page.

- `primary` is the main call-to-action.
- `secondary` is for supporting actions alongside a primary (e.g. Cancel, Back).
- `tertiary` is for low-emphasis actions; use when secondary would still feel too prominent.

_Note_: There should only be one primary button per page.

```jsx
() => (
  <Box gap="12px" verticalAlign="middle">
    <Button>Primary</Button>
    <Button priority="secondary">Secondary</Button>
    <Button priority="tertiary">Tertiary</Button>
  </Box>
);
```

#### Skin

Change the appearance of a button with a `skin` prop.

- `standard` is for general primary actions.
- `light` is for primary actions that are on dark backgrounds.
- `destructive` is only for actions that have a destructive effect on user data, like delete.
- `premium` is for actions that prompt users to upgrade their plans to premium subscription.
- `premium-light` is best for upgrade actions that appear on dark backgrounds.
- `dark` should be used with buttons on backgrounds with colors.
- `transparent` is for general actions on backgrounds with vivid colors or images.
- `ai` should be used with AI based features.

```jsx
() => (
  <Box direction="vertical" gap="40px">
    <Box gap="20px" verticalAlign="middle">
      <Button>Standard Primary</Button>
      <Button priority="secondary">Standard Secondary</Button>
      <Button priority="tertiary">Standard Tertiary</Button>
    </Box>
    <Box gap="20px" backgroundColor="D10" padding="6px" verticalAlign="middle">
      <Button skin="light">Light Primary</Button>
      <Button skin="light" priority="secondary">
        Light Secondary
      </Button>
      <Button skin="light" priority="tertiary">
        Light Tertiary
      </Button>
    </Box>
    <Box gap="20px" verticalAlign="middle">
      <Button skin="destructive">Destructive Primary</Button>
      <Button skin="destructive" priority="secondary">
        Destructive Secondary
      </Button>
      <Button skin="destructive" priority="tertiary">
        Destructive Tertiary
      </Button>
    </Box>
    <Box gap="20px" verticalAlign="middle">
      <Button skin="premium">Premium Primary</Button>
      <Button skin="premium" priority="secondary">
        Premium Secondary
      </Button>
      <Button skin="premium" priority="tertiary">
        Premium Tertiary
      </Button>
    </Box>
    <Box gap="20px" backgroundColor="D10" padding="6px" verticalAlign="middle">
      <Button skin="premium-light">Premium Light Primary</Button>
      <Button skin="premium-light" priority="secondary">
        Premium Light Secondary
      </Button>
      <Button skin="premium-light" priority="tertiary">
        Premium Light Tertiary
      </Button>
    </Box>
    <Box gap="20px" verticalAlign="middle">
      <Button skin="dark">Dark Primary</Button>
      <Button skin="dark" priority="secondary">
        Dark Secondary
      </Button>
      <Button skin="dark" priority="tertiary">
        Dark Tertiary
      </Button>
    </Box>
    <Box
      gap="20px"
      backgroundColor="#3899EB"
      padding="6px"
      verticalAlign="middle"
    >
      <Button skin="transparent">Transparent Primary</Button>
      <Button skin="transparent" priority="secondary">
        Transparent Secondary
      </Button>
      <Button skin="transparent" priority="tertiary">
        Transparent Tertiary
      </Button>
    </Box>
    <Box gap="20px" verticalAlign="middle">
      <Button skin="ai">Ai Primary</Button>
      <Button skin="ai" priority="secondary">
        Ai Secondary
      </Button>
      <Button skin="ai" priority="tertiary">
        Ai Tertiary
      </Button>
    </Box>
  </Box>
);
```

#### Affix

Add more context to actions with affix icons:

- Emphasize the button action with a `prefixIcon`.
- Indicate that an action will open a popover or navigate users to another page with a `suffixIcon`.

```jsx
<StorybookComponents.Stack flexDirection="line">
  <StorybookComponents.Stack flexDirection="column">
    <StorybookComponents.Stack>
      <Button size="large" prefixIcon={<Icons.Add />}>
        Prefix
      </Button>
    </StorybookComponents.Stack>
    <StorybookComponents.Stack>
      <Button size="medium" prefixIcon={<Icons.Add />}>
        Prefix
      </Button>
    </StorybookComponents.Stack>
    <StorybookComponents.Stack>
      <Button size="small" prefixIcon={<Icons.AddSmall />}>
        Prefix
      </Button>
    </StorybookComponents.Stack>
    <StorybookComponents.Stack>
      <Button size="tiny" prefixIcon={<Icons.AddSmall />}>
        Prefix
      </Button>
    </StorybookComponents.Stack>
  </StorybookComponents.Stack>
  <StorybookComponents.Stack flexDirection="column">
    <StorybookComponents.Stack>
      <Button size="large" suffixIcon={<Icons.ChevronDown />}>
        Suffix
      </Button>
    </StorybookComponents.Stack>
    <StorybookComponents.Stack>
      <Button size="medium" suffixIcon={<Icons.ChevronDown />}>
        Suffix
      </Button>
    </StorybookComponents.Stack>
    <StorybookComponents.Stack>
      <Button size="small" suffixIcon={<Icons.ChevronDownSmall />}>
        Suffix
      </Button>
    </StorybookComponents.Stack>
    <StorybookComponents.Stack>
      <Button size="tiny" suffixIcon={<Icons.ChevronDownSmall />}>
        Suffix
      </Button>
    </StorybookComponents.Stack>
  </StorybookComponents.Stack>
</StorybookComponents.Stack>;
```

#### Disabled

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

```jsx
<Button disabled>Disabled</Button>;
```

#### 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="180px">
  <Button ellipsis>
    This label exceeds available space and is shown in a tooltip
  </Button>
</StorybookComponents.Stack>;
```

#### Full width

When working on mobile designs, use the `fullWidth` prop to fill the button to 100% of the parent container.

```jsx
<Button fullWidth>Full width</Button>;
```

### Developer examples

#### Custom HTML tag

Render buttons as any given HTML tag with the `as` prop. For example, they can be rendered as:

- `<a>` when attributes like href, target, etc., are needed.
- `<Link>` when props like to, replace, etc. are needed.

All attributes will be passed to the rendered HTML tag.

```jsx
() => {
  const ReactRouterLink = (props) => <div {...props} />;
  return (
    <StorybookComponents.Stack>
      <Button as="a" href="https://www.wix.com" target="_blank">
        {'Native <a/> tag'}
      </Button>
      <Button as={ReactRouterLink} skin="premium" to="/home">
        {'React Router <Link/> tag'}
      </Button>
      <Button as="button" onClick={() => alert('yay')}>
        {'Native <button/> tag'}
      </Button>
    </StorybookComponents.Stack>
  );
};
```

### Common use case examples

#### Loading state

When an action is delayed and still loading, use [`<Loader/>`](https://wix-pages.com/design-system-documentation/#/component/loader) instead of a label on the button.

```jsx
<CustomModalLayout
  primaryButtonText={<Loader size="tiny" />}
  secondaryButtonText="Cancel"
  onCloseButtonClick={() => {}}
  title="Add menu"
>
  <Layout>
    <Cell>
      <FormField label="Name">
        <Input value="Brunch Menu" />
      </FormField>
    </Cell>
    <Cell>
      <FormField label="Description">
        <InputArea value="Brunch includes pastries, fruits, omelettes, coffee, and more." />
      </FormField>
    </Cell>
    <Cell>
      <Box>
        <FormField
          label="Visible to customers"
          labelPlacement="right"
          stretchContent={false}
        >
          <ToggleSwitch checked />
        </FormField>
      </Box>
    </Cell>
  </Layout>
</CustomModalLayout>;
```

#### Main action of a panel

Place the primary CTA button in the `<SidePanel.Footer/>` to make sure it is always clearly visible to the user.

```jsx
<SidePanel
  onCloseButtonClick={() => {}}
  skin="floating"
  width="288px"
  height="576px"
>
  <SidePanel.Header title="Manage Accordion" />
  <SidePanel.Content noPadding>
    <NestableList
      withBottomBorder
      items={[
        {
          id: 1,
          options: [{ value: <Text size="small">Color</Text> }],
          dragHandleSize: 'small',
        },
        {
          id: 2,
          options: [{ value: <Text size="small">Price</Text> }],
          dragHandleSize: 'small',
        },
        {
          id: 3,
          options: [{ value: <Text size="small">Size</Text> }],
          dragHandleSize: 'small',
        },
        {
          id: 4,
          options: [{ value: <Text size="small">Collections</Text> }],
          dragHandleSize: 'small',
        },
      ]}
      onChange={() => {}}
    />
  </SidePanel.Content>
  <SidePanel.Footer>
    <Box direction="vertical" align="center">
      <Button size="small">Add Item</Button>
    </Box>
  </SidePanel.Footer>
</SidePanel>;
```

#### Priority of actions

Not all actions are equal. Ranking them visually tells users what to do first, what's optional, and what's just there if they need it.

```jsx
() => (
  <Box width="460px">
    <Card>
      <Card.Header
        title="Publish Site"
        subtitle="Last edited 2 hours ago by you"
      />
      <Card.Divider />
      <Card.Content>
        <Text size="small" secondary>
          Publishing will make all changes visible to your visitors.
        </Text>
      </Card.Content>
      <Card.Divider />
      <Card.Content>
        <Box verticalAlign="middle" gap="12px">
          <Button>Publish now</Button>
          <Button priority="secondary">Save draft</Button>
          <Box marginLeft="12px">
            <Button priority="tertiary">Preview</Button>
          </Box>
        </Box>
      </Card.Content>
    </Card>
  </Box>
);
```

#### Disabled state

Disable the primary button when required fields are missing, and automatically enable it once all inputs are completed.

```jsx
() => {
  const [name, setName] = React.useState('');
  const [email, setEmail] = React.useState('');

  const isReady = name.trim().length > 0 && email.includes('@');

  return (
    <Box width="460px">
      <Card>
        <Card.Header
          title="Invite team member"
          subtitle="Fill in the required fields to send the invitation."
        />
        <Card.Divider />
        <Card.Content>
          <Box direction="vertical" gap="18px">
            <FormField label="Full name" required>
              <Input
                placeholder="Jane Smith"
                value={name}
                onChange={(e) => setName(e.target.value)}
              />
            </FormField>
            <FormField label="Email address" required>
              <Input
                placeholder="jane@example.com"
                value={email}
                onChange={(e) => setEmail(e.target.value)}
              />
            </FormField>
          </Box>
        </Card.Content>
        <Card.Divider />
        <Card.Content>
          <Box verticalAlign="middle" gap="12px">
            <Button disabled={!isReady}>Send invite</Button>
            <Button priority="secondary">Cancel</Button>
          </Box>
        </Card.Content>
      </Card>
    </Box>
  );
};
```

## Code

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

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `as` | `"button"` | — | Renders component as any other component or a given HTML tag. |
| `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. |
| `prefixIcon` | `ReactElement` | — | Pass an icon or a component to display at the front of a label (e.g., svg, image, etc.) |
| `priority` | `"primary" \| "secondary" \| "tertiary"` | — | Specifies the priority of a button. |
| `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" \| "tiny" \| "medium" \| "large"` | `medium` | Controls the size of a button. |
| `skin` | `"standard" \| "light" \| "inverted" \| "destructive" \| "premium" \| "dark" \| "transparent" \| "premium-light" \| "ai"` | — | Specifies the skin of a 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 { ButtonUniDriver } from '@wix/design-system/dist/testkit/unidriver';

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

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

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

### Driver methods

| Method | Description |
| --- | --- |
| `getButtonTextContent` | Gets button text |
| `isFocused` | Checks whether button is focused |
| `isButtonDisabled` | Checks whether button is disabled |
| `hasSkin` | Checks whether button has a given skin |
| `isPrefixIconExists` | Checks whether button has an icon prefix |
| `isSuffixIconExists` | Checks whether button has an icon 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.335.0** (2026-10-12) — maintenance release, no component-specific changes
- **1.331.0** (2026-10-01) — maintenance release, no component-specific changes
- **1.330.3** (2026-09-29) — maintenance release, no component-specific changes
- **1.330.0** (2026-09-28) — maintenance release, no component-specific changes
- **1.328.0** (2026-09-22) — maintenance release, no component-specific changes
- **1.326.0** (2026-09-17) — maintenance release, no component-specific changes
- **1.325.0** (2026-09-17) — maintenance release, no component-specific changes
- **1.323.0** (2026-09-10) — maintenance release, no component-specific changes
- **1.310.0** (2026-08-10) — maintenance release, no component-specific changes
- **1.306.0** (2026-07-31) — maintenance release, no component-specific changes
- **1.299.0** (2026-07-17) — feat: add tertiary priority ([#16565](invalid-url)) — has visual changes
- **1.292.0** (2026-06-22) — maintenance release, no component-specific changes
- **1.289.0** (2026-06-17) — maintenance release, no component-specific changes
- **1.278.0** (2026-05-08) — maintenance release, no component-specific changes
- **1.277.0** (2026-05-07) — feat: add ai/premium primary fill and label tokens for odeditor-dark ([#16232](invalid-url))
- **1.273.0** (2026-04-30) — maintenance release, no component-specific changes
- **1.272.0** (2026-04-27) — maintenance release, no component-specific changes
- **1.269.0** (2026-04-15) — fix: update primary button fill and label tokens for odeditor-dark ([#16121](invalid-url))
- **1.266.0** (2026-04-07) — maintenance release, no component-specific changes
- **1.264.0** (2026-03-31) — fix: exposed getboundingclientrect method from button class ([#16085](invalid-url))
- **1.262.0** (2026-03-25) — maintenance release, no component-specific changes
- **1.261.0** (2026-03-24) — maintenance release, no component-specific changes
- **1.260.0** (2026-03-17) — maintenance release, no component-specific changes
- **1.257.0** (2026-02-19) — breaking: inverted skin looks bad on harmony/harmony-dark ([#15940](invalid-url))
- **1.254.0** (2026-02-03) — maintenance release, no component-specific changes
- **1.247.2** (2026-01-21) — maintenance release, no component-specific changes
- **1.220.2** (2025-10-06) — maintenance release, no component-specific changes
- **1.212.0** (2025-08-11) — fix: standard secondary color component token re-introduced ([#15183](invalid-url))
- **1.207.0** (2025-07-24) — breaking: tokenization for Editor3 ([#15091](invalid-url))
- **1.206.0** (2025-07-16) — maintenance release, no component-specific changes
- **1.191.2** (2025-05-28) — maintenance release, no component-specific changes
- **1.173.0** (2025-03-25) — fix: studio hover color fix & new branding fonts ([#14666](invalid-url))
- **1.172.1** (2025-03-21) — maintenance release, no component-specific changes
- **1.166.0** (2025-03-04) — breaking: font size medium & small ([#14573](invalid-url))
- **1.165.0** (2025-02-27) — maintenance release, no component-specific changes
- **1.163.0** (2025-02-18) — breaking: secondary button hover state changes in studio theme ([#14528](invalid-url))
- **1.139.0** (2024-11-07) — maintenance release, no component-specific changes
- **1.138.1** (2024-10-30) — maintenance release, no component-specific changes
- **1.133.0** (2024-10-14) — maintenance release, no component-specific changes
- **1.129.0** (2024-09-25) — maintenance release, no component-specific changes
- **1.123.1** (2024-09-05) — fix: updated button ai skin disabled state text token ([#14079](invalid-url))
- **1.115.0** (2024-07-17) — maintenance release, no component-specific changes
- **1.107.0** (2024-05-29) — maintenance release, no component-specific changes
- **1.104.1** (2024-05-14) — feat: add ai secondary skin ([#13632](invalid-url))
- **1.104.1** (2024-05-14) — fix: add active state to primary AI button ([#13709](invalid-url))
- **1.102.0** (2024-04-16) — maintenance release, no component-specific changes
- **1.99.0** (2024-03-29) — fix: fix light secondary button state on hover & active ([#13550](invalid-url))
- **1.98.0** (2024-03-15) — maintenance release, no component-specific changes
- **1.93.0** (2024-02-08) — maintenance release, no component-specific changes
- **1.92.1** (2024-02-05) — maintenance release, no component-specific changes