diff --git a/README.md b/README.md
index ddd5141..cb98005 100644
--- a/README.md
+++ b/README.md
@@ -458,6 +458,132 @@ interface OverlayScrollbarsStatic {
}
```
+## Styling
+
+OverlayScrollbars comes with two themes called `os-theme-dark` and `os-theme-light`. You can use the `scrollbars.theme` option to change the theme.
+
+Custom themes can be done in multiple ways. The easiest and fastest is to use the predefined set of `CSS Custom Properties` aka. CSS variables. In case those aren't enought you can add custom class names or add custom styling to the existing class names.
+
+### Styling in depth
+
+
+
+ This is a in depth topic. Click here to read it.
+
+
+ ### CSS Custom properties
+
+ OverlayScrollbars provides a set of `CSS Custom Properties` which makes scrollbar styling easy and fast:
+ ```scss
+ .os-scrollbar {
+ // The size of the scrollbar
+ --os-size: 0;
+ // The axis-perpedicular padding of the scrollbar (horizontal: padding-y, vertical: padding-x)
+ --os-padding-perpendicular: 0;
+ // The axis padding of the scrollbar (horizontal: padding-x, vertical: padding-y)
+ --os-padding-axis: 0;
+ // The border radius of the scrollbar track
+ --os-track-border-radius: 0;
+ // The background of the scrollbar track
+ --os-track-bg: none;
+ // The :hover background of the scrollbar track
+ --os-track-bg-hover: none;
+ // The :active background of the scrollbar track
+ --os-track-bg-active: none;
+ // The border of the scrollbar track
+ --os-track-border: none;
+ // The :hover background of the scrollbar track
+ --os-track-border-hover: none;
+ // The :active background of the scrollbar track
+ --os-track-border-active: none;
+ // The border radius of the scrollbar handle
+ --os-handle-border-radius: 0;
+ // The background of the scrollbar handle
+ --os-handle-bg: none;
+ // The :hover background of the scrollbar handle
+ --os-handle-bg-hover: none;
+ // The :active background of the scrollbar handle
+ --os-handle-bg-active: none;
+ // The border of the scrollbar handle
+ --os-handle-border: none;
+ // The :hover border of the scrollbar handle
+ --os-handle-border-hover: none;
+ // The :active border of the scrollbar handle
+ --os-handle-border-active: none;
+ // The min size of the scrollbar handle
+ --os-handle-min-size: 33px;
+ // The max size of the scrollbar handle
+ --os-handle-max-size: none;
+ // The axis-perpedicular size of the scrollbar handle (horizontal: height, vertical: width)
+ --os-handle-perpendicular-size: 100%;
+ // The :hover axis-perpedicular size of the scrollbar handle (horizontal: height, vertical: width)
+ --os-handle-perpendicular-size-hover: 100%;
+ // The :active axis-perpedicular size of the scrollbar handle (horizontal: height, vertical: width)
+ --os-handle-perpendicular-size-active: 100%;
+ // Increases the interactive area of the scrollbar handle.
+ --os-handle-interactive-area-offset: 0;
+ }
+ ```
+
+ You can alter the properties either for both scrollbars at once or per scrollbar axis:
+
+ ```scss
+ // horizontal and vertical scrollbar are 10px
+ .os-theme-custom {
+ --os-size: 10px;
+ }
+
+ // horizontal scrollbar is 10px
+ .os-theme-custom.os-scrollbar-horizontal {
+ --os-size: 10px;
+ }
+ // vertical scrollbar is 20px
+ .os-theme-custom.os-scrollbar-vertical {
+ --os-size: 20px;
+ }
+ ```
+
+ Since scrollbar styles are usually simple, this set of options should be enough to get your desired styling.
+ In case you need more freedom you can create your own styles by adding styling to the base class names described in the next section.
+
+ ### Scrollbars structure and CSS class names
+
+ The scrollbars HTML markup looks like:
+
+ ```html
+
+
+ ```
+
+ The class names are simplified, in a real application the `.os-scrollbar` element can have additional class names which modify the appearance (mostly visibility and alignment).
+
+ Below is a list of the most important class names you will encounter:
+
+ | CSS class name | description |
+| :--- | :--- |
+| `.os-scrollbar` | The root element of a scrollbar. |
+| `.os-scrollbar-rtl` | Indicates a `RTL` direction of the host element the scrollbar belongs to. |
+| `.os-scrollbar-horizontal` | The root element of a horizontal scrollbar. |
+| `.os-scrollbar-vertical` | The root element of a vertical scrollbar. |
+| `.os-scrollbar-handle-interactive` | Indicates that the handle inside the scrollbar is interactive (`scrollbars.dragScroll` is `true`). |
+| `.os-scrollbar-track-interactive` | Indicates that the track inside the scrollbar is interactive (`scrollbars.clickScroll` is `true`). |
+| `.os-scrollbar-track` | The track element. This is the track of the nested handle element. If `scrollbars.clickScroll` is `true` this is the element users can click to change the scroll offset. |
+| `.os-scrollbar-handle` | The handle element. If `scrollbars.dragScroll` is `true` this is the handle users can drag to change the scroll offset. |
+
+ If you create your own theme, please only use the classes listed above. All other classes are modifier classes used to change visibility, alignment and pointer-events of the scrollbars.
+
+
+
## Plugins
Everything thats considered not core functionality or old browser compatibility is exposed via a plugin. This is done because all unused plugins are treeshaken and thus won't end up in your final bundle. OverlayScrollbars comes with the following plugins:
diff --git a/packages/overlayscrollbars/CHANGELOG.md b/packages/overlayscrollbars/CHANGELOG.md
index 017e264..48d5b69 100644
--- a/packages/overlayscrollbars/CHANGELOG.md
+++ b/packages/overlayscrollbars/CHANGELOG.md
@@ -1,14 +1,18 @@
# Changelog
-## W.I.P
+## 2.1.0
### Bug Fixes
- Fix a bug where initial `RTL` direction wasn't detected properly.
-### Improvements
+### Features
- Introduce `CSS Custom Properties` to improve theming and styling of scrollbars.
+
+### Improvements
+
+- Improve pointer event handling on scrollbar handle and track.
- Improve the README documentation with a styling section.
## 2.0.3
diff --git a/packages/overlayscrollbars/README.md b/packages/overlayscrollbars/README.md
index ddd5141..cb98005 100644
--- a/packages/overlayscrollbars/README.md
+++ b/packages/overlayscrollbars/README.md
@@ -458,6 +458,132 @@ interface OverlayScrollbarsStatic {
}
```
+## Styling
+
+OverlayScrollbars comes with two themes called `os-theme-dark` and `os-theme-light`. You can use the `scrollbars.theme` option to change the theme.
+
+Custom themes can be done in multiple ways. The easiest and fastest is to use the predefined set of `CSS Custom Properties` aka. CSS variables. In case those aren't enought you can add custom class names or add custom styling to the existing class names.
+
+### Styling in depth
+
+
+
+ This is a in depth topic. Click here to read it.
+
+
+ ### CSS Custom properties
+
+ OverlayScrollbars provides a set of `CSS Custom Properties` which makes scrollbar styling easy and fast:
+ ```scss
+ .os-scrollbar {
+ // The size of the scrollbar
+ --os-size: 0;
+ // The axis-perpedicular padding of the scrollbar (horizontal: padding-y, vertical: padding-x)
+ --os-padding-perpendicular: 0;
+ // The axis padding of the scrollbar (horizontal: padding-x, vertical: padding-y)
+ --os-padding-axis: 0;
+ // The border radius of the scrollbar track
+ --os-track-border-radius: 0;
+ // The background of the scrollbar track
+ --os-track-bg: none;
+ // The :hover background of the scrollbar track
+ --os-track-bg-hover: none;
+ // The :active background of the scrollbar track
+ --os-track-bg-active: none;
+ // The border of the scrollbar track
+ --os-track-border: none;
+ // The :hover background of the scrollbar track
+ --os-track-border-hover: none;
+ // The :active background of the scrollbar track
+ --os-track-border-active: none;
+ // The border radius of the scrollbar handle
+ --os-handle-border-radius: 0;
+ // The background of the scrollbar handle
+ --os-handle-bg: none;
+ // The :hover background of the scrollbar handle
+ --os-handle-bg-hover: none;
+ // The :active background of the scrollbar handle
+ --os-handle-bg-active: none;
+ // The border of the scrollbar handle
+ --os-handle-border: none;
+ // The :hover border of the scrollbar handle
+ --os-handle-border-hover: none;
+ // The :active border of the scrollbar handle
+ --os-handle-border-active: none;
+ // The min size of the scrollbar handle
+ --os-handle-min-size: 33px;
+ // The max size of the scrollbar handle
+ --os-handle-max-size: none;
+ // The axis-perpedicular size of the scrollbar handle (horizontal: height, vertical: width)
+ --os-handle-perpendicular-size: 100%;
+ // The :hover axis-perpedicular size of the scrollbar handle (horizontal: height, vertical: width)
+ --os-handle-perpendicular-size-hover: 100%;
+ // The :active axis-perpedicular size of the scrollbar handle (horizontal: height, vertical: width)
+ --os-handle-perpendicular-size-active: 100%;
+ // Increases the interactive area of the scrollbar handle.
+ --os-handle-interactive-area-offset: 0;
+ }
+ ```
+
+ You can alter the properties either for both scrollbars at once or per scrollbar axis:
+
+ ```scss
+ // horizontal and vertical scrollbar are 10px
+ .os-theme-custom {
+ --os-size: 10px;
+ }
+
+ // horizontal scrollbar is 10px
+ .os-theme-custom.os-scrollbar-horizontal {
+ --os-size: 10px;
+ }
+ // vertical scrollbar is 20px
+ .os-theme-custom.os-scrollbar-vertical {
+ --os-size: 20px;
+ }
+ ```
+
+ Since scrollbar styles are usually simple, this set of options should be enough to get your desired styling.
+ In case you need more freedom you can create your own styles by adding styling to the base class names described in the next section.
+
+ ### Scrollbars structure and CSS class names
+
+ The scrollbars HTML markup looks like:
+
+ ```html
+
+
+ ```
+
+ The class names are simplified, in a real application the `.os-scrollbar` element can have additional class names which modify the appearance (mostly visibility and alignment).
+
+ Below is a list of the most important class names you will encounter:
+
+ | CSS class name | description |
+| :--- | :--- |
+| `.os-scrollbar` | The root element of a scrollbar. |
+| `.os-scrollbar-rtl` | Indicates a `RTL` direction of the host element the scrollbar belongs to. |
+| `.os-scrollbar-horizontal` | The root element of a horizontal scrollbar. |
+| `.os-scrollbar-vertical` | The root element of a vertical scrollbar. |
+| `.os-scrollbar-handle-interactive` | Indicates that the handle inside the scrollbar is interactive (`scrollbars.dragScroll` is `true`). |
+| `.os-scrollbar-track-interactive` | Indicates that the track inside the scrollbar is interactive (`scrollbars.clickScroll` is `true`). |
+| `.os-scrollbar-track` | The track element. This is the track of the nested handle element. If `scrollbars.clickScroll` is `true` this is the element users can click to change the scroll offset. |
+| `.os-scrollbar-handle` | The handle element. If `scrollbars.dragScroll` is `true` this is the handle users can drag to change the scroll offset. |
+
+ If you create your own theme, please only use the classes listed above. All other classes are modifier classes used to change visibility, alignment and pointer-events of the scrollbars.
+
+
+
## Plugins
Everything thats considered not core functionality or old browser compatibility is exposed via a plugin. This is done because all unused plugins are treeshaken and thus won't end up in your final bundle. OverlayScrollbars comes with the following plugins:
diff --git a/packages/overlayscrollbars/src/setups/scrollbarsSetup/scrollbarsSetup.events.ts b/packages/overlayscrollbars/src/setups/scrollbarsSetup/scrollbarsSetup.events.ts
index 01357d2..400d2d7 100644
--- a/packages/overlayscrollbars/src/setups/scrollbarsSetup/scrollbarsSetup.events.ts
+++ b/packages/overlayscrollbars/src/setups/scrollbarsSetup/scrollbarsSetup.events.ts
@@ -100,6 +100,7 @@ const createInteractiveScrollEvents = (
return on(_track, 'pointerdown', (pointerDownEvent: PointerEvent) => {
const isDragScroll =
closest(pointerDownEvent.target as Node, `.${classNameScrollbarHandle}`) === _handle;
+ const pointerCaptureElement = isDragScroll ? _handle : _track;
if (continuePointerDown(pointerDownEvent, options, isDragScroll)) {
const instantClickScroll = !isDragScroll && pointerDownEvent.shiftKey;
@@ -158,11 +159,11 @@ const createInteractiveScrollEvents = (
'pointerup',
(pointerUpEvent: PointerEvent) => {
runEachAndClear(offFns);
- _track.releasePointerCapture(pointerUpEvent.pointerId);
+ pointerCaptureElement.releasePointerCapture(pointerUpEvent.pointerId);
},
{ _once: true }
);
- _track.setPointerCapture(pointerDownEvent.pointerId);
+ pointerCaptureElement.setPointerCapture(pointerDownEvent.pointerId);
}
});
};
diff --git a/packages/overlayscrollbars/src/styles/themes.scss b/packages/overlayscrollbars/src/styles/themes.scss
index 55a76a0..b747d38 100644
--- a/packages/overlayscrollbars/src/styles/themes.scss
+++ b/packages/overlayscrollbars/src/styles/themes.scss
@@ -53,6 +53,16 @@
border-radius: var(--os-track-border-radius);
background: var(--os-track-bg);
transition: opacity 0.15s, background-color 0.15s, border-color 0.15s;
+
+ &:hover {
+ border: var(--os-track-border-hover);
+ background: var(--os-track-bg-hover);
+ }
+
+ &:active {
+ border: var(--os-track-border-active);
+ background: var(--os-track-bg-active);
+ }
}
.os-scrollbar-handle {
border: var(--os-handle-border);
@@ -68,25 +78,13 @@
bottom: 0;
display: block;
}
- }
- &:hover {
- .os-scrollbar-track {
- border: var(--os-track-border-hover);
- background: var(--os-track-bg-hover);
- }
- .os-scrollbar-handle {
+ &:hover {
border: var(--os-handle-border-hover);
background: var(--os-handle-bg-hover);
}
- }
- &:active {
- .os-scrollbar-track {
- border: var(--os-track-border-active);
- background: var(--os-track-bg-active);
- }
- .os-scrollbar-handle {
+ &:active {
border: var(--os-handle-border-active);
background: var(--os-handle-bg-active);
}
@@ -189,25 +187,25 @@ $os-theme-light-handle-bg-active: rgba(255, 255, 255, 0.66);
.os-theme-dark,
.os-theme-light {
- --os-size: $os-theme-dark-light-size;
- --os-padding-perpendicular: $os-theme-dark-light-padding-perpendicular;
- --os-padding-axis: $os-theme-dark-light-padding-axis;
- --os-track-border-radius: $os-theme-dark-light-track-border-radius;
- --os-handle-interactive-area-offset: $os-theme-dark-light-handle-interactive-area-offset;
- --os-handle-border-radius: $os-theme-dark-light-handle-border-radius;
+ --os-size: #{$os-theme-dark-light-size};
+ --os-padding-perpendicular: #{$os-theme-dark-light-padding-perpendicular};
+ --os-padding-axis: #{$os-theme-dark-light-padding-axis};
+ --os-track-border-radius: #{$os-theme-dark-light-track-border-radius};
+ --os-handle-interactive-area-offset: #{$os-theme-dark-light-handle-interactive-area-offset};
+ --os-handle-border-radius: #{$os-theme-dark-light-handle-border-radius};
}
.os-theme-dark {
- --os-handle-bg: $os-theme-dark-handle-bg;
- --os-handle-bg-hover: $os-theme-dark-handle-bg-hover;
- --os-handle-bg-active: $os-theme-dark-handle-bg-active;
+ --os-handle-bg: #{$os-theme-dark-handle-bg};
+ --os-handle-bg-hover: #{$os-theme-dark-handle-bg-hover};
+ --os-handle-bg-active: #{$os-theme-dark-handle-bg-active};
}
.os-theme-light {
- --os-handle-bg: $os-theme-light-handle-bg;
- --os-handle-bg-hover: $os-theme-light-handle-bg-hover;
- --os-handle-bg-active: $os-theme-light-handle-bg-active;
+ --os-handle-bg: #{$os-theme-light-handle-bg};
+ --os-handle-bg-hover: #{$os-theme-light-handle-bg-hover};
+ --os-handle-bg-active: #{$os-theme-light-handle-bg-active};
}
-// ie11 support for default light and dark theme
+// ie11 support for theme light and dark
.os-no-css-vars {
&.os-theme-dark,
&.os-theme-light {
diff --git a/website/src/components/index.mdx b/website/src/components/index.mdx
index 86b1082..55d0249 100644
--- a/website/src/components/index.mdx
+++ b/website/src/components/index.mdx
@@ -4,8 +4,8 @@ I created this plugin because I hate ugly and space consuming scrollbars. Simila
## Goals & Features
- - Simple, powerful and good documented API
- - High browser compatibility - Firefox, Chrome, Opera, Edge, Safari 10+ and IE 11
+ - Simple, powerful and well documented API
+ - High browser compatibility - Firefox 59+, Chrome 55+, Opera 42+, Edge 12+, Safari 10+ and IE 11
- Can be run on the server - SSR, SSG and ISR support
- Tested on various devices - Mobile, Desktop and Tablet
- Tested with various (and mixed) inputs - Mouse, touch and pen
@@ -13,11 +13,12 @@ I created this plugin because I hate ugly and space consuming scrollbars. Simila
- Automatic update detection - no polling
- Usage of latest browser features - best performance in new browsers
- Bidirectional - LTR or RTL direction support
+ - Supports usage on the `body` element
- Simple and effective scrollbar styling
- Highly customizable
- TypeScript support - fully written in TypeScript
- Dependency free - 100% self written to ensure small size and best functionality
- - High quality and fully typed Framework versions for [`react`](https://github.com/KingSora/OverlayScrollbars/tree/master/packages/overlayscrollbars-react), [`vue`](https://github.com/KingSora/OverlayScrollbars/tree/master/packages/overlayscrollbars-vue), [`angular`](https://github.com/KingSora/OverlayScrollbars/tree/master/packages/overlayscrollbars-ngx), [`svelte`](https://github.com/KingSora/OverlayScrollbars/tree/master/packages/overlayscrollbars-svelte) and [`solid`](https://github.com/KingSora/OverlayScrollbars/tree/master/packages/overlayscrollbars-solid).
+ - High quality and fully typed framework versions for [`react`](https://github.com/KingSora/OverlayScrollbars/tree/master/packages/overlayscrollbars-react), [`vue`](https://github.com/KingSora/OverlayScrollbars/tree/master/packages/overlayscrollbars-vue), [`angular`](https://github.com/KingSora/OverlayScrollbars/tree/master/packages/overlayscrollbars-ngx), [`svelte`](https://github.com/KingSora/OverlayScrollbars/tree/master/packages/overlayscrollbars-svelte) and [`solid`](https://github.com/KingSora/OverlayScrollbars/tree/master/packages/overlayscrollbars-solid).
## Choose your framework
@@ -322,6 +323,8 @@ Indicates whether you can drag the scrollbar handles for scrolling.
| :--- | :--- |
| `boolean` | `false` |
+> __Note__: This options requires the **ClickScrollPlugin** to work.
+
Indicates whether you can click on the scrollbar track for scrolling.
### `scrollbars.pointers`
@@ -437,6 +440,132 @@ interface OverlayScrollbarsStatic {
}
```
+## Styling
+
+OverlayScrollbars comes with two themes called `os-theme-dark` and `os-theme-light`. You can use the `scrollbars.theme` option to change the theme.
+
+Custom themes can be done in multiple ways. The easiest and fastest is to use the predefined set of `CSS Custom Properties` aka. CSS variables. In case those aren't enought you can add custom class names or add custom styling to the existing class names.
+
+### Styling in depth
+
+
+
+ This is a in depth topic. Click here to read it.
+
+
+ ### CSS Custom properties
+
+ OverlayScrollbars provides a set of `CSS Custom Properties` which makes scrollbar styling easy and fast:
+ ```scss
+ .os-scrollbar {
+ // The size of the scrollbar
+ --os-size: 0;
+ // The axis-perpedicular padding of the scrollbar (horizontal: padding-y, vertical: padding-x)
+ --os-padding-perpendicular: 0;
+ // The axis padding of the scrollbar (horizontal: padding-x, vertical: padding-y)
+ --os-padding-axis: 0;
+ // The border radius of the scrollbar track
+ --os-track-border-radius: 0;
+ // The background of the scrollbar track
+ --os-track-bg: none;
+ // The :hover background of the scrollbar track
+ --os-track-bg-hover: none;
+ // The :active background of the scrollbar track
+ --os-track-bg-active: none;
+ // The border of the scrollbar track
+ --os-track-border: none;
+ // The :hover background of the scrollbar track
+ --os-track-border-hover: none;
+ // The :active background of the scrollbar track
+ --os-track-border-active: none;
+ // The border radius of the scrollbar handle
+ --os-handle-border-radius: 0;
+ // The background of the scrollbar handle
+ --os-handle-bg: none;
+ // The :hover background of the scrollbar handle
+ --os-handle-bg-hover: none;
+ // The :active background of the scrollbar handle
+ --os-handle-bg-active: none;
+ // The border of the scrollbar handle
+ --os-handle-border: none;
+ // The :hover border of the scrollbar handle
+ --os-handle-border-hover: none;
+ // The :active border of the scrollbar handle
+ --os-handle-border-active: none;
+ // The min size of the scrollbar handle
+ --os-handle-min-size: 33px;
+ // The max size of the scrollbar handle
+ --os-handle-max-size: none;
+ // The axis-perpedicular size of the scrollbar handle (horizontal: height, vertical: width)
+ --os-handle-perpendicular-size: 100%;
+ // The :hover axis-perpedicular size of the scrollbar handle (horizontal: height, vertical: width)
+ --os-handle-perpendicular-size-hover: 100%;
+ // The :active axis-perpedicular size of the scrollbar handle (horizontal: height, vertical: width)
+ --os-handle-perpendicular-size-active: 100%;
+ // Increases the interactive area of the scrollbar handle.
+ --os-handle-interactive-area-offset: 0;
+ }
+ ```
+
+ You can alter the properties either for both scrollbars at once or per scrollbar axis:
+
+ ```scss
+ // horizontal and vertical scrollbar are 10px
+ .os-theme-custom {
+ --os-size: 10px;
+ }
+
+ // horizontal scrollbar is 10px
+ .os-theme-custom.os-scrollbar-horizontal {
+ --os-size: 10px;
+ }
+ // vertical scrollbar is 20px
+ .os-theme-custom.os-scrollbar-vertical {
+ --os-size: 20px;
+ }
+ ```
+
+ Since scrollbar styles are usually simple, this set of options should be enough to get your desired styling.
+ In case you need more freedom you can create your own styles by adding styling to the base class names described in the next section.
+
+ ### Scrollbars structure and CSS class names
+
+ The scrollbars HTML markup looks like:
+
+ ```html
+
+
+ ```
+
+ The class names are simplified, in a real application the `.os-scrollbar` element can have additional class names which modify the appearance (mostly visibility and alignment).
+
+ Below is a list of the most important class names you will encounter:
+
+ | CSS class name | description |
+| :--- | :--- |
+| `.os-scrollbar` | The root element of a scrollbar. |
+| `.os-scrollbar-rtl` | Indicates a `RTL` direction of the host element the scrollbar belongs to. |
+| `.os-scrollbar-horizontal` | The root element of a horizontal scrollbar. |
+| `.os-scrollbar-vertical` | The root element of a vertical scrollbar. |
+| `.os-scrollbar-handle-interactive` | Indicates that the handle inside the scrollbar is interactive (`scrollbars.dragScroll` is `true`). |
+| `.os-scrollbar-track-interactive` | Indicates that the track inside the scrollbar is interactive (`scrollbars.clickScroll` is `true`). |
+| `.os-scrollbar-track` | The track element. This is the track of the nested handle element. If `scrollbars.clickScroll` is `true` this is the element users can click to change the scroll offset. |
+| `.os-scrollbar-handle` | The handle element. If `scrollbars.dragScroll` is `true` this is the handle users can drag to change the scroll offset. |
+
+ If you create your own theme, please only use the classes listed above. All other classes are modifier classes used to change visibility, alignment and pointer-events of the scrollbars.
+
+
+
## Plugins
Everything thats considered not core functionality or old browser compatibility is exposed via a plugin. This is done because all unused plugins are treeshaken and thus won't end up in your final bundle. OverlayScrollbars comes with the following plugins: