ToggleButton

Components/Actions

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

Overview

Copy

Toggle button allows users to switch between states or trigger actions through clicking or selection, and is commonly used in toolbars.

Do

  • Use it to build composer actions like Undo and Redo.
  • Use it in toolbars for actions like bolding or aligning text.
  • Use it as a tab to navigate in a composer interface.
  • Use it in main layouts to enable users to switch between two states.

Don't

  • Don't use it for regular form actions like Save or Cancel. Use <Button/> instead.
  • Don't use it to turn settings on/off. Use <ToggleSwitch/> instead.

Feature examples

Size

Control toggle button size with size prop:

  • large is best for main actions in a composer.
  • medium (default) is for main composer toolbars.
  • small fits into smaller toolbars and UI elements like cards and widgets.
  • tiny is used in dense layouts.
Copy

Label placement

Position the label with labelPlacement prop:

  • tooltip (default) - use it in dense layouts and for repetitive intuitive actions that don't need the exposed label, such as making text italic.
  • end saves vertical space.
  • bottom saves horizontal space.
Copy

Skin

Control the appearance of a button with skin prop:

  • standard (default) is used it in all default cases.
  • inverted is used when selected actions need additional emphasis.
  • destructive is best for actions that might have a negative effect, for example, when the microphone is muted.
  • success is best for actions that have a positive effect, for example when camera is on or screen is shared.
  • dark is used on colored backgrounds.

Note: by design, different skins are only visible when toggle buttons are selected.

Copy

Shape

Control toggle button form with shape prop:

  • square (default) is best for composer toolbars and top bars.
  • round is built in composer sidebars.
  • pill is for main page layouts.
Copy

Border

Turn on a toggle button border using border prop. It is off by default.

Use it when the action needs additional emphasis.

Copy

State

Control toggle button states with these props:

  • selected is used when action is set to active.
  • disabled is used for unavailable actions, when toggle button cannot be clicked or selected.
Copy

Developer examples

Custom HTML tag

Render toggle button as any given HTML tag with as prop. For example, it 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

Composer interface

Toggle button is one of the main components used in Wix composers. Use it in:

  • <ComposerHeader/> for Undo and Redo actions.
  • <ComposerSidebar/> as built-in button for navigation.
  • Any other toolbar to show actions or select states.
Copy

Video stream

Use toggle buttons in control toolbars to enable/disable actions like screen sharing.

Copy

Switch between states

Use toggle buttons as selectors that switch between two states.

Copy

Code

Copy

Props

NameTypeDefaultDescription
as"button"—Renders component as any other component or a given HTML tag.
borderbooleanfalseApplies border.
childrenReactNode—Used for passing any
dataHookstring—String based data hook.
disabledbooleanfalseApplies disabled styles.
interactivebooleantrueEnables pointer events of a selected button.
labelEllipsisbooleanfalseWhether label should have ellipsis.
labelPlacement"end" | "start" | "bottom" | "tooltip"'tooltip'Label placement.
labelValueReactNode''Label content.
onClickMouseEventHandler—Defines a callback function which is called every time a button is clicked.
refnull | string | (instance: ToggleButtonComponent | null) => void | RefObject<ToggleButtonComponent>—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).
selectedboolean—Applies selected styles.
shape"round" | "square" | "pill"'square'Button shape.
size"small" | "tiny" | "medium" | "large"'medium'Button size.
skin"standard" | "inverted" | "destructive" | "dark" | "success" | "standard-secondary"'standard'Button skins.
tooltipDisabledboolean—Specifies whether the tooltip is suppressed.
tooltipPropsTooltipCommonProps—Tooltip props for label. Applied only when labelPlacement is tooltip.

Testkit

Import the driver matching your test environment:

Copy

Driver methods

