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

## Article: IconButton Component

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

## Article Content:

# IconButton

_Components/Actions_

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

## Overview

```jsx
<Box align="center">
  <Tooltip content="Edit">
    <IconButton skin="inverted">
      <Icons.Edit />
    </IconButton>
  </Tooltip>
</Box>;
```

Icon buttons highlight actions that users can take, used in compact or crowded layouts.

### Do

- Add tooltip labels to icon buttons using a `<Tooltip/>`.
- Only use icon buttons for low-emphasis actions.
- Use them in compact or crowded layouts.
- Make sure the meaning of the icons are simple and unambiguous.

### Don't

- Don't use them for secondary actions if there's enough space to show the full label. Use `<Button/>` or `<TextButton/>` instead.

### Feature examples

#### Size

Update the dimensions of a button with the `size` prop.

- `large` is for onboarding flows and marketing pages where the action needs more emphasis.
- `medium` is the default for all common cases.
- `small` is for icon buttons used in cards and widgets.
- `tiny` is for small and dense layouts.

_Note_: small and tiny size buttons should use the small icon size (18x18).

```jsx
<StorybookComponents.Stack flexDirection="column">
  <IconButton size="large">
    <Icons.Add />
  </IconButton>
  <IconButton size="medium">
    <Icons.Add />
  </IconButton>
  <IconButton size="small">
    <Icons.AddSmall />
  </IconButton>
  <IconButton size="tiny">
    <Icons.AddSmall />
  </IconButton>
</StorybookComponents.Stack>;
```

#### Skin

Change the button's appearance with the `skin` prop.

- `standard` is the default for all general actions.
- `light` is for dark backgrounds.
- `transparent` is for backgrounds with colors or images.
- `premium` is for actions that prompt users to upgrade their plans.
- `dark` should be used with buttons on backgrounds with colors.
- `ai` should be used with AI based features.

Each action can be `primary`, `secondary` or `tertiary`, depending on priority. There should only be one primary action per page.

_Note_: Secondary buttons should be used alongside primary buttons for less utilized actions, such as cancel or back.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <StorybookComponents.Stack padding="12px" gap="6px">
    <IconButton skin="standard" priority="primary">
      <Icons.Check />
    </IconButton>
    <IconButton skin="standard" priority="secondary">
      <Icons.X />
    </IconButton>
    <IconButton skin="standard" priority="tertiary">
      <Icons.More />
    </IconButton>
  </StorybookComponents.Stack>
  <StorybookComponents.Background skin="dark">
    <StorybookComponents.Stack padding="12px" gap="6px">
      <IconButton skin="light" priority="primary">
        <Icons.Check />
      </IconButton>
      <IconButton skin="light" priority="secondary">
        <Icons.X />
      </IconButton>
      <IconButton skin="light" priority="tertiary">
        <Icons.More />
      </IconButton>
    </StorybookComponents.Stack>
  </StorybookComponents.Background>
  <StorybookComponents.Background skin="blue">
    <StorybookComponents.Stack padding="12px" gap="6px">
      <IconButton skin="transparent" priority="primary">
        <Icons.Check />
      </IconButton>
      <IconButton skin="transparent" priority="secondary">
        <Icons.X />
      </IconButton>
      <IconButton skin="transparent" priority="tertiary">
        <Icons.More />
      </IconButton>
    </StorybookComponents.Stack>
  </StorybookComponents.Background>
  <StorybookComponents.Background skin="light">
    <StorybookComponents.Stack padding="12px" gap="6px">
      <IconButton skin="premium" priority="primary">
        <Icons.Check />
      </IconButton>
      <IconButton skin="premium" priority="secondary">
        <Icons.X />
      </IconButton>
      <IconButton skin="premium" priority="tertiary">
        <Icons.More />
      </IconButton>
    </StorybookComponents.Stack>
  </StorybookComponents.Background>
  <StorybookComponents.Stack padding="12px" gap="6px">
    <IconButton skin="dark" priority="primary">
      <Icons.Check />
    </IconButton>
    <IconButton skin="dark" priority="secondary">
      <Icons.X />
    </IconButton>
    <IconButton skin="dark" priority="tertiary">
      <Icons.More />
    </IconButton>
  </StorybookComponents.Stack>
  <StorybookComponents.Stack padding="12px" gap="6px">
    <IconButton skin="ai" priority="primary">
      <Icons.Check />
    </IconButton>
    <IconButton skin="ai" priority="secondary">
      <Icons.X />
    </IconButton>
    <IconButton skin="ai" priority="tertiary">
      <Icons.More />
    </IconButton>
  </StorybookComponents.Stack>
