Component / 052 / NEXOFRAME

SearchInput

Mẫu chuẩn

Một ô nhập để tìm, gồm icon kính lúp ở đầu và nút xoá ở cuối khi đã có chữ. Nó báo một giá trị (chuỗi) qua một callback. Nó dựng trên Input và Button.

Composite tầng 2Dựng từ Input + Button1 giá trị, 1 callbackEsc xoá khi có chữ

Playground

Gõ để xem nút xoá xuất hiện, bấm nó hoặc gõ Esc để xoá và xem tiêu điểm trở lại ô.

Giá trị hiện tại: (rỗng)

import { SearchInput } from "@nexobox/ui";

const [value, setValue] = useState("");

<SearchInput
  value={value}
  onValueChange={setValue}
  placeholder="Tìm nhân sự…"
  aria-label="Tìm nhân sự"
  clearLabel="Xoá tìm kiếm"
/>

Bài toán

Lọc danh sách nhân sự hay hội thoại theo tên. Input cho ô nhập nhưng không có chỗ đặt icon ở trong ô, cũng không có nút xoá. Ghép tay thì icon đè lên chữ, và nút xoá không có tên trợ năng.

Khi nào sử dụng

Nên dùng

Lọc một danh sách trên trang theo từ khoá. Đặt trong toolbar, cạnh FilterTabs.

Khi nào không dùng

Tránh dùng

Không dùng cho	Dùng thay
Chọn một giá trị từ danh sách gợi ý	Combobox
Trường của biểu mẫu	Field với Input
Tìm kiếm toàn site mở dialog	Dialog tìm kiếm của shell

Dựng từ

Primitive tầng 1	Vai trong composite
Input	Ô nhập, `type="search"`.
Button	Nút xoá, `variant="ghost"`, `size="sm"`, chỉ hiện khi có chữ.

SearchInput thêm gì
Icon `Search01Icon` trong ô, đệm trái để chữ không đè icon
Nút xoá có tên trợ năng; bấm xong tiêu điểm trở về ô
`Esc` xoá khi có chữ

Anatomy

Icon kính lúp neo trái tuyệt đối trong ô, Input có đệm trái chừa chỗ icon, nút xoá neo phải tuyệt đối khi có chữ.

States

Trạng thái	Biểu hiện
Rỗng	Placeholder; không có nút xoá
Có chữ	Nút xoá hiện
Focus	Vòng focus của `Input`
Disabled	Từ `Input`; nút xoá ẩn

Bàn phím & trợ năng

Gõ, chọn chữ -- Input.

Esc khi có chữ -- composite xoá giá trị, giữ tiêu điểm trong ô.

Tab tới nút xoá, Enter -- Button; composite trả tiêu điểm về ô sau khi xoá.

Seam — host sở hữu gì

Composite không lọc dữ liệu, không debounce, không đồng bộ URL. Host nhận chuỗi và tự quyết lọc lúc nào.

Host sở hữu	Cấp qua
Lọc dữ liệu, debounce	Host, ngoài composite
Giá trị hiện tại	`value` / `onValueChange`

API & triển khai

Prop	Mặc định	Quy ước
value	—	Bắt buộc.
onValueChange	—	Bắt buộc. (value: string) => void.
placeholder	undefined	—
aria-label	undefined	Bắt buộc khi không có Label đi kèm.
clearLabel	—	Bắt buộc. Tên trợ năng của nút xoá, ví dụ "Xoá tìm kiếm".
disabled	false	—

Design tokens

--nf-semantic-text-muted (icon), --nf-foundation-size-icon-small, --nf-foundation-space-2, --nf-foundation-space-3, --nf-foundation-space-8 (đệm trái chừa chỗ icon). Qua Input và Button: --nf-component-field-*, --nf-component-button-*.

Do / Don't

Nên dùng

clearLabel nói việc: "Xoá tìm kiếm". Host debounce nếu lọc tốn kém. Đặt cạnh FilterTabs trong một toolbar.

Tránh dùng

Nút × không có tên. Gọi server ở mỗi phím gõ. Nhét vào PageHeader.