Toggle

Overview

The Toggle component is a button that switches between two states — selected and unselected. It supports variants, sizes, icons, and an optional tooltip, and can be used in controlled or uncontrolled mode.

Variations

Controlled and uncontrolled

The Toggle component can be used in both controlled and uncontrolled modes. In controlled mode, the selected prop drives the toggle’s state and onChange fires with the new boolean when the user activates it. In uncontrolled mode, defaultValue sets the initial state and the component manages its own state internally.

Variants

The variant prop controls the unselected style: outline, ghost, or transparent. The selectedVariant prop controls the style when the toggle is selected, with options primary and secondary.

Note

When variant is set to transparent, selectedVariant is ignored — the selected state also stays transparent, following the design specification.

Sizes

The size prop controls the toggle’s overall dimensions. Supported values are md (default), sm, and xs.

Rounded

Pass rounded to give the underlying button fully rounded corners.

Icon only

Pass iconOnly to size the toggle to fit a single icon, suitable for icon-only buttons. When iconOnly is set, the prefixIcon is the only icon displayed and the text prop becomes the button’s aria-label.

With tooltip

Pass tooltipProps to wrap the toggle in a Tooltip. It accepts the title, content, side, and align properties from TooltipProps.

Installation

import { Toggle } from "@harnessio/ui/components";

<Toggle
  size="sm"
  variant="outline"
  selectedVariant="primary"
  rounded
  tooltipProps={{
    content: <p>This is a tooltip</p>,
  }}
  text="Toggle"
/>;

Usage

Anatomy

Toggle renders a single pressable button that reflects a selected / unselected state.

• The button hosts an optional prefixIcon, the text label, and an optional suffixIcon. In iconOnly mode only the prefixIcon shows and text supplies the accessible label.
• The unselected appearance comes from variant; when selected, the button switches to selectedVariant (except for transparent, which stays transparent).
• Activating the toggle flips its state and fires onChange with the new boolean value. Provide selected to control the state yourself, or defaultValue to let the component manage it.

Note

onChange receives the new selected state as a boolean (not a DOM event), so a handler reads the value directly: onChange={(selected) => …}.

Best practices

Do

• Give every toggle a text label; in iconOnly mode keep text set so the control still has an accessible name.
• Use a Toggle for a single on/off choice; reach for ToggleGroup when several related toggles form one set.
• Pair selected with onChange in controlled mode, or use defaultValue for uncontrolled — don’t mix the two.

Don’t

• Don’t rely on colour alone (the selectedVariant) to signal state without a clear label or icon.
• Don’t use a Toggle for actions that submit or navigate — use a Button instead.

Accessibility

Keyboard

• The toggle is a real <button>, so it is focusable and activates with Space or Enter.

Labeling & semantics

• The pressed state is exposed to assistive tech (aria-pressed / data-state) by the underlying Radix Toggle primitive.
• In iconOnly mode the text prop becomes the button’s aria-label; always provide it so the icon-only control has an accessible name.

Properties

Properties

Prop	Required	Default	Type
text	false		string
variant	false	'outline'	'outline' | 'ghost' | 'transparent'
selectedVariant	false	'primary'	'primary' | 'secondary'
size	false	'md'	'md' | 'sm' | 'xs'
selected	false		boolean
defaultValue	false	false	boolean
onChange	false		(selected: boolean) => void
iconOnly	false	false	boolean
rounded	false	false	boolean
disabled	false	false	boolean
prefixIcon	false		IconName
prefixIconProps	false		Omit<IconPropsV2, 'name'>
suffixIcon	false		IconName
suffixIconProps	false		Omit<IconPropsV2, 'name'>
tooltipProps	false		Pick<TooltipProps, 'title' | 'content' | 'side' | 'align'>
className	false		string