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

Tokenizer

Field gom vài giá trị ngắn thành các Token: địa chỉ email, tag, label. Gõ rồi nhấn Enter hoặc dấu phẩy thì thêm một token; mỗi token có button xóa, và Backspace trong field trống thì xóa token cuối. Hộp sunken dùng góc container vẫn hữu hạn ở preset pill, và cao thêm khi các token xuống dòng.

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

Xem trước

ada@example.comgrace@example.com

Nhấn Enter hoặc dấu phẩy sau mỗi địa chỉ.

Props

  • defaultValue
  • value
  • placeholder
  • size
  • max
  • disabled
  • label
import { Field, FieldControl, FieldDescription, FieldLabel } from "@/components/ui/field"
import { Tokenizer } from "@/components/ui/tokenizer"

<Field className="w-full max-w-md">
  <FieldLabel>Mời mọi người</FieldLabel>
  <FieldControl>
    <Tokenizer placeholder="Thêm email" defaultValue={["ada@example.com", "grace@example.com"]} />
  </FieldControl>
  <FieldDescription>Nhấn Enter hoặc dấu phẩy sau mỗi địa chỉ.</FieldDescription>
</Field>

Cách dùng

Khi nào dùng

  • Gom vài giá trị ngắn cùng loại trong một field: địa chỉ email, tag.
  • Các giá trị người dùng gõ tự do, mỗi giá trị hiện như một chip có thể xóa.

Khi nào không dùng

  • Một value. Dùng Input.
  • Chọn từ danh sách đã biết. Dùng Combobox, hoặc Checkbox cho danh sách ngắn.
  • Hiện các giá trị người dùng không đổi được. Dùng Token.

Biến thể

size

Chiều cao tối thiểu của hộp lấy từ size-element-*: 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. Hộp cao thêm khi token xuống dòng. Khớp Input hoặc Button bên cạnh: md trong form, sm chỉ trong UI dày ưu tiên chuột, lg hoặc xl cho field chính của một màn hình.

  • ada@example.comgrace@example.com

    Nhấn Enter hoặc dấu phẩy sau mỗi địa chỉ.

    sm

  • ada@example.comgrace@example.com

    Nhấn Enter hoặc dấu phẩy sau mỗi địa chỉ.

    mdmặc định

  • ada@example.comgrace@example.com

    Nhấn Enter hoặc dấu phẩy sau mỗi địa chỉ.

    lg

  • ada@example.comgrace@example.com

    Nhấn Enter hoặc dấu phẩy sau mỗi địa chỉ.

    xl

import { Field, FieldControl, FieldDescription, FieldLabel } from "@/components/ui/field"
import { Tokenizer } from "@/components/ui/tokenizer"

<Field className="w-full max-w-md">
  <FieldLabel>Mời mọi người</FieldLabel>
  <FieldControl>
    <Tokenizer placeholder="Thêm email" size="sm" defaultValue={["ada@example.com", "grace@example.com"]} />
  </FieldControl>
  <FieldDescription>Nhấn Enter hoặc dấu phẩy sau mỗi địa chỉ.</FieldDescription>
</Field>
<Field className="w-full max-w-md">
  <FieldLabel>Mời mọi người</FieldLabel>
  <FieldControl>
    <Tokenizer placeholder="Thêm email" defaultValue={["ada@example.com", "grace@example.com"]} />
  </FieldControl>
  <FieldDescription>Nhấn Enter hoặc dấu phẩy sau mỗi địa chỉ.</FieldDescription>
</Field>
<Field className="w-full max-w-md">
  <FieldLabel>Mời mọi người</FieldLabel>
  <FieldControl>
    <Tokenizer placeholder="Thêm email" size="lg" defaultValue={["ada@example.com", "grace@example.com"]} />
  </FieldControl>
  <FieldDescription>Nhấn Enter hoặc dấu phẩy sau mỗi địa chỉ.</FieldDescription>
</Field>
<Field className="w-full max-w-md">
  <FieldLabel>Mời mọi người</FieldLabel>
  <FieldControl>
    <Tokenizer placeholder="Thêm email" size="xl" defaultValue={["ada@example.com", "grace@example.com"]} />
  </FieldControl>
  <FieldDescription>Nhấn Enter hoặc dấu phẩy sau mỗi địa chỉ.</FieldDescription>
