トグルグループToggleGroupBeta

オン/オフできる二値のボタン群です。

プレビュー

状態とバリエーション

複数選択

書式設定のように、複数の状態を同時にオンにできます。

単一選択

配置や表示モードなど、1つだけ選ぶ操作に使います。

アウトライン

ツールバー内でボタン境界を見せたい場合に使います。

無効化

一時的に操作できない項目はボタンの形を保ち、ツールチップで理由を補足します。

プロパティ

表は横にスクロールできます
プロパティ型初期値説明
type'single' | 'multiple'-単一選択か複数選択かを指定します。
value / defaultValuestring | string[]-選択中の値です。type に応じて型が変わります。
onValueChange(value: string | string[]) => void-選択状態が変わった時に呼ばれます。
disabledbooleanfalseグループ全体、または項目ごとに操作を無効化します。理由が必要な場合はツールチップで補足します。
variant'default' | 'outline''default'各項目の見た目です。枠線を見せたい時は outline を使います。
size'default' | 'sm' | 'lg''default'各 ToggleGroupItem のサイズです。
ToggleGroupItem.tone'default' | 'info' | 'success' | 'warning' | 'destructive''default'選択中の色を項目ごとに指定します（状態セグメント：休講→destructive、補講→info、通常→default など）。default は primary。(#288)

使い方

import * as React from "react";
import { ToggleGroup, ToggleGroupItem } from "@gunjo/ui";

export function AlignControl() {
  const [value, setValue] = React.useState("left");

  return (
    <ToggleGroup
      type="single"
      value={value}
      onValueChange={(next) => next && setValue(next)}
    >
      <ToggleGroupItem value="left">左</ToggleGroupItem>
      <ToggleGroupItem value="center">中央</ToggleGroupItem>
      <ToggleGroupItem value="right">右</ToggleGroupItem>
    </ToggleGroup>
  );
}

設計の判断

  • 「全部は外せない」を、既定ではなく明示の指定にした。資料は「単一選択では、選ばれている項目をもう一度押しても外れないようにする」を挙げています。GUNJO は disallowEmpty を渡したときだけそうします（#170）。フィルターのように「0件は、すべて表示」が正しい画面もあり、どちらが正しいかは並べたものの意味で変わるからです。土台の Radix が空の値を返してきたときに、それを捨てる形で作ってあります。
  • 選ばれたときの色を、項目ごとに変えられる。tone に注意や成功や警告や破壊を渡すと、その項目が選ばれたときだけ淡い色に変わります（#288）。休講と補講と通常のように、選択肢そのものが意味を持つ切り替えのためです。色は Badge や Alert と同じ淡い色の組み合わせなので、文字とのコントラストは揃っています。
  • variant と size は親に1回書けば足りる。文脈で子に配り、項目ごとの上書きもできます。資料が求める role の付与と aria-pressed は土台の Radix が持つので、こちらは目的を伝える aria-label を親に渡すだけで済みます。

使用コンポーネント

ToggleGroupToggleGroupItemTooltip

関連コンポーネント

ToggleTooltipButtonButton

いつ・なぜ使うか（UIXHERO）

「いつ・なぜ使うか」の判断は、姉妹サイト UIXHERO の記事で解説しています。

UIコンポーネント: ToggleGroup