72Los geht’s
HextaUI

Toggle group

Eine Reihe von Toggles für eine oder mehrere Auswahlen, mit einer Füllung, die zum gewählten Element gleitet, verbundenen oder abgesetzten Elementen und Pfeiltasten-Fokus.

import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"

export function ToggleGroupDemo() {
  return (
    <ToggleGroup aria-label="Date range" defaultValue={["week"]}>
      <ToggleGroupItem value="day">Day</ToggleGroupItem>
      <ToggleGroupItem value="week">Week</ToggleGroupItem>
      <ToggleGroupItem value="month">Month</ToggleGroupItem>
      <ToggleGroupItem value="year">Year</ToggleGroupItem>
    </ToggleGroup>
  )
}

Installation

pnpm dlx shadcn@latest add https://hextaui.com/r/toggle-group.json

Fügt die Komponente, die HextaUI-Theme-Tokens und alle HextaUI-Komponenten hinzu, von denen sie abhängt.

Verwendung

import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"
<ToggleGroup aria-label="Date range" defaultValue={["week"]}>
  <ToggleGroupItem value="day">Day</ToggleGroupItem>
  <ToggleGroupItem value="week">Week</ToggleGroupItem>
  <ToggleGroupItem value="month">Month</ToggleGroupItem>
</ToggleGroup>

Kann jeweils ein Item an sein, gleitet eine einzelne Füllung zum gewählten Item und nimmt seine Form an, sodass die Gruppe wie ein Steuerelement wirkt. Mit multiple füllt sich jedes Item für sich. Die Füllung wird vor dem ersten Paint platziert und gleitet daher beim Laden nie herein.

Komposition

ToggleGroup
└── ToggleGroupItem

Beispiele

Outline

variant="outline" verbindet die Items zu einem umrandeten Steuerelement.

import {
  IconAlignCenter,
  IconAlignJustified,
  IconAlignLeft,
  IconAlignRight,
} from "@tabler/icons-react"

import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"

export function ToggleGroupOutline() {
  return (
    <ToggleGroup
      variant="outline"
      aria-label="Text alignment"
      defaultValue={["left"]}
    >
      <ToggleGroupItem value="left" aria-label="Align left">
        <IconAlignLeft />
      </ToggleGroupItem>
      <ToggleGroupItem value="center" aria-label="Align center">
        <IconAlignCenter />
      </ToggleGroupItem>
      <ToggleGroupItem value="right" aria-label="Align right">
        <IconAlignRight />
      </ToggleGroupItem>
      <ToggleGroupItem value="justify" aria-label="Justify">
        <IconAlignJustified />
      </ToggleGroupItem>
    </ToggleGroup>
  )
}

Mehrfach

multiple lässt beliebig viele Items an sein, wie bei der Textformatierung.

import {
  IconBold,
  IconItalic,
  IconStrikethrough,
  IconUnderline,
} from "@tabler/icons-react"

import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"

export function ToggleGroupMultiple() {
  return (
    <ToggleGroup
      multiple
      variant="outline"
      aria-label="Text formatting"
      defaultValue={["bold", "italic"]}
    >
      <ToggleGroupItem value="bold" aria-label="Bold">
        <IconBold />
      </ToggleGroupItem>
      <ToggleGroupItem value="italic" aria-label="Italic">
        <IconItalic />
      </ToggleGroupItem>
      <ToggleGroupItem value="underline" aria-label="Underline">
        <IconUnderline />
      </ToggleGroupItem>
      <ToggleGroupItem value="strikethrough" aria-label="Strikethrough">
        <IconStrikethrough />
      </ToggleGroupItem>
    </ToggleGroup>
  )
}

Größen

size an der Gruppe legt die Größe jedes Items fest: sm, default oder lg.

import { IconBold, IconItalic, IconUnderline } from "@tabler/icons-react"

import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"

export function ToggleGroupSizes() {
  return (
    <div className="flex flex-col items-center gap-4">
      {(["sm", "default", "lg"] as const).map((size) => (
        <ToggleGroup
          key={size}
          multiple
          size={size}
          variant="outline"
          aria-label={`Formatting, ${size}`}
          defaultValue={["bold"]}
        >
          <ToggleGroupItem value="bold" aria-label="Bold">
            <IconBold />
          </ToggleGroupItem>
          <ToggleGroupItem value="italic" aria-label="Italic">
            <IconItalic />
          </ToggleGroupItem>
          <ToggleGroupItem value="underline" aria-label="Underline">
            <IconUnderline />
          </ToggleGroupItem>
        </ToggleGroup>
      ))}
    </div>
  )
}

