@ark-ui/react/fieldTailwind CSS v4WAI-ARIA Accessible

Ark Field Component

Thành phần form field toàn diện, đóng gói ngữ cảnh trợ năng (accessible context) chuẩn WAI-ARIA với khả năng tự động liên kết nhãn qua aria-labelledby, gợi ý và thông báo lỗi qua aria-describedby, cùng các data-attributes trạng thái (data-invalid, data-disabled, data-readonly, data-required). Hỗ trợ cả hai phong cách lập trình Compound API và Shorthand API với 4 kích thước đồng bộ.

Chuẩn accessibility WAI-ARIA

4 kích cỡ (xs, sm, md, lg)

Bố cục Vertical & Horizontal

Tích hợp ArkSwitch & ArkPinInput

1. Bảng điều khiển tương tác (Interactive Playground)

Live Controls

Thử nghiệm thời gian thực các kích cỡ, bố cục, trạng thái và nội dung văn bản của thành phần ArkField.

Kích cỡ (Size)

Bố cục (Orientation)

Trạng thái (States)

Tùy biến nhãn

Kết quả hiển thị thời gian thực (Kích cỡ: MD, Bố cục: vertical)Active

Họ và tên

Tên đầy đủ sẽ được sử dụng để xuất hóa đơn và chứng chỉ.

2. Hai phương thức sử dụng: Shorthand API & Compound Components

Hai mô hình API

Linh hoạt lựa chọn cú pháp 1 dòng tinh gọn cho các form cơ bản hoặc cấu trúc ghép nối linh hoạt để tùy biến DOM chuyên sâu.

Cách 1: Shorthand APINhanh & Tinh gọn

Truyền các props như label, helperText, errorText, required trực tiếp vào component.

Địa chỉ Email

Chúng tôi không bao giờ chia sẻ email của bạn cho bên thứ ba.

<ArkField
  label="Địa chỉ Email"
  required
  placeholder="ban@chillcms.vn"
  helperText="Chúng tôi không bao giờ chia sẻ email..."
  startAdornment={<Mail className="size-4" />}
/>

Cách 2: Compound ComponentsTùy biến chuyên sâu

Ghép nối các phần tử con ArkField.Root, ArkField.Label, ArkField.Input, ArkField.HelperText, ArkField.ErrorText.

Tên đăng nhập hệ thốngCó thể đổi sau

Chỉ bao gồm chữ thường, số và dấu gạch dưới.

<ArkField.Root required>
  <div className="flex justify-between">
    <ArkField.Label>Tên đăng nhập hệ thống</ArkField.Label>
    <span className="text-xs">Có thể đổi sau</span>
  </div>
  <ArkField.Input placeholder="chill_admin" />
  <ArkField.HelperText>Chỉ bao gồm chữ thường...</ArkField.HelperText>
</ArkField.Root>

3. Hỗ trợ đầy đủ các loại Native Controls

Input • Textarea • Select

ArkField hỗ trợ liền mạch các phần tử form gốc của HTML: Text Input, Textarea tự động dãn độ cao (autoresize) và Select dropdown.

1. Native Input

Họ và tên đại diệnDùng cho hợp đồng và thanh toán.

2. Textarea (Autoresize)

Mô tả tiểu sửTùy chọn

Tự động điều chỉnh chiều cao theo nội dung gõ.

3. Native Select

Quốc gia / Khu vựcXác định múi giờ và đơn vị tiền tệ giao dịch.

4. Biểu tượng đầu dòng & Hành động tương tác cuối dòng (Adornments)

Start & End Adornments

Dễ dàng chèn icon chỉ dẫn ở đầu ô nhập hoặc các nút thao tác tương tác (Clear, Show/Hide Password) ở cuối ô nhập.

Tìm kiếm với nút Xóa nhanh

Clear Action

Tìm kiếm tài liệu & API

Nhấn nút mũi tên tròn ở góc phải để xóa văn bản vừa nhập.

Mật khẩu với nút Ẩn / Hiện

Toggle Visibility

Mật khẩu quản trị viên

Nhấp vào biểu tượng con mắt để xem trước mật khẩu.