</StorybookComponents.Stack>;
```

#### Disabled

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

```jsx
<IconButton disabled>
  <Icons.Add />
</IconButton>;
```

### 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` are needed.
- `<Link>` when props like `to`, `replace`, etc. are needed.

All attributes will be passed to the rendered element.

```jsx
() => {
  const ReactRouterLink = (props) => <div {...props} />;

  return (
    <StorybookComponents.Stack justifyContent="space-between">
      <StorybookComponents.Stack
        flexDirection="column"
        gap="12px"
        alignItems="center"
      >
        <Text secondary size="small">
          {'<a/> tag'}
        </Text>
        <IconButton as="a" href="https://www.wix.com" target="_blank">
          <Icons.Add />
        </IconButton>
      </StorybookComponents.Stack>
      <StorybookComponents.Stack
        flexDirection="column"
        gap="12px"
        alignItems="center"
      >
        <Text secondary size="small">
          {'React router <Link/> tag'}
        </Text>
        <IconButton as={ReactRouterLink} to="/home">
          <Icons.Add />
        </IconButton>
      </StorybookComponents.Stack>
      <StorybookComponents.Stack
        flexDirection="column"
        gap="12px"
        alignItems="center"
      >
        <Text secondary size="small">
          {'Native <button/> tag'}
        </Text>
        <IconButton as="button">
          <Icons.Add />
        </IconButton>
      </StorybookComponents.Stack>
    </StorybookComponents.Stack>
  );
};
```

### Common use case examples

#### Button labels

