ToggleGroup

Two-state buttons that can be toggled on or off

ToggleGroup arranges two-state buttons into a keyboard-navigable single or multiple selection control.

Single

Multiple

Single

Multiple

Features

Full keyboard navigation
Horizontal and vertical orientation
Single or multiple pressed buttons
Controlled or uncontrolled state

Installation

ToggleGroup is already installed in tamagui, or you can install it independently:

yarnnpmbunpnpm
yarn add @tamagui/toggle-group

Usage

ToggleGroup handles the toggle state logic. For visual grouping with border radius, compose with XGroup or YGroup. Use activeStyle to customize the active state appearance:

import { ToggleGroup, XGroup, style } from 'tamagui'

const activeItemStyle = style({ backgroundColor: 'color-5' })

export default () => {
  return (
    <ToggleGroup type="single">
      <XGroup>
        <XGroup.Item>
          <ToggleGroup.Item
            value="foo"
            borderRadius="4"
            activeStyle={activeItemStyle}
          >
            Foo
          </ToggleGroup.Item>
        </XGroup.Item>
        <XGroup.Item>
          <ToggleGroup.Item
            value="bar"
            borderRadius="4"
            activeStyle={activeItemStyle}
          >
            Bar
          </ToggleGroup.Item>
        </XGroup.Item>
      </XGroup>
    </ToggleGroup>
  )
}

For vertical layouts, use YGroup:

<ToggleGroup type="single" orientation="vertical">
  <YGroup>
    <YGroup.Item>
      <ToggleGroup.Item value="top" borderRadius="4">
        Top
      </ToggleGroup.Item>
    </YGroup.Item>
    <YGroup.Item>
      <ToggleGroup.Item value="bottom" borderRadius="4">
        Bottom
      </ToggleGroup.Item>
    </YGroup.Item>
  </YGroup>
</ToggleGroup>

API reference

ToggleGroup

ToggleGroup manages toggle state and keyboard navigation. It does not render any visible element by default. Use XGroup/YGroup for visual grouping.

Props

type

"single" | "multiple"

Determines whether a single or multiple items can be pressed at a time.

value

string | string[]

The controlled value of the pressed item(s). Use string for type="single", string[] for type="multiple".

defaultValue

string | string[]

The value of the item(s) to show as pressed when initially rendered.

orientation

"horizontal" | "vertical"

Default:

"horizontal"

The orientation of the component, which determines how focus moves: horizontal for left/right arrows and vertical for up/down arrows.

disabled

boolean

Default:

false

When true, prevents the user from interacting with the toggle group and all its items.

onValueChange

(value: string | string[]) => void

Event handler called when the pressed state of an item changes.

loop

boolean

Default:

true

Whether or not to loop over after reaching the end or start of the items. Used for keyboard navigation.

disableDeactivation

boolean

Default:

false

Won't let the user turn the active item off. Only applies to type="single".

rovingFocus

boolean

Default:

true

Enable roving focus keyboard navigation between items.

ToggleGroup.Item

ToggleGroup.Item extends View inheriting all the Tamagui standard props, plus:

Props

value

string

A unique value for this toggle item.

disabled

boolean

Default:

false

When true, prevents the user from interacting with this item.

activeStyle

StylePiece

Style piece applied when the item is in its active/pressed state. Accepts a style() piece.

activeTheme

string | null

Theme to apply when the item is active. Set to null for no theme change.

Styling active state

Customize the active/pressed state using activeStyle:

const greenActiveStyle = style({
  backgroundColor: 'green-500',
})

// Usage on ToggleGroup.Item
<ToggleGroup.Item value="left" activeStyle={greenActiveStyle}>
  Left
</ToggleGroup.Item>

// Or via styled()
const GreenItem = styled(ToggleGroup.Item, {
  activeStyle: greenActiveStyle,
})

You can also use activeTheme to apply a theme when active:

<ToggleGroup.Item value="option1" activeTheme="green">
  Option 1
</ToggleGroup.Item>

useToggleGroupItem

For custom components inside ToggleGroup.Item that need to know the active state, use the useToggleGroupItem hook:

import { useToggleGroupItem, ToggleGroup } from '@tamagui/toggle-group'

function CustomLabel({ children }) {
  const { active, color } = useToggleGroupItem()
  return <html.span color={active ? 'green-10' : 'color'}>{children}</html.span>
}

// Usage
;<ToggleGroup.Item value="option1">
  <CustomLabel>Option 1</CustomLabel>
</ToggleGroup.Item>

Switch

Edit this page on GitHub.