IconButton

Components/Actions

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

Overview

Copy

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

Copy

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.

Copy

Disabled

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

Copy

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.

Copy

Common use case examples

Button labels

Use <Tooltip/> to add a label to icon buttons.

Copy

Small layouts

Use icon buttons in small and crowded layouts.

Copy

Popover menu

Use icon buttons to open a <PopoverMenu/>.

Copy

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.

Copy

Code

Copy

Props

NameTypeDefaultDescription
ariaLabelstring—Define a string value that labels the button element.
ariaLabelledBystring—Identify the element that labels the button element.
as"button"—Renders component as any other component or a given HTML tag.
dataHookstring—Applies a data-hook HTML attribute that can be used in the tests.
disabledboolean—Specify whether button should be disabled.
onClickMouseEventHandler—Defines a callback function which is called every time a button is clicked.
priority"primary" | "secondary" | "tertiary"—Control the priority of a component.
refnull | 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:

Copy

Driver methods

MethodDescription
isButtonDisabledreturns true if button disabled
isFocusedChecks whether button is focused
hasSizeChecks whether the resolved rendered size matches the given size, including provider defaults
hasSkinChecks whether the resolved rendered skin matches the given skin, including provider defaults
hasPriorityChecks whether the resolved rendered priority matches the given priority, including provider defaults
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.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) — 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) — 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) — 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)
  • 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)
  • 1.139.0 (2024-11-07) — feat: skin type ai (#14254)
  • 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)
  • 1.93.0 (2024-02-08) — maintenance release, no component-specific changes
  • 1.92.1 (2024-02-05) — maintenance release, no component-specific changes

Last updated: 30 October 2026

Did this help?