Use [`<Tooltip/>`](https://wix-pages.com/design-system-documentation/#/component/tooltip) to add a label to icon buttons.

```jsx
<Box align="center">
  <Tooltip content="Edit program">
    <IconButton priority="secondary">
      <Icons.Edit />
    </IconButton>
  </Tooltip>
</Box>;
```

#### Small layouts

Use icon buttons in small and crowded layouts.

```jsx
<Layout>
  <Cell span={4}>
    <Proportion aspectRatio={1}>
      <MediaOverlay skin="gradient" media="FoodExample2.jpg">
        <MediaOverlay.Content placement="top-end" visible="always">
          <Tooltip content="Edit image">
            <IconButton priority="secondary" skin="inverted" size="small">
              <Icons.CropSmall />
            </IconButton>
          </Tooltip>
          <Tooltip content="Mark as favorite">
            <IconButton priority="secondary" skin="inverted" size="small">
              <Icons.FavoriteSmall />
            </IconButton>
          </Tooltip>
          <PopoverMenu
            textSize="small"
            triggerElement={
              <Tooltip content="More actions">
                <IconButton priority="secondary" skin="inverted" size="small">
                  <Icons.MoreSmall />
                </IconButton>
              </Tooltip>
            }
          >
            <PopoverMenu.MenuItem text="Edit" />
            <PopoverMenu.MenuItem text="Remove" skin="destructive" />
          </PopoverMenu>
        </MediaOverlay.Content>
        <MediaOverlay.Content placement="bottom-start" visible="always">
          <Text light size="small">
            Pasta with Ricotta Cheese
          </Text>
        </MediaOverlay.Content>
      </MediaOverlay>
    </Proportion>
  </Cell>
</Layout>;
```

#### Popover menu

Use icon buttons to open a `<PopoverMenu/>`.

```jsx
() => {
  const renderImage = () => <Image width={230} borderRadius={0}></Image>;

  const renderContent = () => (
    <Box
      direction="vertical"
      verticalAlign="space-between"
      padding="24px 29px 27px"
      backgroundColor="D80"
      flexGrow={1}
    >
      <Box direction="vertical" gap={1}>
        <Text weight="bold">JAVA meetup</Text>
        <Text size="small" weight="thin" secondary light>
          Jan 20, 2021, 10:00 AM, Location will be announced later
        </Text>
      </Box>
      <Box align="space-between">
        <Box />
        <Box align="space-between" verticalAlign="middle" gap={1}>
          <PopoverMenu
            textSize="small"
            triggerElement={
              <Tooltip content="More actions">
                <IconButton priority="secondary" size="small">
                  <Icons.MoreSmall />
                </IconButton>
              </Tooltip>
            }
          >
            <PopoverMenu.MenuItem
              text="Edit SEO settings"
              prefixIcon={<Icons.SettingsSmall />}
            />
            <PopoverMenu.Divider />
            <PopoverMenu.MenuItem
              text="Duplicate as draft"
              prefixIcon={<Icons.DuplicateSmall />}
            />
            <PopoverMenu.MenuItem
              text="Cancel event"
              skin="destructive"
              prefixIcon={<Icons.BlockSmall />}
            />
          </PopoverMenu>
          <Button
            priority="secondary"
            size="small"
            prefixIcon={<Icons.PromoteSmall />}
          >
            Promote
          </Button>
          <Button priority="secondary" size="small">
            Edit
          </Button>
        </Box>
      </Box>
    </Box>
  );

  return (
    <Card hideOverflow>
      <Box minHeight={200}>
        {renderImage()}
        {renderContent()}
      </Box>
    </Card>
  );
};
```

#### Low priority actions

Use icon buttons for lower-priority actions that have no effect on the main user flow. For example, to change the cover image of an audio.

```jsx
<SidePanel onCloseButtonClick={() => {}} skin="floating" width="288px">
  <SidePanel.Header title="Audio Player Settings" />
  <SidePanel.Content noPadding>
    <SidePanel.Field>
      <FieldSet
        legend="Track cover image"
        alignment="center"
        columns="168px auto auto"
      >
        <Image width="156px" height="102px" src="TravelExample6.jpg" />
        <Tooltip content="Change image">
          <IconButton size="small" skin="standard" priority="secondary">
            <Icons.RefreshSmall />
          </IconButton>
        </Tooltip>
        <Tooltip content="Remove image">
          <IconButton size="small" skin="standard" priority="secondary">
            <Icons.DeleteSmall />
          </IconButton>
        </Tooltip>
      </FieldSet>
    </SidePanel.Field>
    <SidePanel.Field>
      <FormField label="Source (URL)">
        <Input placeholder="Add link to the track" size="small" />
      </FormField>
    </SidePanel.Field>
    <SidePanel.Field>
      <FormField label="Name">
        <Input value="Track Name" size="small" />
      </FormField>
    </SidePanel.Field>
    <SidePanel.Field>
      <FormField label="Description">
        <InputArea
          placeholder="Add a short description to promote your audio track."
          size="small"
          minHeight="120px"
          resizable
        />
      </FormField>
    </SidePanel.Field>
  </SidePanel.Content>
</SidePanel>;
```

## Code

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

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `ariaLabel` | `string` | — | Define a string value that labels the button element. |
| `ariaLabelledBy` | `string` | — | Identify the element that labels the button element. |
| `as` | `"button"` | — | Renders component as any other component or a given HTML tag. |
| `dataHook` | `string` | — | Applies a data-hook HTML attribute that can be used in the tests. |
| `disabled` | `boolean` | — | Specify whether button should be disabled. |
| `onClick` | `MouseEventHandler` | — | Defines a callback function which is called every time a button is clicked. |
| `priority` | `"primary" \| "secondary" \| "tertiary"` | — | Control the priority of a component. |
| `ref` | `null \| string \| (instance: IconButtonHandle \| null) => void \| RefObject<IconButtonHandle>` | — | 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). |
| `size` | `"small" \| "tiny" \| "medium" \| "large"` | — | Control the size of a component. |
| `skin` | `"standard" \| "light" \| "inverted" \| "destructive" \| "premium" \| "dark" \| "transparent" \| "ai"` | — | Sets the skin of a component. |