MethodDescription
isButtonDisabledChecks whether ToggleButton is disabled
getSkinGets the ToggleButton skin
isButtonSelectedChecks whether ToggleButton is selected
getLabelPlacementGets the ToggleButton label placement
getLabelValueGets the ToggleButton label placement value
getShapeGets the ToggleButton shape
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.330.3 (2026-09-29) — fix: in Harmony (odeditor) a selected button now casts the softer, wider shadow of its design definition, in both the standard and the inverted skin. SegmentedToggle's selected segment shares that shadow and changes with it. (#17232) — 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.328.0 (2026-09-22) — maintenance release, no component-specific changes
  • 1.325.0 (2026-09-17) — maintenance release, no component-specific changes
  • 1.324.0 (2026-09-14) — maintenance release, no component-specific changes
  • 1.323.0 (2026-09-10) — maintenance release, no component-specific changes
  • 1.320.1 (2026-09-04) — maintenance release, no component-specific changes
  • 1.320.0 (2026-09-03) — maintenance release, no component-specific changes
  • 1.318.0 (2026-08-28) — feat: the icon scales down while pressed in Harmony (odeditor). (#16929)
  • 1.316.0 (2026-08-25) — fix: allow standard-secondary as a typed skin value. (#16868)
  • 1.310.1 (2026-08-11) — maintenance release, no component-specific changes
  • 1.310.0 (2026-08-10) — maintenance release, no component-specific changes
  • 1.309.0 (2026-08-06) — maintenance release, no component-specific changes
  • 1.308.0 (2026-08-04) — fix: label font weight is semi-bold again in Harmony (odeditor), Studio 2.0 (odeditor-dark) and Wixel themes. (#16727)
  • 1.305.1 (2026-07-30) — maintenance release, no component-specific changes
  • 1.305.0 (2026-07-28) — maintenance release, no component-specific changes
  • 1.304.0 (2026-07-24) — feat: press-scale animation [Harmony] (#16621)
  • 1.303.0 (2026-07-23) — feat: migrate to semantic classnames (#16584)
  • 1.292.0 (2026-06-22) — maintenance release, no component-specific changes
  • 1.291.0 (2026-06-19) — maintenance release, no component-specific changes
  • 1.273.0 (2026-04-30) — maintenance release, no component-specific changes
  • 1.267.0 (2026-04-09) — fix: fixed shadows for dark theme (#16116) — has visual changes
  • 1.267.0 (2026-04-09) — fix: radius in Harmony theme (#16119) — has visual changes
  • 1.266.0 (2026-04-07) — maintenance release, no component-specific changes
  • 1.263.0 (2026-03-31) — fix: more pronounced shadows (#15930) — has visual changes
  • 1.261.0 (2026-03-24) — maintenance release, no component-specific changes
  • 1.248.0 (2026-01-23) — feat: update hover tokens for standard secondary skin (#15855)
  • 1.247.2 (2026-01-21) — maintenance release, no component-specific changes
  • 1.246.0 (2026-01-09) — maintenance release, no component-specific changes
  • 1.242.0 (2025-12-19) — maintenance release, no component-specific changes
  • 1.241.0 (2025-12-17) — maintenance release, no component-specific changes
  • 1.233.0 (2025-12-01) — feat: new skin added standard-secondary (#15588)
  • 1.227.0 (2025-11-13) — fix: incorrect margins (#15494)
  • 1.221.1 (2025-10-16) — fix: prevent ToggleButton leaking styles (#15408)
  • 1.221.0 (2025-10-15) — fix: fix button container border-box (#15415)
  • 1.220.3 (2025-10-13) — fix: fit ellipsis for end/start placement (#15369)
  • 1.219.0 (2025-09-12) — maintenance release, no component-specific changes
  • 1.218.0 (2025-09-09) — feat: labelPlacement font & other (#15274)
  • 1.212.0 (2025-08-11) — maintenance release, no component-specific changes
  • 1.211.1 (2025-08-08) — fix: applied component level token for standard selected state (#15175)
  • 1.210.0 (2025-08-04) — breaking: tokenization for E3 (#15143)
  • 1.208.0 (2025-07-25) — maintenance release, no component-specific changes
  • 1.206.0 (2025-07-16) — fix: update inline paddings when no icon is passed (#15095)
  • 1.201.2 (2025-06-26) — fix: fix padding when only label is present (#15011)
  • 1.201.1 (2025-06-25) — fix: fix padding for square shape with no icon (#15006)
  • 1.201.0 (2025-06-23) — breaking: token fixes & new component level tokens (#14992)
  • 1.177.0 (2025-04-07) — maintenance release, no component-specific changes
  • 1.172.0 (2025-03-20) — maintenance release, no component-specific changes
  • 1.165.0 (2025-02-27) — feat: add prop to disable interactivity (pointer events) (#14544)
  • 1.164.0 (2025-02-25) — maintenance release, no component-specific changes
  • 1.143.1 (2024-11-26) — fix: fix ToggleButton tooltips, hover and active state behavior in mobile (#14305)
  • 1.138.1 (2024-10-30) — maintenance release, no component-specific changes
  • 1.115.0 (2024-07-17) — maintenance release, no component-specific changes
  • 1.103.1 (2024-04-24) — maintenance release, no component-specific changes
  • 1.103.0 (2024-04-23) — fix: fix disabled selected label color (#13593)
  • 1.102.0 (2024-04-16) — maintenance release, no component-specific changes
  • 1.100.0 (2024-04-04) — maintenance release, no component-specific changes
  • 1.97.0 (2024-02-26) — fix: fixing incorrect testkit arg base type (#13388)
  • 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: 26 October 2026

Did this help?