ArkScrollArea

Ark UI v5Tailwind v4

Thà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.

Tài liệu Ark UI gốc
Ẩn triệt để scrollbar gốc (Chrome, Firefox, Safari, Edge)Zero-Jank Zag.js State MachineShorthand & Compound Component API4 Kích thước (xs, sm, md, lg) & 5 VariantsDark Mode & Theme Token Đồng bộ

Các ví dụ chuẩn từ Ark UI Documentation

ark-ui.com

4 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)

Basic

Tạ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.

2. Horizontal (Cuộn ngang)

Horizontal

Cấu hình thanh cuộn chỉ dành cho chiều ngang khi nội dung tràn theo trục X.

3. Both Directions (Cả hai chiều)

2D

Kí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.

4. Nested (Cuộn lồng nhau)

Nested

Hai 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.

Interactive Playground (Khu vực thử nghiệm tương tác)

Live Demo

Thay đổ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ì.

Kích thước thanh cuộn (Size):
Biến thể (Variant):
Chiều cuộn (Orientation):

Shorthand API vs Compound Component API

Linh hoạt

ArkScrollArea 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.

1. Shorthand API (Gọn nhẹ)Khuyên dùng

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.

Shorthand.tsx
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>
  );
}
2. Compound Component API (Kiểm soát chi tiết)Tối đa tùy biến

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.

Compound.tsx
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)

Vertical

Ví 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ế.

chillcms-runtime.log
12 dòng sự kiện

Thanh cuộn ngang: Danh mục sản phẩm & Thẻ lọc (Horizontal Reel)

Horizontal

Thanh 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.

Chọn phân loại mua sắm:Kéo chuột hoặc cuộn ngang (Shift + Scroll)

Cuộn hai chiều (2D Bidirectional - Both Dimensions)

2D Scroll

Hỗ 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.

Điều khiển cuộn qua API & Telemetry (Programmatic Scroll)

Ark API

Sử 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.

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).

Defaultdefault

Thanh cuộn chuẩn, thumb nổi bật khi tương tác.

Subtlesubtle

Đường rãnh thanh mảnh, thumb nhạt hài hoà.

Hoverhover

Ẩn hoàn toàn, chỉ hiện khi rê chuột hoặc cuộn.

Alwaysalways

Luôn hiển thị cố định rãnh và thumb rõ ràng.

Minimalminimal

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 địnhMô 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).
autoScrollbarsbooleantrueTự động sinh các subcomponents Viewport, Content, Scrollbar, Thumb khi dùng Shorthand.
viewportRefRef<HTMLDivElement>undefinedTham chiếu Ref trực tiếp tới phần tử Viewport chứa nội dung cuộn.
viewportClassNamestringundefinedClass name Tailwind áp dụng cho thẻ Viewport.
scrollbarClassNamestringundefinedClass name Tailwind áp dụng cho rãnh trượt Scrollbar.
thumbClassNamestringundefinedClass name Tailwind áp dụng cho nút trượt Thumb.
© 2026. FlatVn All rights reserved. Version 4.4.2