ArkScrollArea
Ark UI v5Tailwind v4Thành phần thanh cuộn tùy chỉnh thế hệ mới kết hợp giữa @ark-ui/react/scroll-area (Zag.js state machine) và Tailwind CSS v4. Ẩn hoàn toàn thanh cuộn trình duyệt mặc định, hỗ trợ cuộn dọc, ngang, 2 chiều, 5 kiểu giao diện và điều khiển qua API.
Các ví dụ chuẩn từ Ark UI Documentation
ark-ui.com4 trường hợp sử dụng kinh điển theo tài liệu gốc tại ark-ui.com/docs/components/scroll-area . Thanh cuộn (scrollbar) và nút trượt (thumb) hiển thị sắc nét, tương tác kéo chuột mượt mà.
1. Basic (Cuộn dọc cơ bản)
BasicTạo vùng cuộn cơ bản với thanh cuộn dọc tùy biến, thumb tự động co giãn theo tỉ lệ nội dung.
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt.
Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem. Ut enim ad minima veniam, quis nostrum exercitationem ullam corporis suscipit laboriosam.
2. Horizontal (Cuộn ngang)
HorizontalCấu hình thanh cuộn chỉ dành cho chiều ngang khi nội dung tràn theo trục X.
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo.
3. Both Directions (Cả hai chiều)
2DKích hoạt đồng thời cả thanh cuộn dọc và ngang, nút Corner ở góc giao nhau kết nối liền lạc.
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt.
At vero eos et accusamus et iusto odio dignissimos ducimus qui blanditiis praesentium voluptatum deleniti atque corrupti quos dolores et quas molestias excepturi sint occaecati cupiditate non provident, similique sunt in culpa qui officia deserunt mollitia animi, id est laborum et dolorum fuga.
4. Nested (Cuộn lồng nhau)
NestedHai vùng cuộn lồng nhau với cơ chế cô lập sự kiện cuộn thông minh từ Zag.js.
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Đây là vùng cuộn bên trong (Inner Nested Scroll Area). Khi cuộn chuột tại đây, sự kiện cuộn được Zag.js cô lập chính xác cho khung nhìn bên trong mà không làm giật khung ngoài.
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo.
Đoạn văn tiếp theo của vùng cuộn ngoài. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
Interactive Playground (Khu vực thử nghiệm tương tác)
Live DemoThay đổi trực tiếp kích thước, biến thể giao diện và chiều cuộn để kiểm tra phản hồi tức thì.
Thanh cuộn tuỳ biến tối ưu hoá hiệu năng
ArkScrollArea sử dụng Zag.js để tính toán chính xác vị trí con trỏ, kích thước nút cuộn (thumb) và khung nhìn (viewport). Hệ thống hoàn toàn không can thiệp trực tiếp vào luồng cuộn tự nhiên của hệ điều hành, đảm bảo độ mượt 60fps / 120fps.
Đang kết nối qua kênh truyền dữ liệu bảo mật ChillCMS.
Đang kết nối qua kênh truyền dữ liệu bảo mật ChillCMS.
Đang kết nối qua kênh truyền dữ liệu bảo mật ChillCMS.
Đang kết nối qua kênh truyền dữ liệu bảo mật ChillCMS.
Đang kết nối qua kênh truyền dữ liệu bảo mật ChillCMS.
Đang kết nối qua kênh truyền dữ liệu bảo mật ChillCMS.
// Cấu hình đang áp dụng:
size="md" | variant="default" | orientation="vertical"
Shorthand API vs Compound Component API
Linh hoạtArkScrollArea hỗ trợ cả hai phong cách: dùng gọn gàng chỉ với một component hoặc ghép nối chi tiết từng thành phần.
Chỉ cần truyền nội dung vào <ArkScrollArea>, các thành phần Viewport, Content, Scrollbar và Thumb sẽ tự động được thiết lập.
import { ArkScrollArea } from '~/components/ui/ark-scroll-area';
export function QuickList() {
return (
<ArkScrollArea
className="h-60 rounded-xl border border-border"
size="sm"
variant="hover"
orientation="vertical"
>
<div className="p-4 space-y-2">
{/* Danh sách nội dung cần cuộn */}
</div>
</ArkScrollArea>
);
}Cho phép gắn class name riêng cho từng phần, tuỳ biến vị trí scrollbar hoặc kết hợp với các thành phần UI khác.
import { ArkScrollArea } from '~/components/ui/ark-scroll-area';
export function CustomScrollLayout() {
return (
<ArkScrollArea.Root size="md" variant="subtle" className="h-60 rounded-xl border">
<ArkScrollArea.Viewport className="p-4">
<ArkScrollArea.Content>
{/* Nội dung tuỳ biến */}
</ArkScrollArea.Content>
</ArkScrollArea.Viewport>
<ArkScrollArea.Scrollbar orientation="vertical">
<ArkScrollArea.Thumb />
</ArkScrollArea.Scrollbar>
<ArkScrollArea.Corner />
</ArkScrollArea.Root>
);
}Danh sách dọc: Nhật ký hệ thống (System Activity Log)
VerticalVí dụ ứng dụng thanh cuộn dọc cho màn hình xem log hoặc tin nhắn chat với variant 'hover' tinh tế.
Thanh cuộn ngang: Danh mục sản phẩm & Thẻ lọc (Horizontal Reel)
HorizontalThanh cuộn ngang với variant 'minimal' mượt mà, giúp người dùng lướt chọn danh mục trên mobile và desktop.
Cuộn hai chiều (2D Bidirectional - Both Dimensions)
2D ScrollHỗ trợ cả thanh cuộn dọc và ngang cùng lúc. Nút giao nhau ở góc dưới cùng bên phải được điều khiển bởi ArkScrollArea.Corner.
| Mã ĐH | Khách hàng | Sản phẩm | Tổng tiền | Trạng thái | Cổng thanh toán | Ngày tạo | |
|---|---|---|---|---|---|---|---|
| #ORD-2026-1000 | Nguyễn Văn 1 | user1@example.com | Gói ChillCMS Premium v1.0 | 250.000 ₫ | Đã thanh toán | VietQR / Momo | 2026-09-22 16:40 |
| #ORD-2026-1001 | Nguyễn Văn 2 | user2@example.com | Gói ChillCMS Premium v2.0 | 500.000 ₫ | Đã thanh toán | VietQR / Momo | 2026-09-22 16:41 |
| #ORD-2026-1002 | Nguyễn Văn 3 | user3@example.com | Gói ChillCMS Premium v3.0 | 750.000 ₫ | Đã thanh toán | VietQR / Momo | 2026-09-22 16:42 |
| #ORD-2026-1003 | Nguyễn Văn 4 | user4@example.com | Gói ChillCMS Premium v4.0 | 1000.000 ₫ | Đã thanh toán | VietQR / Momo | 2026-09-22 16:43 |
| #ORD-2026-1004 | Nguyễn Văn 5 | user5@example.com | Gói ChillCMS Premium v5.0 | 1250.000 ₫ | Đã thanh toán | VietQR / Momo | 2026-09-22 16:44 |
| #ORD-2026-1005 | Nguyễn Văn 6 | user6@example.com | Gói ChillCMS Premium v6.0 | 1500.000 ₫ | Đã thanh toán | VietQR / Momo | 2026-09-22 16:45 |
| #ORD-2026-1006 | Nguyễn Văn 7 | user7@example.com | Gói ChillCMS Premium v7.0 | 1750.000 ₫ | Đã thanh toán | VietQR / Momo | 2026-09-22 16:46 |
| #ORD-2026-1007 | Nguyễn Văn 8 | user8@example.com | Gói ChillCMS Premium v8.0 | 2000.000 ₫ | Đã thanh toán | VietQR / Momo | 2026-09-22 16:47 |
| #ORD-2026-1008 | Nguyễn Văn 9 | user9@example.com | Gói ChillCMS Premium v9.0 | 2250.000 ₫ | Đã thanh toán | VietQR / Momo | 2026-09-22 16:48 |
| #ORD-2026-1009 | Nguyễn Văn 10 | user10@example.com | Gói ChillCMS Premium v10.0 | 2500.000 ₫ | Đã thanh toán | VietQR / Momo | 2026-09-22 16:49 |
| #ORD-2026-1010 | Nguyễn Văn 11 | user11@example.com | Gói ChillCMS Premium v11.0 | 2750.000 ₫ | Đã thanh toán | VietQR / Momo | 2026-09-22 16:410 |
| #ORD-2026-1011 | Nguyễn Văn 12 | user12@example.com | Gói ChillCMS Premium v12.0 | 3000.000 ₫ | Đã thanh toán | VietQR / Momo | 2026-09-22 16:411 |
| #ORD-2026-1012 | Nguyễn Văn 13 | user13@example.com | Gói ChillCMS Premium v13.0 | 3250.000 ₫ | Đã thanh toán | VietQR / Momo | 2026-09-22 16:412 |
| #ORD-2026-1013 | Nguyễn Văn 14 | user14@example.com | Gói ChillCMS Premium v14.0 | 3500.000 ₫ | Đã thanh toán | VietQR / Momo | 2026-09-22 16:413 |
| #ORD-2026-1014 | Nguyễn Văn 15 | user15@example.com | Gói ChillCMS Premium v15.0 | 3750.000 ₫ | Đã thanh toán | VietQR / Momo | 2026-09-22 16:414 |
Điều khiển cuộn qua API & Telemetry (Programmatic Scroll)
Ark APISử dụng useScrollAreaContext() từ @ark-ui/react để đọc vị trí cuộn và kích hoạt cuộn mượt mà bằng lập trình.
Phần 1: Khởi đầu
Đây là vị trí đầu trang. Quan sát chỉ số "Ở đỉnh" trong bảng điều khiển phía dưới.
Nội dung đang được cuộn tự do bằng chuột, phím mũi tên hoặc nút bấm API.
Nội dung đang được cuộn tự do bằng chuột, phím mũi tên hoặc nút bấm API.
Nội dung đang được cuộn tự do bằng chuột, phím mũi tên hoặc nút bấm API.
Nội dung đang được cuộn tự do bằng chuột, phím mũi tên hoặc nút bấm API.
Nội dung đang được cuộn tự do bằng chuột, phím mũi tên hoặc nút bấm API.
Nội dung đang được cuộn tự do bằng chuột, phím mũi tên hoặc nút bấm API.
Phần cuối: Về đích
Đây là vị trí cuối danh sách. Chỉ số "Ở đáy" sẽ chuyển thành Đúng.
5 Biến thể giao diện (Variants Showcase)
Thiết kếĐáp ứng đa dạng nhu cầu thẩm mỹ: default (tiêu chuẩn), subtle (nhẹ nhàng), hover (chỉ hiện khi rê chuột), always (luôn hiện) và minimal (tối giản).
Thanh cuộn chuẩn, thumb nổi bật khi tương tác.
Đường rãnh thanh mảnh, thumb nhạt hài hoà.
Ẩn hoàn toàn, chỉ hiện khi rê chuột hoặc cuộn.
Luôn hiển thị cố định rãnh và thumb rõ ràng.
Siêu mỏng không rãnh nền, hiện đại tối giản.
Bảng tài liệu thuộc tính (API Reference)
Thông số chi tiết các thuộc tính hỗ trợ trên thành phần ArkScrollArea.
| Thuộc tính (Prop) | Kiểu dữ liệu (Type) | Mặc định | Mô tả |
|---|---|---|---|
| orientation | 'vertical' | 'horizontal' | 'both' | 'vertical' | Chiều thanh cuộn: dọc, ngang, hoặc cả hai chiều đồng thời. |
| size | 'xs' | 'sm' | 'md' | 'lg' | 'md' | Độ dày thanh cuộn (xs: 6px, sm: 8px, md: 10px, lg: 14px). |
| variant | 'default' | 'subtle' | 'hover' | 'always' | 'minimal' | 'default' | Biến thể thẩm mỹ của thanh cuộn và nút trượt (thumb). |
| autoScrollbars | boolean | true | Tự động sinh các subcomponents Viewport, Content, Scrollbar, Thumb khi dùng Shorthand. |
| viewportRef | Ref<HTMLDivElement> | undefined | Tham chiếu Ref trực tiếp tới phần tử Viewport chứa nội dung cuộn. |
| viewportClassName | string | undefined | Class name Tailwind áp dụng cho thẻ Viewport. |
| scrollbarClassName | string | undefined | Class name Tailwind áp dụng cho rãnh trượt Scrollbar. |
| thumbClassName | string | undefined | Class name Tailwind áp dụng cho nút trượt Thumb. |