Abstände

spacing setzt einen Abstand zwischen Items auf der Spacing-Skala. Outline-Items mit Abstand behalten ihre eigenen Rahmen und Füllungen.

import { IconStar } from "@tabler/icons-react"

import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"

export function ToggleGroupSpacing() {
  return (
    <div className="flex flex-col items-center gap-4">
      <ToggleGroup spacing={1} aria-label="Rating filter" defaultValue={["4"]}>
        {["1", "2", "3", "4", "5"].map((stars) => (
          <ToggleGroupItem key={stars} value={stars}>
            {stars}
            <IconStar />
          </ToggleGroupItem>
        ))}
      </ToggleGroup>
      <ToggleGroup
        multiple
        spacing={2}
        variant="outline"
        size="sm"
        aria-label="Topics"
        defaultValue={["design"]}
      >
        <ToggleGroupItem value="design">Design</ToggleGroupItem>
        <ToggleGroupItem value="engineering">Engineering</ToggleGroupItem>
        <ToggleGroupItem value="research">Research</ToggleGroupItem>
      </ToggleGroup>
    </div>
  )
}

Icons und Labels

Setze ein Icon vor das Label. Items nur mit Icon brauchen ein aria-label.

import { IconDeviceDesktop, IconMoon, IconSun } from "@tabler/icons-react"

import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"

export function ToggleGroupIcons() {
  return (
    <ToggleGroup aria-label="Theme" defaultValue={["system"]}>
      <ToggleGroupItem value="light">
        <IconSun />
        Light
      </ToggleGroupItem>
      <ToggleGroupItem value="dark">
        <IconMoon />
        Dark
      </ToggleGroupItem>
      <ToggleGroupItem value="system">
        <IconDeviceDesktop />
        System
      </ToggleGroupItem>
    </ToggleGroup>
  )
}

Vertikal

orientation="vertical" stapelt die Items und bewegt den Fokus mit ↑ und ↓.

import { IconLayoutGrid, IconLayoutList, IconList } from "@tabler/icons-react"

import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"

export function ToggleGroupVertical() {
  return (
    <ToggleGroup
      orientation="vertical"
      variant="outline"
      aria-label="Layout"
      defaultValue={["grid"]}
    >
      <ToggleGroupItem value="grid" aria-label="Grid">
        <IconLayoutGrid />
      </ToggleGroupItem>
      <ToggleGroupItem value="cards" aria-label="Cards">
        <IconLayoutList />
      </ToggleGroupItem>
      <ToggleGroupItem value="list" aria-label="List">
        <IconList />
      </ToggleGroupItem>
    </ToggleGroup>
  )
}

Deaktiviert

Deaktiviere ein Item oder die ganze Gruppe mit disabled. Deaktivierte Items werden von der Tastatur übersprungen.

import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"

export function ToggleGroupDisabled() {
  return (
    <div className="flex flex-col items-center gap-4">
      <ToggleGroup aria-label="Plan" defaultValue={["pro"]}>
        <ToggleGroupItem value="free">Free</ToggleGroupItem>
        <ToggleGroupItem value="pro">Pro</ToggleGroupItem>
        <ToggleGroupItem value="team" disabled>
          Team
        </ToggleGroupItem>
      </ToggleGroup>
      <ToggleGroup
        disabled
        variant="outline"
        aria-label="Billing"
        defaultValue={["monthly"]}
      >
        <ToggleGroupItem value="monthly">Monthly</ToggleGroupItem>
        <ToggleGroupItem value="yearly">Yearly</ToggleGroupItem>
      </ToggleGroup>
    </div>
  )
}

Kontrolliert

Übergib value und onValueChange. Den leeren Wert zu ignorieren hält ein Item an, sodass ein erneuter Druck auf das gewählte Item nichts bewirkt.

"use client"

import * as React from "react"

import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"

const views = ["Board", "List", "Calendar"]

export function ToggleGroupControlled() {
  const [view, setView] = React.useState("Board")

  return (
    <div className="flex flex-col items-center gap-3">
      <ToggleGroup
        variant="outline"
        aria-label="View"
        value={[view]}
        onValueChange={(value) => {
          if (value.length > 0) {
            setView(value[0])
          }
        }}
      >
        {views.map((item) => (
          <ToggleGroupItem key={item} value={item}>
            {item}
          </ToggleGroupItem>
        ))}
      </ToggleGroup>
      <p className="text-sm text-muted-foreground">Showing the {view} view.</p>
    </div>
  )
}

