Ark UI Primitives@ark-ui/react/fieldsetTailwind CSS v4

Ark Fieldset

Thành phần nhóm các trường nhập liệu chuẩn ngữ nghĩa HTML5 <fieldset> và <legend>. Tích hợp máy trạng thái Zag.js, hỗ trợ tính năng tự động vô hiệu hóa (cascade disabled) toàn bộ form controls bên trong, thông báo lỗi WAI-ARIA, 5 biến thể kiểu dáng và 4 kích cỡ token tiêu chuẩn.

Chuẩn HTML5 & WAI-ARIA

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

5 kiểu dáng (Variants)

Shorthand & Compound API

1. Hai phương thức sử dụng: Shorthand & Compound Anatomy

Hai mô hình API

ArkFieldset hỗ trợ cả cú pháp 1 dòng tiện ích (Shorthand) lẫn cấu trúc Compound Components để tùy biến sâu sắc.

Cách 1: Shorthand APINhanh & Tiện lợi

Truyền các props như legend, description, required, actions trực tiếp vào component.

Thông tin định danh

Bắt buộc

Nhập họ tên và mã số định danh nhân viên

Cách 2: Compound AnatomyTùy biến không giới hạn

Sử dụng ArkFieldset.Root, Legend, HelperText, Content, ErrorText.

Cấu hình Cụm máy chủ

Thiết lập thông số cổng kết nối và giao thức bảo mật SSL.

2. Ma trận kiểu dáng (Variants)

5 Biến thể

Khám phá 5 biến thể trực quan: Plain (tối giản), Card (thẻ nổi), Bordered (viền sắc nét), Subtle (nền dịu) và Outline (kính mờ).

Plain (Tối giản)(Không bắt buộc)

Không viền ngoài, không padding dư thừa, phù hợp nhóm form phẳng.

Card (Thẻ nổi)

Khung thẻ hoàn chỉnh với đường viền, bo góc 2xl và đổ bóng nhẹ.

Bordered (Đường viền)

Đường viền sắc nét, bo góc chuẩn, nền trong suốt.

Subtle (Nền dịu)

Nền mềm mại với đường viền mờ, phân cấp thị giác trang nhã.

Outline (Kính mờ)

Đường viền mảnh kết hợp hiệu ứng kính mờ (backdrop blur).

3. Đồng bộ kích thước Controls (Sizes Matrix)

xs / sm / md / lg

Cả 4 kích cỡ (xs, sm, md, lg) được chuẩn hóa theo token ControlSize, căn chỉnh hoàn hảo với Input, Button và Switch.

Chọn kích thước demo:

Fieldset Kích cỡ: MD

Token md

Khoảng cách padding, gap và cỡ chữ đang tự động đồng bộ theo token size: md

Kích hoạt tự động lưu

So sánh trực tiếp cả 4 kích cỡ (xs, sm, md, lg):

Extra Small (xs)

Token padding & gap tự động tính toán theo xs

Small (sm)

Token padding & gap tự động tính toán theo sm

Medium (md)

Token padding & gap tự động tính toán theo md

Large (lg)

Token padding & gap tự động tính toán theo lg

4. Trạng thái tương tác & Kiểm tra tính hợp lệ (States & Validation)

Interactive Controls

Kiểm thử tính năng tự động vô hiệu hóa toàn bộ controls bên trong (HTML5 Cascade Disabled) và thông báo lỗi WAI-ARIA.

Vô hiệu hóa (disabled)Báo lỗi (invalid)Dấu bắt buộc (*)Dấu không bắt buộc

Kiểu Legend:

Cài đặt Quyền riêng tư & Bảo mật

Hoạt động

Quản lý phương thức xác thực và phiên đăng nhập người dùng.

Xác thực 2 yếu tố qua ứng dụng Authenticator (TOTP)

Tăng cường bảo vệ tài khoản bằng mã OTP 6 chữ số.

Đăng xuất khỏi tất cả thiết bị khác khi đổi mật khẩu

Hủy phiên đăng nhập cũ trên điện thoại và máy tính bảng.

5. Kịch bản ứng dụng thực tế (Real-World Scenarios)

Thực tế

Khám phá các mô hình thiết kế thực tế: Hồ sơ người dùng, Thanh toán trực tuyến, Cấu hình thông báo và Fieldset lồng nhau.

Kịch bản 1: Hồ sơ & Thông tin tài khoản người dùng

Hồ sơ tác giả bài viết

Thông tin hiển thị công khai ở chân trang bài viết và trang tác giả.

Họ và tên:

Email công việc:

Tiểu sử ngắn:

Kịch bản 2: Thông tin thanh toán & Thẻ tín dụng quốc tế