</Field>

Ví dụ

Mời bằng email

ada@example.comgrace@example.com

Nhấn Enter hoặc dấu phẩy sau mỗi địa chỉ.

import { Field, FieldControl, FieldDescription, FieldLabel } from "@/components/ui/field"
import { Tokenizer } from "@/components/ui/tokenizer"

<Field className="w-full max-w-md">
  <FieldLabel>Mời mọi người</FieldLabel>
  <FieldControl>
    <Tokenizer defaultValue={["ada@example.com", "grace@example.com"]} placeholder="Thêm email" />
  </FieldControl>
  <FieldDescription>Nhấn Enter hoặc dấu phẩy sau mỗi địa chỉ.</FieldDescription>
</Field>

Có giới hạn

max dừng việc thêm ở ba tag.

designtokens
import { Field, FieldControl, FieldLabel } from "@/components/ui/field"
import { Tokenizer } from "@/components/ui/tokenizer"

<Field className="w-full max-w-md">
  <FieldLabel>Thẻ</FieldLabel>
  <FieldControl>
    <Tokenizer size="sm" max={3} defaultValue={["design", "tokens"]} placeholder="Thêm thẻ" />
  </FieldControl>
</Field>

Nên và không nên

Nên

  • Dùng cho vài giá trị ngắn cùng loại: email, tag.
  • Nói trong placeholder hoặc description phím nào thêm một value.
  • Kiểm tra mỗi value trong onValueChange và giải thích value bị từ chối trong một FieldError.

Không nên

  • Đừng dùng để chọn từ danh sách đã biết; dùng Combobox hoặc Checkbox.
  • Đừng dùng cho một value; dùng Input.
  • Đừng đặt chữ dài trong một token.

Props

TênKiểuGiá trịMặc địnhMô tả
defaultValuestring--Các value ở lần render đầu, dạng mảng: ["ada@example.com"].
valuestring--Các value dạng mảng, khi bạn control chúng. Đi cùng onValueChange.
onValueChangefunction--Được gọi với mọi value sau khi một value được thêm hoặc xóa.
placeholderstring--Chữ cần gõ, hiện khi chưa có token: Thêm một email. Không phải label.
sizeenumsm | md | lg | xlmdChiều cao tối thiểu của hộp lấy từ size-element-*: 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. Hộp cao thêm khi token xuống dòng. Khớp Input hoặc Button bên cạnh: md trong form, sm chỉ trong UI dày ưu tiên chuột, lg hoặc xl cho field chính của một màn hình.
maxnumber--Số value tối đa nó nhận. Khi đầy, field không nhận thêm chữ, và Backspace vẫn xóa.
disabledboolean-falseKhông gõ được, và các token mất button xóa.
namestring--Tên form. Mỗi value được submit dưới tên này.
removeLabelfunction--Đặt tên mỗi button xóa từ value của nó: (value) => `Remove ${value}` theo mặc định.

Cấu tạo

PhầnMô tả
rootTokenizer: hộp field và những gì nó chứa.
groupHộp field: nền sunken và viền control của Input, với góc radius-container, cao ít nhất bằng size-element, gap-xs giữa các token, py-xs. Nó hiện focus ring của field chữ, kiểu disabled và viền danger.
tokenMột Token cho mỗi value, với button xóa được đặt tên kèm value. Token disabled không có button.
placeholderChữ placeholder trong field chữ, chỉ khi chưa có token.

Khả năng truy cập

Role: textbox

PhímHành động
Enter, commaBiến chữ đã gõ thành một token. Enter khi không có chữ thì submit form như thường.
BackspaceTrong field trống, xóa token cuối.
TabChuyển qua các button xóa của token và field.
  • Đặt tên field bằng label của Field, hoặc aria-label: các token được đọc trước field, theo thứ tự.
  • Mỗi button xóa được đặt tên Remove cùng value; removeLabel đổi các từ. Sau khi xóa, focus trở về field.
  • Hộp chỉ hiện focus ring khi field chữ đang focus; button xóa vẽ vòng của riêng nó.
  • Value đã có trong danh sách, hoặc value vượt max, không được thêm.
  • Khi có name, mỗi value được submit dưới tên đó trong một input ẩn.

Cài đặt

npx werewolf-ui add tokenizer

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.