Component
Label
Tên nhìn thấy của một control trong form: chữ medium 14px, giữ trên màn hình trong lúc người dùng gõ. Đánh dấu field bắt buộc bằng ghi chú Required nhẹ ở cuối hàng, hoặc field không bắt buộc bằng Optional, có thể bắt đầu bằng icon trang trí, và có thể thêm button info kèm tooltip để trợ giúp thêm. Bên trong Field, dùng FieldLabel, vì FieldLabel tự trỏ tới control.
Xem trước
import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/label"
<div className="flex w-full max-w-sm flex-col gap-xs">
<Label htmlFor="preview-label">Khóa API</Label>
<Input id="preview-label" />
</div>Cách dùng
Khi nào dùng
- Đặt tên cho một control trong form bằng văn bản giữ trên màn hình trong lúc người dùng gõ.
- Đánh dấu một field bắt buộc, hoặc một field không bắt buộc trong form mà hầu hết field là bắt buộc.
Khi nào không dùng
- Một control có mô tả hoặc lỗi. Dùng Field, component này nối chúng với control và gán label cho bạn.
- Văn bản không đặt tên cho control nào, chẳng hạn tiêu đề của một mục. Dùng một heading.
- Thay bằng placeholder, thứ biến mất ngay khi người dùng gõ.
Ví dụ
Mặc định
import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/label"
<div className="flex w-full max-w-sm flex-col gap-xs">
<Label htmlFor="project-name">Tên dự án</Label>
<Input id="project-name" />
</div>Bắt buộc
Ghi chú Required dành cho người dùng nhìn thấy màn hình; required trên input là thứ trình đọc màn hình thông báo.
import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/label"
<div className="flex w-full max-w-sm flex-col gap-xs">
<Label htmlFor="workspace-name" required requiredText="Bắt buộc">Tên không gian làm việc</Label>
<Input id="workspace-name" required />
</div>Không bắt buộc
import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/label"
<div className="flex w-full max-w-sm flex-col gap-xs">
<Label htmlFor="company" optional optionalText="Không bắt buộc">Công ty</Label>
<Input id="company" />
</div>Vô hiệu
import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/label"
<div className="flex w-full max-w-sm flex-col gap-xs">
<Label htmlFor="region" disabled>Khu vực</Label>
<Input id="region" disabled defaultValue="Châu Âu" />
</div>Với icon phía trước
Icon mang tính trang trí; văn bản label đặt tên cho field.
import { IconSearch } from "@tabler/icons-react"
import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/label"
<div className="flex w-full max-w-sm flex-col gap-xs">
<Label htmlFor="search" leadingIcon={<IconSearch size={16} />} required>Search</Label>
<Input id="search" required />
</div>Với tooltip
Button info nêu tên field, và tooltip được đọc như mô tả của button.
import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/label"
<div className="flex w-full max-w-sm flex-col gap-xs">
<Label htmlFor="api-key" tooltip="Find it under Settings, then API." tooltipLabel="Giới thiệu về khóa API">Khóa API</Label>
<Input id="api-key" />
</div>Nên và không nên
Nên
- Cho mọi control trong form một label nhìn thấy, phía trên hoặc bên cạnh.
- Viết tên theo sentence case, không có dấu hai chấm: Email, Project name.
- Ưu tiên Field, component này nối label, control, mô tả và lỗi của control.
- Đánh dấu vài field bắt buộc khi hầu hết là không bắt buộc, hoặc vài field không bắt buộc khi hầu hết là bắt buộc.
- Dùng tooltip cho trợ giúp mà một số người dùng cần, chẳng hạn chỗ tìm một giá trị; đặt tên button kèm field: About API keys.
- Cạnh một Checkbox, dùng prop label và description của Checkbox; chúng xếp hàng và nối các id.
Không nên
- Đừng dùng placeholder hoặc aria-label thay cho label nhìn thấy.
- Đừng đánh dấu cả field required và field optional trong cùng một form.
- Đừng đặt label lên văn bản không đặt tên cho control nào; dùng một heading hoặc một đoạn văn.
- Đừng giấu những gì mọi người dùng cần trong tooltip; viết vào mô tả của field.
Props
| Tên | Kiểu | Giá trị | Mặc định | Mô tả |
|---|---|---|---|---|
| htmlFor | string | - | - | id của control mà label này đặt tên. FieldLabel gán id đó cho bạn. |
| leadingIcon | node | - | - | Icon Tabler trang trí trước label, size={16}. Ẩn khỏi trình đọc màn hình: văn bản label đặt tên cho field. |
| required | boolean | - | false | Hiện ghi chú Required ở cuối hàng. Cũng đặt required trên control. Không kết hợp được với optional. |
| optional | boolean | - | false | Hiện ghi chú Optional ở cuối hàng, cho form mà hầu hết field là bắt buộc. Đánh dấu vài field bắt buộc hoặc vài field không bắt buộc, không đánh dấu cả hai. |
| requiredText | node | - | Required | Ghi chú Required, cho trang bằng ngôn ngữ khác. |
| optionalText | node | - | Optional | Ghi chú Optional, cho trang bằng ngôn ngữ khác. |
| disabled | boolean | - | false | Làm mờ label cho khớp control disabled. Đặt data-disabled. |
| tooltip | node | - | - | Trợ giúp thêm phía sau button info sau label, chẳng hạn chỗ tìm một giá trị. Vài từ văn bản thường. Cần tooltipLabel. |
| tooltipLabel | string | - | - | Tên của button info, có tên field trong đó: About API keys. Bắt buộc khi có tooltip. |
Slot
| Tên | Bắt buộc | Mô tả |
|---|---|---|
| label | có | Tên của field, theo sentence case và không có dấu hai chấm: Email, Project name. |
Cấu tạo
| Phần | Mô tả |
|---|---|
| root | Phần tử label: chữ primary medium 14px. Ghi chú Required hoặc Optional nằm ở cuối hàng. Khi có tooltip, root là một hàng chứa label và button info. |
| icon | Icon Tabler trang trí tùy chọn trước văn bản, 16px, màu icon secondary, ngang với dòng đầu. Ẩn khỏi trình đọc màn hình. |
| marker | Ghi chú Required: chữ tertiary regular 12px ở cuối hàng (ms-auto), ẩn khỏi trình đọc màn hình. |
| optional | Ghi chú Optional: cùng kiểu chữ nhẹ với Required, được đọc cùng label. |
| info | Button info tùy chọn sau label: vòng tròn 20px quanh icon info Tabler 16px, màu icon secondary, overlay hover và pressed trung tính, vòng focus. Mở tooltip. |
| hitArea | ::before trong suốt, căn giữa trên button info, không bao giờ nhỏ hơn size-target-min (24px với chuột, 44px trên cảm ứng). |
Khả năng truy cập
Role: generic
| Phím | Hành động |
|---|---|
| Tab | Khi có tooltip: chuyển focus tới button info và mở tooltip. |
| Enter, Space | Khi có tooltip: mở hoặc đóng tooltip. |
| Escape | Khi có tooltip: đóng tooltip. |
- htmlFor phải khớp id của control, nên nhấn lên label đưa focus vào control và trình đọc màn hình đọc label như tên của control. Bên trong Field, FieldLabel gán htmlFor.
- Ghi chú Required là chữ, nên không bao giờ dựa vào màu, và bị ẩn khỏi trình đọc màn hình. Cũng đặt required trên control: đó là thứ trình đọc màn hình thông báo.
- Ghi chú Optional nằm trong accessible name, vì không có thuộc tính nào cho biết field là optional.
- placeholder không phải là label: nó biến mất ngay khi người dùng gõ.
- Button info nằm ngoài phần tử label, nên tên của button không bao giờ thành một phần tên của control. type bắt buộc tooltipLabel khi có tooltip, và label nên gồm field: About API keys.
- Tooltip mở khi hover và focus, và một lần nhấn bật tắt tooltip, nên cũng hoạt động trên màn hình cảm ứng. Văn bản của tooltip được đọc như mô tả của button.
- Giữ những gì người dùng cần để điền field trong một mô tả bên dưới (FieldDescription), không chỉ trong tooltip.
Cài đặt
npx werewolf-ui add labelChạ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.