## Testkit

Import the driver matching your test environment:

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

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

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

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

### Driver methods

| Method | Description |
| --- | --- |
| `isButtonDisabled` | returns true if button disabled |
| `isFocused` | Checks whether button is focused |
| `hasSize` | Checks whether the resolved rendered size matches the given size, including provider defaults |
| `hasSkin` | Checks whether the resolved rendered skin matches the given skin, including provider defaults |
| `hasPriority` | Checks whether the resolved rendered priority matches the given priority, including provider defaults |
| `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.345.0** — breaking: in Harmony (odeditor), a dark secondary icon button on hover shows a slightly darker grey fill with a visible light grey border, matching the design definition and the dark secondary Button. ([#17625](invalid-url)) — has visual changes
- **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.330.3** (2026-09-29) — fix: `skin="dark"` with `priority="secondary"` has a transparent background in Harmony (odeditor) and Studio 2.0 Light (studio2-light). ([#17295](invalid-url)) — has visual 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.323.0** (2026-09-10) — maintenance release, no component-specific 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.289.0** (2026-06-17) — maintenance release, no component-specific changes
- **1.277.0** (2026-05-07) — maintenance release, no component-specific changes
- **1.273.0** (2026-04-30) — maintenance release, no component-specific changes
- **1.269.0** (2026-04-15) — feat: add destructive skin variant ([#16141](invalid-url)) — has visual changes
- **1.266.0** (2026-04-07) — maintenance release, no component-specific changes
- **1.260.0** (2026-03-17) — maintenance release, no component-specific changes
- **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.232.0** (2025-11-28) — maintenance release, no component-specific changes
- **1.212.0** (2025-08-11) — maintenance release, no component-specific changes
- **1.207.0** (2025-07-24) — breaking: new component level tokens implemented ([#15097](invalid-url))
- **1.206.0** (2025-07-16) — maintenance release, no component-specific changes
- **1.201.1** (2025-06-25) — maintenance release, no component-specific changes
- **1.201.0** (2025-06-23) — maintenance release, no component-specific changes
- **1.190.0** (2025-05-22) — maintenance release, no component-specific changes
- **1.188.1** (2025-05-14) — maintenance release, no component-specific changes
- **1.169.0** (2025-03-10) — maintenance release, no component-specific changes
- **1.154.0** (2025-01-16) — fix: convert skin="inverted" to priority="secondary" ([#14461](invalid-url))
- **1.139.0** (2024-11-07) — feat: skin type ai ([#14254](invalid-url))
- **1.138.1** (2024-10-30) — maintenance release, no component-specific changes
- **1.129.0** (2024-09-25) — maintenance release, no component-specific changes
- **1.120.1** (2024-08-08) — maintenance release, no component-specific changes
- **1.120.0** (2024-08-02) — maintenance release, no component-specific changes
- **1.115.0** (2024-07-17) — maintenance release, no component-specific changes
- **1.112.0** (2024-07-03) — maintenance release, no component-specific changes
- **1.107.0** (2024-05-29) — maintenance release, no component-specific changes
- **1.102.0** (2024-04-16) — maintenance release, no component-specific changes
- **1.101.0** (2024-04-12) — feat: add mobile breakpoint ([#13557](invalid-url))
- **1.93.0** (2024-02-08) — maintenance release, no component-specific changes
- **1.92.1** (2024-02-05) — maintenance release, no component-specific changes