Thẻ thanh toán quốc tế (Visa / Mastercard)

Bảo mật 256-bit SSL

Dữ liệu thẻ được mã hóa theo tiêu chuẩn an toàn bảo mật PCI-DSS.

Số thẻ tín dụng:

Hạn sử dụng:

Mã bảo mật CVC:

Mã bưu điện (Zip):

Kịch bản 3: Kênh nhận thông báo hệ thống

Kênh nhận cảnh báo vận hành(Không bắt buộc)

Lựa chọn các phương thức bạn muốn hệ thống gửi thông báo khi có sự cố.

Thông báo qua Email

Bản tin tổng hợp tuần và các cảnh báo khẩn cấp.

Thông báo đẩy Push Notification

Nhận thông báo ngay lập tức trên trình duyệt.

Kịch bản 4: Fieldset lồng nhau (Nested Fieldsets)

Cài đặt Hạ tầng Cloud & Cơ sở dữ liệu

Cấu hình nhiều tầng phân cấp trong các biểu mẫu quản trị phức tạp.

Phân vùng Lưu trữ chính

Amazon S3 bucket

Bộ nhớ đệm Redis Cache

In-memory cache pool

6. Mã nguồn mẫu & Cách tích hợp

Code Snippet

Mã nguồn React mẫu để bạn có thể sao chép và áp dụng ngay vào các module của ChillCMS.

import { ArkFieldset } from '~/components/ui/ark-fieldset';
import { Input } from '~/components/ui/input';

// Cách 1: Shorthand API
<ArkFieldset
  variant="card"
  size="md"
  legend="Thông tin cá nhân"
  description="Vui lòng cung cấp chính xác họ tên và email."
  required
>
  <Input placeholder="Họ và tên..." />
  <Input type="email" placeholder="Địa chỉ email..." />
</ArkFieldset>

// Cách 2: Compound Anatomy API
<ArkFieldset.Root variant="card" size="md">
  <ArkFieldset.Legend required>Thông tin cá nhân</ArkFieldset.Legend>
  <ArkFieldset.HelperText>Vui lòng cung cấp chính xác họ tên và email.</ArkFieldset.HelperText>
  <ArkFieldset.Content>
    <Input placeholder="Họ và tên..." />
    <Input type="email" placeholder="Địa chỉ email..." />
  </ArkFieldset.Content>
  <ArkFieldset.ErrorText>Dữ liệu không hợp lệ.</ArkFieldset.ErrorText>
</ArkFieldset.Root>

7. Tra cứu Props & Cấu trúc thành phần (API Reference)

Documentation

Toàn bộ props của ArkFieldset, các Compound Subcomponents và Zag state machine hook.

Thuộc tính (Prop)	Kiểu dữ liệu (Type)	Mặc định	Mô tả
legend	ReactNode	-	Tiêu đề của Fieldset khi dùng Shorthand API.
description / helperText	ReactNode	-	Đoạn văn mô tả phụ hiển thị bên dưới Legend.
errorText	ReactNode	-	Nội dung thông báo lỗi khi trường hợp `invalid` xảy ra.
variant	'plain' \| 'card' \| 'bordered' \| 'subtle' \| 'outline'	'plain'	Kiểu dáng hiển thị viền và nền của Fieldset.
size	'xs' \| 'sm' \| 'md' \| 'lg'	'md'	Kích cỡ token padding và khoảng cách các trường.
required	boolean	false	Hiển thị dấu hoa thị đỏ (*) báo hiệu nhóm bắt buộc.
optional	boolean	false	Hiển thị dòng chữ `(Không bắt buộc)` cạnh Legend.
disabled	boolean	false	Vô hiệu hóa toàn bộ các input/button bên trong fieldset theo chuẩn HTML5.
invalid	boolean	false	Bật trạng thái lỗi và kích hoạt hiển thị `ErrorText`.
actions	ReactNode	-	Slot nội dung góc phải thanh Legend (nút bấm, badge, switch).
legendVariant	'default' \| 'badge' \| 'bordered'	'default'	Kiểu dáng hiển thị của Legend (tiêu chuẩn, dạng huy hiệu, hoặc gạch chân).

Danh sách Compound Subcomponents:

ArkFieldset.Root: Thẻ fieldset bao ngoài, cung cấp context

ArkFieldset.Legend: Thẻ tiêu đề nhóm biểu mẫu

ArkFieldset.HelperText: Văn bản hướng dẫn phụ

ArkFieldset.ErrorText: Văn bản thông báo lỗi (tự ẩn khi hợp lệ)

ArkFieldset.Content: Container chứa danh sách inputs

ArkFieldset.Context: Render prop truy cập máy trạng thái Zag

Notifications