@libs-ui/components-scroll-overlay

Directive tạo thanh cuộn tùy chỉnh (custom scrollbar) thay thế thanh cuộn mặc định của trình duyệt.

Giới thiệu

LibsUiComponentsScrollOverlayDirective là một standalone Angular directive giúp tạo ra thanh cuộn tùy chỉnh với giao diện đẹp mắt, hỗ trợ kéo thả, tự động ẩn hiện và tùy biến màu sắc.

Tính năng

• ✅ Custom Scrollbar (thay thế native scrollbar)
• ✅ Hỗ trợ cả chiều ngang (Horizontal) và chiều dọc (Vertical)
• ✅ Tự động ẩn hiện khi hover
• ✅ Hỗ trợ kéo thả (Drag & Drop) thanh cuộn
• ✅ Tùy biến màu sắc, kích thước
• ✅ Hỗ trợ Mobile/Touch devices (thông qua getDragEventByElement)
• ✅ Resize Observer tự động cập nhật kích thước

Khi nào sử dụng

• Khi cần giao diện thanh cuộn đồng bộ trên các trình duyệt/hệ điều hành khác nhau.
• Khi cần thanh cuộn nhỏ gọn, overlay lên nội dung mà không chiếm diện tích layout.
• Khi cần tùy biến màu sắc thanh cuộn theo theme của ứng dụng.

Cài đặt

# npm
npm install @libs-ui/components-scroll-overlay

# yarn
yarn add @libs-ui/components-scroll-overlay

Import

import { LibsUiComponentsScrollOverlayDirective } from '@libs-ui/components-scroll-overlay';

@Component({
  standalone: true,
  imports: [LibsUiComponentsScrollOverlayDirective],
  // ...
})
export class YourComponent {}

Ví dụ

Basic

Thêm directive vào phần tử có overflow: scroll hoặc overflow: auto.

<div
  LibsUiComponentsScrollOverlayDirective
  class="h-[300px] w-full overflow-y-auto">
  <!-- Content dài -->
</div>

With Options

<div
  LibsUiComponentsScrollOverlayDirective
  [options]="{
    scrollbarColor: '#e5e7eb',
    scrollThumbColor: '#9ca3af',
    scrollbarWidth: 8,
    scrollbarPadding: 0
  }"
  class="h-[300px] w-full overflow-y-auto">
  <!-- Content -->
</div>

API

LibsUiComponentsScrollOverlayDirective

Selector: [LibsUiComponentsScrollOverlayDirective]

Inputs

| Property | Type | Default | Description | | ----------------------- | ----------------------- | -------------- | ------------------------------------------------------------- | | [options] | IScrollOverlayOptions | {} | Cấu hình cho thanh cuộn (màu sắc, kích thước, behavior). | | [classContainer] | string | '' | Class CSS thêm vào container bao ngoài (do directive tạo ra). | | [elementScroll] | HTMLElement | Host Element | Element cần scroll (mặc định là element gắn directive). | | [elementCheckScrollX] | HTMLElement | undefined | Element để tính toán scroll width (nếu khác element scroll). | | [elementCheckScrollY] | HTMLElement | undefined | Element để tính toán scroll height (nếu khác element scroll). | | [debugMode] | boolean | false | Bật chế độ debug log. | | [ignoreInit] | boolean | false | Nếu true, directive sẽ không khởi tạo scrollbar. |

Outputs

| Property | Type | Description | | ------------------- | ------- | ---------------------------------------- | | (outScroll) | Event | Emit khi scroll event xảy ra. | | (outScrollX) | Event | Emit khi scroll chiều ngang thay đổi. | | (outScrollY) | Event | Emit khi scroll chiều dọc thay đổi. | | (outScrollTop) | Event | Emit khi scroll lên đầu (scrollTop = 0). | | (outScrollBottom) | Event | Emit khi scroll xuống cuối. |

Types & Interfaces

export type TYPE_SCROLL_DIRECTION = 'X' | 'Y';
export type TYPE_SCROLL_OVERFLOW = 'hidden' | 'scroll';

export interface IScrollOverlayOptions {
  ignoreTransparentScrollBarColorDefault?: boolean; // Nếu true, dùng 'auto' thay vì 'transparent' cho scrollbar-color
  scrollbarWidth?: number; // Độ rộng của track scrollbar (default: 10)
  scrollbarColor?: string; // Màu nền của track
  scrollbarHoverColor?: string; // Màu nền của track khi hover
  scrollThumbColor?: string; // Màu của thanh cuộn (thumb)
  scrollThumbHoverColor?: string; // Màu của thanh cuộn khi hover
  scrollbarPadding?: number; // Padding cho thumb (default: 2)
  scrollX?: TYPE_SCROLL_OVERFLOW; // 'scroll' hoặc 'hidden' cho chiều ngang
  scrollXOpacity0?: boolean; // Nếu true, thanh cuộn ngang vĩnh viễn ẩn (opacity 0) nhưng vẫn scroll được? (Check logic: visible but opacity 0)
  scrollY?: TYPE_SCROLL_OVERFLOW; // 'scroll' hoặc 'hidden' cho chiều dọc
  scrollYOpacity0?: boolean; // Tương tự cho chiều dọc
}

Styling

Directive tự động inject styles vào thẻ <style id="id-style-tag-custom-scroll-overlay"> trong <head>. Cấu trúc DOM được tạo ra:

<div class="lib-ui-scroll-overlay-container ...">
  <!-- Host Element -->
  <div class="scrollbar-track scrollbar-track-X">
    <div class="scrollbar-thumb scrollbar-thumb-X"></div>
  </div>
  <div class="scrollbar-track scrollbar-track-Y">
    <div class="scrollbar-thumb scrollbar-thumb-Y"></div>
  </div>
</div>

Công nghệ

| Technology | Version | Purpose | | ---------- | ------- | ------------------- | | Angular | 18+ | Framework | | RxJS | 7.x | Event Handling | | DOM API | - | Scroll Manipulation |

Demo

npx nx serve core-ui

Truy cập: http://localhost:4500/components/scroll-overlay