5. Bố cục ngang (Horizontal Layout) cho Trang Cài Đặt

Admin Settings Layout

Hỗ trợ thuộc tính orientation='horizontal' tự động chuyển đổi sang dạng grid 3 cột trên màn hình desktop, tiêu chuẩn của các trang Settings/Profile.

Tên trang webTên hiển thị trên thanh tiêu đề trình duyệt và email thông báo.

Email hỗ trợ kỹ thuật

Địa chỉ tiếp nhận thông báo lỗi hệ thống khẩn cấp.

Thông báo bảo trì hệ thốngTùy chọn

Hiển thị dạng banner cảnh báo trên thanh điều hướng người dùng.

6. Multi-control Fields với ArkField.Item & target

Field.Item & Target

Khi một Field chứa nhiều ô nhập liệu (ví dụ: Chọn tiền tệ + Ô nhập số tiền), sử dụng ArkField.Item và target để gán nhãn chính xác vào ô mong muốn.

Hạn mức giao dịch chuyển tiền

Nhấp vào nhãn trên sẽ tự động kích hoạt focus vào ô nhập số tiền nhờ thuộc tính target="amount-input".

7. Tích hợp với các thành phần Ark UI khác (ArkSwitch, ArkPinInput)

Ark UI Ecosystem Integration

Các thành phần form trong hệ sinh thái Ark UI tự động nhận biết và kế thừa trạng thái disabled, invalid, required khi được đặt trong ArkField.Root.

Tích hợp với ArkSwitch

ArkSwitch in Field

Label của Field tự động kích hoạt chuyển trạng thái Switch khi người dùng nhấp vào.

Xác thực 2 yếu tố (2FA) bắt buộcYêu cầu mã TOTP khi đăng nhập từ thiết bị mới.

Tích hợp với ArkPinInput

ArkPinInput in Field

Mã PIN bảo mật kế thừa ngữ cảnh trợ năng và thông báo lỗi tập trung.

Mã PIN giao dịch khẩn cấp (6 số)

Mã PIN bảo mật gồm 6 số, không chia sẻ cho bất kỳ ai.

8. Form kiểm tra hợp lệ thời gian thực (Real-time Validation Demo)

Form Validation

Mẫu form đăng ký hoàn chỉnh kiểm tra logic dữ liệu khi người dùng submit hoặc tương tác, kích hoạt ErrorText linh hoạt.

9. Bảng tra cứu thành phần & Thuộc tính (API Reference)

Reference Guide

Tổng quan đầy đủ các subcomponents và props được hỗ trợ trong gói ArkField.

Thành phần (Component)	Anatomy Part	Props bổ sung	Mô tả chức năng
ArkField.Root	root	size, orientation, required, invalid, disabled, readOnly	Container cấp cao quản lý context trợ năng WAI-ARIA cho toàn bộ field.
ArkField.Label	label	optional, optionalText, showRequiredIndicator, requiredMark	Nhãn hiển thị, tự động liên kết với control qua id và hỗ trợ indicator bắt buộc/tùy chọn.
ArkField.Input	input	size, startAdornment, endAdornment, wrapperClassName	Ô nhập liệu native input bọc sẵn style Tailwind v4 và hỗ trợ icon hai đầu.
ArkField.Textarea	textarea	size, autoresize	Ô nhập nhiều dòng với tính năng autoresize tự động chỉnh chiều cao.
ArkField.Select	select	size	Menu chọn lựa native select với giao diện đồng bộ hệ thống.
ArkField.HelperText	helper-text	size	Văn bản chỉ dẫn phụ, tự động liên kết với control qua aria-describedby.
ArkField.ErrorText	error-text	size, icon	Thông báo lỗi màu đỏ tự động hiển thị khi invalid=true, ẩn khi hợp lệ.
ArkField.RequiredIndicator	required-indicator	fallback	Dấu hoa thị đỏ (*) hoặc nội dung thay thế hiển thị khi trường là bắt buộc.
ArkField.Item	item	value	Phân nhóm ô nhập liệu trong trường hợp một field có nhiều controls.

Notifications