Button

Components/Actions

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

Overview

Copy

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

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.

Copy

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

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

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

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

All attributes will be passed to the rendered HTML tag.

Copy

Common use case examples

Loading state

When an action is delayed and still loading, use <Loader/> instead of a label on the button.

Copy

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.

Copy

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.

Copy

Disabled state

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

Copy

Code

Copy

Props

NameTypeDefaultDescription
as"button"—Renders component as any other component or a given HTML tag.
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.
prefixIconReactElement—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.
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" | "tiny" | "medium" | "large"mediumControls the size of a button.
skin"standard" | "light" | "inverted" | "destructive" | "premium" | "dark" | "transparent" | "premium-light" | "ai"—Specifies the skin of a 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
isButtonDisabledChecks whether button is disabled
hasSkinChecks whether button has a given skin
isPrefixIconExistsChecks whether button has an icon prefix
isSuffixIconExistsChecks whether button has an icon 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.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) — 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)
  • 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)
  • 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)
  • 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)
  • 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)
  • 1.207.0 (2025-07-24) — breaking: tokenization for Editor3 (#15091)
  • 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)
  • 1.172.1 (2025-03-21) — maintenance release, no component-specific changes
  • 1.166.0 (2025-03-04) — breaking: font size medium & small (#14573)
  • 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)
  • 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)
  • 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)
  • 1.104.1 (2024-05-14) — fix: add active state to primary AI button (#13709)
  • 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)
  • 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

Last updated: 22 October 2026

Did this help?