Rechts nach links

Item-Reihenfolge, verbundene Ecken, die gleitende Füllung und Pfeiltasten folgen der Leserichtung.

import {
  IconAlignCenter,
  IconAlignLeft,
  IconAlignRight,
} from "@tabler/icons-react"

import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"

export function ToggleGroupRtl() {
  return (
    <div dir="rtl" className="flex flex-col items-center gap-4">
      <ToggleGroup aria-label="الفترة" defaultValue={["week"]}>
        <ToggleGroupItem value="day">يوم</ToggleGroupItem>
        <ToggleGroupItem value="week">أسبوع</ToggleGroupItem>
        <ToggleGroupItem value="month">شهر</ToggleGroupItem>
      </ToggleGroup>
      <ToggleGroup
        variant="outline"
        aria-label="محاذاة النص"
        defaultValue={["right"]}
      >
        <ToggleGroupItem value="right" aria-label="محاذاة لليمين">
          <IconAlignRight />
        </ToggleGroupItem>
        <ToggleGroupItem value="center" aria-label="توسيط">
          <IconAlignCenter />
        </ToggleGroupItem>
        <ToggleGroupItem value="left" aria-label="محاذاة لليسار">
          <IconAlignLeft />
        </ToggleGroupItem>
      </ToggleGroup>
    </div>
  )
}

Tastatur

TasteAktion
TabWechselt in die Gruppe zum zuletzt fokussierten Item und wieder hinaus.
←→Wechselt zwischen Items, an den Enden umlaufend. ↑ und ↓ bei vertikal.
HomeEndSpringt zum ersten oder letzten Eintrag.
EnterSpaceSchaltet das fokussierte Item an oder aus.

Barrierefreiheit

  • Die Gruppe hat die Rolle group; gib ihr ein aria-label. Jedes Item ist ein Button mit aria-pressed.
  • Nur ein Item ist in der Tab-Reihenfolge, sodass die Gruppe ein einziger Tab-Stopp ist und Pfeiltasten sich darin bewegen.
  • Ohne multiple schaltet ein Druck auf das gewählte Item es aus. Kontrolliere den Wert, um ein Item an zu halten.
  • Bei reduzierter Bewegung blendet die Füllung ein, statt zu gleiten.

API-Referenz

ToggleGroup

PropTypStandard
value
string[]–
defaultValue
string[]–
onValueChange
(value: string[], details) => void–
multiple
booleanfalse
variantLegt die Variante jedes Items fest.
"default" | "outline""default"
sizeLegt die Größe jedes Items fest.
"default" | "sm" | "lg""default"
spacingAbstand zwischen Items auf der Spacing-Skala. 0 verbindet Outline-Items.
0 | 0.5 | 1 | 1.5 | 2 | 2.5 | 3 | 4 | 5 | 6 | 80
orientation
"horizontal" | "vertical""horizontal"
loopFocus
booleantrue
disabled
booleanfalse
render
ReactElement | (props, state) => ReactElement<div>
AttributBeschreibung
data-slot="toggle-group"Das Root.
data-slot="toggle-group-indicator"Die gleitende Füllung, ohne multiple gerendert. data-visible, wenn ein Item an ist.
data-variant / data-size / data-spacingVariante, Größe und Abstand der Gruppe.
data-orientation"horizontal" oder "vertical".
data-multipleVorhanden, wenn viele Items an sein können.
data-disabledVorhanden, wenn die Gruppe deaktiviert ist.

ToggleGroupItem

PropTypStandard
valueIdentifiziert das Item im Wert der Gruppe.
string–
disabled
booleanfalse
variantWird verwendet, wenn die Gruppe keine setzt.
"default" | "outline"–
sizeWird verwendet, wenn die Gruppe keine setzt.
"default" | "sm" | "lg"–
nativeButton
booleantrue
render
ReactElement | (props, state) => ReactElement<button>
AttributBeschreibung
data-slot="toggle-group-item"Jedes Item.
data-pressedDas Item ist an.
data-disabledDas Item ist deaktiviert.
data-variant / data-sizeDie aufgelöste Variante und Größe des Items.

Verwandt

In Blocks verwendet

Blocks, die auf Toggle group aufbauen.