Chuyển tới nội dung

Pro đang mở bán trước. Cài đặt mở từ tháng 1/2027. Xem Pro

werewolf-ui
Component

Toggle

Button bật hoặc tắt một lựa chọn định dạng hoặc chế độ view. Trạng thái được chọn dùng nền accent mềm.

  • npm: 2 trực tiếp, 3 tổng
  • registry: 2 trực tiếp, 2 tổng

Xem trước

Props

  • variant
  • size
  • disabled
  • iconOnly
  • defaultPressed
  • label
  • icon
import { IconPin } from "@tabler/icons-react"
import { Toggle } from "@/components/ui/toggle"

<Toggle>
  <IconPin size={16} />
  Ghim mục
</Toggle>

Cách dùng

Khi nào dùng

  • Bật hoặc tắt một lựa chọn, chẳng hạn ghim một mục hoặc áp dụng nhấn mạnh.
  • Giữ một hành động toolbar ở trạng thái chọn cho đến khi người dùng tắt.

Khi nào không dùng

  • Hành động không có trạng thái bật được giữ. Dùng Button.
  • Cài đặt được submit trong form. Dùng Switch.
  • Các lựa chọn liên quan. Dùng ToggleGroup.

Biến thể

variant

Trong suốt khi tắt, hoặc một surface có viền trung tính cho outline.

  • defaultmặc định

  • outline

import { IconPin } from "@tabler/icons-react"
import { Toggle } from "@/components/ui/toggle"

<Toggle>
  <IconPin size={16} />
  Ghim mục
</Toggle>
<Toggle variant="outline">
  <IconPin size={16} />
  Ghim mục
</Toggle>

size

Chiều cao control, cỡ chữ và icon, cùng các bước với Button: sm 28px, md 32px (mặc định), lg 36px, xl 44px với chuột; trên cảm ứng md là 36px, lg 44px và xl 48px. Control nhỏ vẫn giữ vùng nhấn tối thiểu.

  • sm

  • mdmặc định

  • lg

  • xl

import { IconPin } from "@tabler/icons-react"
import { Toggle } from "@/components/ui/toggle"

<Toggle size="sm">
  <IconPin size={16} />
  Ghim mục
</Toggle>
<Toggle>
  <IconPin size={16} />
  Ghim mục
</Toggle>
<Toggle size="lg">
  <IconPin size={16} />
  Ghim mục
</Toggle>
<Toggle size="xl">
  <IconPin size={20} />
  Ghim mục
</Toggle>

Ví dụ

Định dạng

import { Toggle } from "@/components/ui/toggle"

<Toggle>Đậm</Toggle>

Được chọn từ đầu

import { Toggle } from "@/components/ui/toggle"

<Toggle variant="outline" defaultPressed>Dạng xem lưới</Toggle>

Chỉ icon

import { IconBold } from "@tabler/icons-react"
import { Toggle } from "@/components/ui/toggle"

<Toggle iconOnly aria-label="Đậm">
  <IconBold size={16} />
</Toggle>

Lựa chọn vô hiệu

import { Toggle } from "@/components/ui/toggle"

<Toggle disabled defaultPressed>Định dạng đã khóa</Toggle>

Icon kèm chữ

Icon và label ổn định ở cùng nhau khi lựa chọn đổi.

import { IconPin } from "@tabler/icons-react"
import { Toggle } from "@/components/ui/toggle"

<Toggle variant="outline" defaultPressed>
  <IconPin size={16} />
  Ghim mục
</Toggle>

Trạng thái icon vô hiệu

import { IconBold, IconItalic } from "@tabler/icons-react"
import { Toggle } from "@/components/ui/toggle"

<Toggle iconOnly disabled aria-label="Đậm">
  <IconBold size={16} />
</Toggle>
<Toggle iconOnly disabled defaultPressed aria-label="In nghiêng">
  <IconItalic size={16} />
</Toggle>

Nên và không nên

Nên

  • Dùng label ổn định, đặt tên cho lựa chọn.
  • Dùng iconOnly với aria-label cho control định dạng gọn.

Không nên

  • Đừng dùng Toggle cho hành động không có trạng thái được giữ.
  • Đừng dùng cho cài đặt có hiệu lực ngay; dùng Switch.

Props

TênKiểuGiá trịMặc địnhMô tả
variantenumdefault | outlinedefaultTrong suốt khi tắt, hoặc một surface có viền trung tính cho outline.
sizeenumsm | md | lg | xlmdChiều cao control, cỡ chữ và icon, cùng các bước với Button: sm 28px, md 32px (mặc định), lg 36px, xl 44px với chuột; trên cảm ứng md là 36px, lg 44px và xl 48px. Control nhỏ vẫn giữ vùng nhấn tối thiểu.
disabledboolean-falseChặn focus và lựa chọn, và dùng màu disabled.
iconOnlyboolean-falseLàm button vuông. Button chỉ có icon cần aria-label.
pressedboolean--Trạng thái bật hoặc tắt controlled. Đi cùng onPressedChange.
defaultPressedboolean-falseTrạng thái ban đầu khi uncontrolled.
onPressedChangefunction--Nhận trạng thái boolean được yêu cầu sau khi kích hoạt.

Cấu tạo

PhầnMô tả
rootToggle button, trong suốt theo mặc định hoặc surface có viền ở outline. Khi bật dùng cặp accent mềm.
iconIcon trang trí tùy chọn, 16px ở sm, md và lg và 20px ở xl.
hitAreaPseudo-element trong suốt kéo đích của button tới size-target-min.

Khả năng truy cập

Role: button

PhímHành động
Space, EnterToggle trạng thái pressed.
TabChuyển focus tới control tiếp theo.
  • Children dạng chữ cung cấp tên truy cập. iconOnly cần aria-label.
  • aria-pressed lộ trạng thái bật hoặc tắt. Giữ label ổn định khi trạng thái đổi.
  • Button mặc định type="button" và không submit form của nó.
  • Truyền size và weight cho mọi icon. Dùng regular khi tắt và có thể dùng fill khi bật.

Cài đặt

npx werewolf-ui add toggle

Chạy npx werewolf-ui init một lần trong app trước khi thêm component. Init cài token, thêm CSS import và luật cho agent. Add cài component này cùng các dependency và giữ nguyên theme của bạn. Xem Cài đặt để biết yêu cầu và cách cài qua registry.