@ehfuse/overlay-scrollbar 1.0.0 → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +68 -139
- package/dist/index.d.ts +14 -3
- package/dist/index.esm.js +262 -236
- package/dist/index.esm.js.map +1 -1
- package/dist/index.js +261 -235
- package/dist/index.js.map +1 -1
- package/dist/src/OverlayScrollbar.d.ts +16 -4
- package/dist/src/OverlayScrollbar.d.ts.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
# OverlayScrollbar
|
|
2
2
|
|
|
3
|
-
A React component that provides a
|
|
3
|
+
A highly customizable React component that provides a beautiful overlay scrollbar with extensive styling options, interactive features, and smooth animations.
|
|
4
|
+
|
|
5
|
+
다양한 스타일링 옵션, 인터랙티브 기능, 부드러운 애니메이션을 제공하는 고도로 커스터마이징 가능한 React 오버레이 스크롤바 컴포넌트입니다.
|
|
4
6
|
|
|
5
7
|
## 📚 Documentation
|
|
6
8
|
|
|
@@ -9,14 +11,31 @@ A React component that provides a custom overlay scrollbar with smooth animation
|
|
|
9
11
|
|
|
10
12
|
## Features
|
|
11
13
|
|
|
12
|
-
- 🎨 **
|
|
13
|
-
-
|
|
14
|
-
-
|
|
15
|
-
-
|
|
16
|
-
-
|
|
17
|
-
-
|
|
18
|
-
-
|
|
19
|
-
-
|
|
14
|
+
- 🎨 **Fully Customizable** - Control colors, sizes, radius, and positioning of all scrollbar elements
|
|
15
|
+
- 🏹 **Arrow Navigation** - Optional arrow buttons for precise scrolling control
|
|
16
|
+
- ⚡ **Smooth Animations** - Fade-in/out transitions with hover effects and drag feedback
|
|
17
|
+
- 🔍 **Smart Auto-hide** - Intelligent visibility management based on scroll state and user interaction
|
|
18
|
+
- 📐 **Flexible Sizing** - Independent control of track width, thumb width, and minimum thumb height
|
|
19
|
+
- 🎯 **Interactive** - Click-to-scroll, drag-to-scroll, and wheel event handling
|
|
20
|
+
- 🖱️ **Hover Effects** - Visual feedback on hover for arrows and improved UX
|
|
21
|
+
- 📱 **True Overlay** - Doesn't affect content layout, floats over content
|
|
22
|
+
- 🔧 **TypeScript** - Complete TypeScript support with detailed type definitions
|
|
23
|
+
- 🪶 **Zero Dependencies** - Only requires React, no external libraries
|
|
24
|
+
- ♿ **Accessible** - Preserves native scroll behavior while enhancing visual presentation
|
|
25
|
+
|
|
26
|
+
## 기능 소개
|
|
27
|
+
|
|
28
|
+
- 🎨 **완전한 커스터마이징** - 스크롤바의 모든 요소에 대한 색상, 크기, 둥근 모서리, 위치 제어
|
|
29
|
+
- 🏹 **화살표 내비게이션** - 정밀한 스크롤 제어를 위한 선택적 화살표 버튼
|
|
30
|
+
- ⚡ **부드러운 애니메이션** - 호버 효과와 드래그 피드백이 포함된 페이드 인/아웃 전환
|
|
31
|
+
- 🔍 **스마트 자동 숨김** - 스크롤 상태와 사용자 상호작용에 기반한 지능적인 표시 관리
|
|
32
|
+
- 📐 **유연한 크기 조정** - 트랙 너비, 썸 너비, 최소 썸 높이의 독립적 제어
|
|
33
|
+
- 🎯 **인터랙티브** - 클릭 스크롤, 드래그 스크롤, 휠 이벤트 처리
|
|
34
|
+
- 🖱️ **호버 효과** - 화살표 호버 시 시각적 피드백 및 향상된 UX
|
|
35
|
+
- 📱 **진정한 오버레이** - 콘텐츠 레이아웃에 영향을 주지 않고 콘텐츠 위에 떠 있음
|
|
36
|
+
- 🔧 **TypeScript** - 상세한 타입 정의를 포함한 완전한 TypeScript 지원
|
|
37
|
+
- 🪶 **의존성 없음** - React만 필요하며 외부 라이브러리 불필요
|
|
38
|
+
- ♿ **접근성** - 시각적 표현을 향상시키면서 기본 스크롤 동작 보존
|
|
20
39
|
|
|
21
40
|
## Installation
|
|
22
41
|
|
|
@@ -30,6 +49,18 @@ or
|
|
|
30
49
|
yarn add @ehfuse/overlay-scrollbar
|
|
31
50
|
```
|
|
32
51
|
|
|
52
|
+
## 설치
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
npm install @ehfuse/overlay-scrollbar
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
또는
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
yarn add @ehfuse/overlay-scrollbar
|
|
62
|
+
```
|
|
63
|
+
|
|
33
64
|
## Quick Start
|
|
34
65
|
|
|
35
66
|
For detailed setup instructions, see the [Getting Started Guide](https://github.com/ehfuse/overlay-scrollbar/blob/main/docs/getting-started-en.md).
|
|
@@ -41,9 +72,18 @@ import { OverlayScrollbar } from "@ehfuse/overlay-scrollbar";
|
|
|
41
72
|
function App() {
|
|
42
73
|
return (
|
|
43
74
|
<div style={{ height: "400px" }}>
|
|
44
|
-
<OverlayScrollbar
|
|
75
|
+
<OverlayScrollbar
|
|
76
|
+
showArrows={true}
|
|
77
|
+
thumbRadius={6}
|
|
78
|
+
trackColor="rgba(0, 0, 0, 0.1)"
|
|
79
|
+
thumbColor="rgba(100, 100, 100, 0.7)"
|
|
80
|
+
arrowColor="rgba(80, 80, 80, 0.8)"
|
|
81
|
+
hideDelay={1500} // Auto-hide after 1.5s
|
|
82
|
+
hideDelayOnWheel={700} // Quick hide after wheel scroll
|
|
83
|
+
>
|
|
45
84
|
<div style={{ height: "1000px" }}>
|
|
46
85
|
{/* Your scrollable content here */}
|
|
86
|
+
<p>Content that requires scrolling...</p>
|
|
47
87
|
</div>
|
|
48
88
|
</OverlayScrollbar>
|
|
49
89
|
</div>
|
|
@@ -51,9 +91,9 @@ function App() {
|
|
|
51
91
|
}
|
|
52
92
|
```
|
|
53
93
|
|
|
54
|
-
##
|
|
94
|
+
## 빠른 시작
|
|
55
95
|
|
|
56
|
-
|
|
96
|
+
자세한 설정 지침은 [시작하기 가이드](https://github.com/ehfuse/overlay-scrollbar/blob/main/docs/getting-started-ko.md)를 참조하세요.
|
|
57
97
|
|
|
58
98
|
```tsx
|
|
59
99
|
import React from "react";
|
|
@@ -62,10 +102,18 @@ import { OverlayScrollbar } from "@ehfuse/overlay-scrollbar";
|
|
|
62
102
|
function App() {
|
|
63
103
|
return (
|
|
64
104
|
<div style={{ height: "400px" }}>
|
|
65
|
-
<OverlayScrollbar
|
|
105
|
+
<OverlayScrollbar
|
|
106
|
+
showArrows={true}
|
|
107
|
+
thumbRadius={6}
|
|
108
|
+
trackColor="rgba(0, 0, 0, 0.1)"
|
|
109
|
+
thumbColor="rgba(100, 100, 100, 0.7)"
|
|
110
|
+
arrowColor="rgba(80, 80, 80, 0.8)"
|
|
111
|
+
hideDelay={1500} // 1.5초 후 자동 숨김
|
|
112
|
+
hideDelayOnWheel={700} // 휠 스크롤 후 빠른 숨김
|
|
113
|
+
>
|
|
66
114
|
<div style={{ height: "1000px" }}>
|
|
67
|
-
{/*
|
|
68
|
-
<p
|
|
115
|
+
{/* 스크롤 가능한 콘텐츠 */}
|
|
116
|
+
<p>스크롤이 필요한 콘텐츠...</p>
|
|
69
117
|
</div>
|
|
70
118
|
</OverlayScrollbar>
|
|
71
119
|
</div>
|
|
@@ -73,125 +121,6 @@ function App() {
|
|
|
73
121
|
}
|
|
74
122
|
```
|
|
75
123
|
|
|
76
|
-
### With Ref Access
|
|
77
|
-
|
|
78
|
-
```tsx
|
|
79
|
-
import React, { useRef } from "react";
|
|
80
|
-
import {
|
|
81
|
-
OverlayScrollbar,
|
|
82
|
-
OverlayScrollbarRef,
|
|
83
|
-
} from "@ehfuse/overlay-scrollbar";
|
|
84
|
-
|
|
85
|
-
function App() {
|
|
86
|
-
const scrollbarRef = useRef<OverlayScrollbarRef>(null);
|
|
87
|
-
|
|
88
|
-
const scrollToTop = () => {
|
|
89
|
-
scrollbarRef.current?.scrollTo({ top: 0, behavior: "smooth" });
|
|
90
|
-
};
|
|
91
|
-
|
|
92
|
-
const getScrollInfo = () => {
|
|
93
|
-
if (scrollbarRef.current) {
|
|
94
|
-
console.log("Scroll Top:", scrollbarRef.current.scrollTop);
|
|
95
|
-
console.log("Scroll Height:", scrollbarRef.current.scrollHeight);
|
|
96
|
-
console.log("Client Height:", scrollbarRef.current.clientHeight);
|
|
97
|
-
}
|
|
98
|
-
};
|
|
99
|
-
|
|
100
|
-
return (
|
|
101
|
-
<div style={{ height: "400px" }}>
|
|
102
|
-
<button onClick={scrollToTop}>Scroll to Top</button>
|
|
103
|
-
<button onClick={getScrollInfo}>Get Scroll Info</button>
|
|
104
|
-
|
|
105
|
-
<OverlayScrollbar ref={scrollbarRef}>
|
|
106
|
-
<div style={{ height: "1000px" }}>
|
|
107
|
-
{/* Your scrollable content here */}
|
|
108
|
-
</div>
|
|
109
|
-
</OverlayScrollbar>
|
|
110
|
-
</div>
|
|
111
|
-
);
|
|
112
|
-
}
|
|
113
|
-
```
|
|
114
|
-
|
|
115
|
-
### With Custom Styling
|
|
116
|
-
|
|
117
|
-
```tsx
|
|
118
|
-
import React from "react";
|
|
119
|
-
import { OverlayScrollbar } from "@ehfuse/overlay-scrollbar";
|
|
120
|
-
|
|
121
|
-
function App() {
|
|
122
|
-
return (
|
|
123
|
-
<OverlayScrollbar
|
|
124
|
-
className="my-scrollbar"
|
|
125
|
-
style={{
|
|
126
|
-
height: "400px",
|
|
127
|
-
border: "1px solid #ccc",
|
|
128
|
-
borderRadius: "8px",
|
|
129
|
-
}}
|
|
130
|
-
onScroll={(event) => {
|
|
131
|
-
console.log("Scrolled!", event);
|
|
132
|
-
}}
|
|
133
|
-
>
|
|
134
|
-
<div style={{ height: "1000px", padding: "20px" }}>
|
|
135
|
-
{/* Your content */}
|
|
136
|
-
</div>
|
|
137
|
-
</OverlayScrollbar>
|
|
138
|
-
);
|
|
139
|
-
}
|
|
140
|
-
```
|
|
141
|
-
|
|
142
|
-
## API Reference
|
|
143
|
-
|
|
144
|
-
### Props
|
|
145
|
-
|
|
146
|
-
| Prop | Type | Default | Description |
|
|
147
|
-
| ----------- | ------------------------ | ------- | ------------------------------------------ |
|
|
148
|
-
| `children` | `ReactNode` | - | The content to be scrolled |
|
|
149
|
-
| `className` | `string` | - | Additional CSS class for the container |
|
|
150
|
-
| `style` | `React.CSSProperties` | - | Additional inline styles for the container |
|
|
151
|
-
| `onScroll` | `(event: Event) => void` | - | Callback fired when scrolling occurs |
|
|
152
|
-
|
|
153
|
-
### Ref Methods
|
|
154
|
-
|
|
155
|
-
The component exposes several methods through ref:
|
|
156
|
-
|
|
157
|
-
| Method | Type | Description |
|
|
158
|
-
| -------------------- | ------------------------------------ | ---------------------------------------- |
|
|
159
|
-
| `getScrollContainer` | `() => HTMLDivElement \| null` | Returns the scrollable container element |
|
|
160
|
-
| `scrollTo` | `(options: ScrollToOptions) => void` | Scrolls to a specific position |
|
|
161
|
-
| `scrollTop` | `number` | Gets the current scroll top position |
|
|
162
|
-
| `scrollHeight` | `number` | Gets the total scrollable height |
|
|
163
|
-
| `clientHeight` | `number` | Gets the visible height of the container |
|
|
164
|
-
|
|
165
|
-
### ScrollToOptions
|
|
166
|
-
|
|
167
|
-
```typescript
|
|
168
|
-
interface ScrollToOptions {
|
|
169
|
-
top?: number;
|
|
170
|
-
left?: number;
|
|
171
|
-
behavior?: "auto" | "smooth";
|
|
172
|
-
}
|
|
173
|
-
```
|
|
174
|
-
|
|
175
|
-
## Behavior
|
|
176
|
-
|
|
177
|
-
- **Auto-hide**: The scrollbar automatically hides after 0.7 seconds of inactivity during wheel scroll or regular scrolling
|
|
178
|
-
- **Hover reveal**: Hovering over the right edge (20px wide area) shows the scrollbar with track background
|
|
179
|
-
- **Interactive scrolling**:
|
|
180
|
-
- Click on the track to jump to that position
|
|
181
|
-
- Drag the thumb for precise scrolling
|
|
182
|
-
- Mouse wheel scrolling works normally
|
|
183
|
-
- **Responsive**: Automatically adapts to content and container size changes
|
|
184
|
-
- **Smooth animations**: All show/hide transitions are smoothly animated
|
|
185
|
-
|
|
186
|
-
## Styling
|
|
187
|
-
|
|
188
|
-
The component uses CSS-in-JS for styling and automatically hides native scrollbars. The custom scrollbar has:
|
|
189
|
-
|
|
190
|
-
- **Track**: Semi-transparent background that appears on hover/interaction
|
|
191
|
-
- **Thumb**: The draggable scrollbar handle with hover effects
|
|
192
|
-
- **Positioning**: 8px wide, positioned 2px from the right edge
|
|
193
|
-
- **Colors**: Configurable through CSS custom properties (future enhancement)
|
|
194
|
-
|
|
195
124
|
## Browser Support
|
|
196
125
|
|
|
197
126
|
- Chrome/Edge: Full support
|
|
@@ -199,12 +128,12 @@ The component uses CSS-in-JS for styling and automatically hides native scrollba
|
|
|
199
128
|
- Safari: Full support
|
|
200
129
|
- Mobile browsers: Touch scrolling supported, overlay scrollbar hidden on mobile
|
|
201
130
|
|
|
202
|
-
##
|
|
131
|
+
## 브라우저 지원
|
|
203
132
|
|
|
204
|
-
-
|
|
205
|
-
-
|
|
206
|
-
-
|
|
207
|
-
-
|
|
133
|
+
- Chrome/Edge: 완전 지원
|
|
134
|
+
- Firefox: 완전 지원
|
|
135
|
+
- Safari: 완전 지원
|
|
136
|
+
- 모바일 브라우저: 터치 스크롤 지원, 모바일에서는 오버레이 스크롤바 숨김
|
|
208
137
|
|
|
209
138
|
## License
|
|
210
139
|
|
package/dist/index.d.ts
CHANGED
|
@@ -3,9 +3,6 @@ import React, { ReactNode } from 'react';
|
|
|
3
3
|
/**
|
|
4
4
|
* OverlayScrollbar.tsx
|
|
5
5
|
*
|
|
6
|
-
* A React component that provides a custom overlay scrollbar with smooth animations and auto-hide functionality
|
|
7
|
-
*
|
|
8
|
-
* @license MIT
|
|
9
6
|
* @copyright 2025 KIM YOUNG JIN (ehfuse@gmail.com)
|
|
10
7
|
*
|
|
11
8
|
* Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
@@ -32,6 +29,20 @@ interface OverlayScrollbarProps {
|
|
|
32
29
|
style?: React.CSSProperties;
|
|
33
30
|
children: ReactNode;
|
|
34
31
|
onScroll?: (event: Event) => void;
|
|
32
|
+
scrollbarWidth?: number;
|
|
33
|
+
thumbRadius?: number;
|
|
34
|
+
showArrows?: boolean;
|
|
35
|
+
arrowStep?: number;
|
|
36
|
+
trackWidth?: number;
|
|
37
|
+
thumbWidth?: number;
|
|
38
|
+
thumbMinHeight?: number;
|
|
39
|
+
trackColor?: string;
|
|
40
|
+
thumbColor?: string;
|
|
41
|
+
thumbActiveColor?: string;
|
|
42
|
+
arrowColor?: string;
|
|
43
|
+
arrowActiveColor?: string;
|
|
44
|
+
hideDelay?: number;
|
|
45
|
+
hideDelayOnWheel?: number;
|
|
35
46
|
}
|
|
36
47
|
interface OverlayScrollbarRef {
|
|
37
48
|
getScrollContainer: () => HTMLDivElement | null;
|