ToggleButton

A button that toggles between selected and unselected states.

Usage#

import { ToggleButton } from '@backstage/ui';
import { useState } from 'react';

const [isSelected, setIsSelected] = useState(false);

<ToggleButton isSelected={isSelected} onChange={setIsSelected}>
  Toggle
</ToggleButton>

API reference#

Prop	Type	Default	Description
isSelected	boolean	-	Whether the button is selected. Controls the visual pressed state.
defaultSelected	boolean	-	The default selected state (uncontrolled).
onChange	(isSelected: boolean) => void	-	Handler called when the button is pressed.
size	smallmedium	small	Visual weight. Use small for compact layouts, medium for emphasis.
iconStart	ReactElement	-	Icon displayed before the button text. Sized to match button.
iconEnd	ReactElement	-	Icon displayed after the button text. Sized to match button.
isDisabled	boolean	false	Prevents interaction and dims the button.
onSurface	Surface	-	Surface the button is placed on. Defaults to context surface.
children	ReactNode(renderProps) => ReactNode	-	Button label. Can be a function for dynamic content.
className	string	-	Additional CSS class name for custom styling.

Inherits all React Aria ToggleButton props.

Examples#

With icon#

const [isSelected, setIsSelected] = useState(false);

<ToggleButton
  isSelected={isSelected}
  onChange={setIsSelected}
  iconStart={<RiCheckLine />}
>
  With Icon
</ToggleButton>

Sizes#

<Flex align="center" gap="2">
  <ToggleButton size="small" isSelected={small} onChange={setSmall}>
    Small
  </ToggleButton>
  <ToggleButton size="medium" isSelected={medium} onChange={setMedium}>
    Medium
  </ToggleButton>
</Flex>

Disabled#

<Flex gap="2">
  <ToggleButton isDisabled isSelected={false} onChange={() => {}}>
    Disabled Off
  </ToggleButton>
  <ToggleButton isDisabled isSelected={true} onChange={() => {}}>
    Disabled On
  </ToggleButton>
</Flex>

Theming#

Our theming system is based on a mix between CSS classes, CSS variables and data attributes. If you want to customise this component, you can use one of these class names below.

bui-ToggleButton
bui-ToggleButtonContent

Changelog#

Version 0.13.0#

Changes

Migrated all components from useStyles to useDefinition hook. Exported OwnProps types for each component, enabling better type composition for consumers. #33050

Version 0.12.0#

Breaking Changes

Breaking Replaced Surface / onSurface system with new provider/consumer background system

The old Surface type ('0'–'3', 'auto') and its associated props (surface, onSurface) have been replaced by a provider/consumer bg architecture.

Types:
- ContainerBg — 'neutral-1' | 'neutral-2' | 'neutral-3' | 'danger' | 'warning' | 'success'
- ProviderBg — ContainerBg | 'neutral-auto'
Consumer components (e.g. Button) inherit the parent's bg via data-on-bg, and CSS handles the visual step-up. See "Neutral level capping" below for details on how levels are bounded.

Hooks:
- useBgProvider(bg?) — for provider components. Returns { bg: undefined } when no bg is given (transparent). Supports 'neutral-auto' to auto-increment from the parent context.
- useBgConsumer() — for consumer components. Returns the parent container's bg unchanged.
Component roles:
- Provider-only (Box, Flex, Grid): set data-bg, wrap children in BgProvider. Transparent by default — they do not auto-increment; pass bg="neutral-auto" explicitly if you want automatic neutral stepping.
- Consumer-only (Button, ButtonIcon, ButtonLink): set data-on-bg, inherit the parent container's bg unchanged.
- Provider + Consumer (Card): sets both data-bg and data-on-bg, wraps children. Card passes bg="neutral-auto" to its inner Box, so it auto-increments from the parent context.
Neutral level capping:

Provider components cap at neutral-3. There is no neutral-4 prop value. The neutral-4 level exists only in consumer component CSS — for example, a Button sitting on a neutral-3 surface uses neutral-4 tokens internally via data-on-bg. #32711

Migration Guide:

Rename the surface prop to bg on provider components and update values:
```
- <Box surface="1">
+ <Box bg="neutral-1">

- <Card surface="2">
+ <Card bg="neutral-2">

- <Flex surface="0">
+ <Flex bg="neutral-1">

- <Grid.Root surface="1">
+ <Grid.Root bg="neutral-1">
```
Remove onSurface from consumer components — they now always inherit from the parent container:
```
- <Button onSurface="1" variant="secondary">
+ <Button variant="secondary">

- <ButtonIcon onSurface="2" variant="secondary" />
+ <ButtonIcon variant="secondary" />

- <ToggleButton onSurface="1">
+ <ToggleButton>
```
Update type imports:
```
- import type { Surface, LeafSurfaceProps, ContainerSurfaceProps } from '@backstage/ui';
+ import type { ContainerBg, ProviderBg } from '@backstage/ui';
```
Replace hook usage in custom components:
```
- import { useSurface, SurfaceProvider } from '@backstage/ui';
+ import { useBgProvider, useBgConsumer, BgProvider } from '@backstage/ui';

- const { surface } = useSurface({ surface: props.surface });
+ const { bg } = useBgProvider(props.bg);

- const { surface } = useSurface({ onSurface: props.onSurface });
+ const { bg } = useBgConsumer();
```
Update CSS selectors targeting surface data attributes:
```
- [data-surface='1'] { ... }
+ [data-bg='neutral-1'] { ... }

- [data-on-surface='1'] { ... }
+ [data-on-bg='neutral-1'] { ... }
```
Note: Provider components use data-bg (values: neutral-1 through neutral-3, plus intent values). Consumer components use data-on-bg, which reflects the parent container's bg directly. The neutral-4 level never appears as a prop or data-bg value — it is used only in consumer CSS.