Skip to content

Commit 701347d

Browse files
author
Graham Still
committed
Update documentation
1 parent eba65d4 commit 701347d

File tree

5 files changed

+186
-54
lines changed

5 files changed

+186
-54
lines changed

‎website/docs/examples.md

+39-20
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
---
2-
sidebar_position: 3
2+
sidebar_position: 4
33
---
4+
import Tabs from '@theme/Tabs';
5+
import TabItem from '@theme/TabItem';
46

57
# Examples
68

@@ -39,10 +41,11 @@ The scollbar colour utilities are inherited, so if you want to use the same colo
3941
```
4042

4143
## Variants
44+
Use the `scrollbar-hover:` and `scrollbar-thumb:` variants to apply utilties when the scrollbar's thumb is hovered or active, respectively. Note that only scrollbars that are being [styled using pseudoelements](/getting-started#preferred-strategy) will pay attention to these variants; standards-track scrollbars (like those used in FireFox exclusively and in Chrome/Edge by default) deal with hover and active states on their own.
4245

43-
`hover:` and `active:` variants will be honoured in most browsers, but be aware that Firefox applies its own hover and active styling instead.
44-
45-
All browsers are compatible with `dark:` variants.
46+
:::warning
47+
If you're using `tailwind-scrollbar`@v3, use the built-in `hover:` and `active:` variants instead of `scrollbar-hover:` and `scrollbar-thumb:`.
48+
:::
4649

4750
<div className="scrollbar-hover:scrollbar-thumb-sky-500 scrollbar-active:scrollbar-thumb-sky-400 h-32 scrollbar scrollbar-thumb-slate-700 scrollbar-track-slate-300 overflow-y-scroll">
4851
<div className="h-64 bg-slate-400"></div>
@@ -56,7 +59,7 @@ All browsers are compatible with `dark:` variants.
5659

5760
## Custom colours
5861

59-
The colour utilities can accept colours in any format Tailwind's native colour utilities like `bg-*` can, including [custom colours](https://tailwindcss.com/docs/customizing-colors#adding-additional-colors) and [arbitrary values](https://tailwindcss.com/docs/customizing-colors#arbitrary-values).
62+
The colour utilities can accept colours in any format Tailwind's native colour utilities like `bg-*` can, including [custom colours](https://tailwindcss.com/docs/colors#customizing-your-colors) and [arbitrary values](https://tailwindcss.com/docs/adding-custom-styles#using-arbitrary-values).
6063

6164
<div className="scrollbar-thumb-custom scrollbar-track-custom-light scrollbar-hover:scrollbar-thumb-[#059669] scrollbar-active:scrollbar-thumb-emerald-500/50 scrollbar h-32 overflow-y-scroll">
6265
<div className="h-64 bg-slate-400"></div>
@@ -68,21 +71,37 @@ The colour utilities can accept colours in any format Tailwind's native colour u
6871
</div>
6972
```
7073

71-
```javascript title="tailwind.config.js"
72-
module.exports = {
73-
// ...
74-
theme: {
75-
extend: {
76-
colors: {
77-
custom: {
78-
DEFAULT: '#10B981',
79-
light: '#D1FAE5',
74+
<Tabs groupId="config">
75+
<TabItem value="css" label="New CSS Config" default>
76+
```css
77+
@import 'tailwindcss';
78+
79+
/* ... */
80+
81+
@theme {
82+
--color-custom: #d1fae5;
83+
--color-custom-light: #10b981;
84+
}
85+
```
86+
</TabItem>
87+
<TabItem value="js" label="Legacy JavaScript Config">
88+
```javascript
89+
module.exports = {
90+
// ...
91+
theme: {
92+
extend: {
93+
colors: {
94+
custom: {
95+
DEFAULT: '#10b981',
96+
light: '#d1fae5',
97+
},
98+
},
8099
},
81100
},
82-
},
83-
},
84-
};
85-
```
101+
};
102+
```
103+
</TabItem>
104+
</Tabs>
86105

87106
## Corners
88107

@@ -100,7 +119,7 @@ When you have both a vertical and horizontal scrollbar, you'll end up with an em
100119

101120
## Rounded bars
102121

103-
*These utilities only work in `nocompatible` mode, and have no effect in Firefox. See [configuration](/getting-started#configuration).*
122+
*These utilities only work in `nocompatible` mode, and have no effect on standards-track scrollbars. See [configuration](/getting-started#configuration).*
104123

105124
The `scrollbar-*-rounded-*` family of utilities can be applied to the `thumb`, `track`, or `corner` components, and work in the same was as Tailwind's native `rounded-*` utilities. Custom values and arbitrary values are permitted.
106125

@@ -116,7 +135,7 @@ The `scrollbar-*-rounded-*` family of utilities can be applied to the `thumb`, `
116135

117136
## Custom sizes
118137

119-
*These utilities only work in `nocompatible` mode, and have no effect in Firefox. See [configuration](/getting-started#configuration).*
138+
*These utilities only work in `nocompatible` mode, and have no effect on standards-track scrollbars. See [configuration](/getting-started#configuration).*
120139

121140
The `scrollbar-w-*` and `scrollbar-h-*` utilities can be used to fine-tine the width and height of scrollbars. Note that these only have effects on vertical and horizontal scrollbars, respectively, and can only be used with the `scrollbar` utility (not `scrollbar-thin`).
122141

‎website/docs/getting-started.md

+110-28
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
---
2-
sidebar_position: 2
2+
sidebar_position: 3
33
---
4+
import Tabs from '@theme/Tabs';
5+
import TabItem from '@theme/TabItem';
46

57
# Getting Started
68

@@ -16,47 +18,127 @@ yarn add -D tailwind-scrollbar
1618
pnpm add -D tailwind-scrollbar
1719
```
1820

21+
:::warning
22+
The lastest version of `tailwind-scrollbar` (v4) is only compatible with `tailwindcss` v4. If you're using `tailwindcss` v3, you'll need to use `tailwind-scrollbar` v3.
23+
:::
24+
1925
2. Add it to the plugins array of your Tailwind config
2026

21-
```javascript
22-
module.exports = {
23-
// ...
24-
plugins: [
25-
// ...
26-
require('tailwind-scrollbar'),
27-
],
28-
};
29-
```
27+
<Tabs groupId="config">
28+
<TabItem value="css" label="New CSS Config" default>
29+
```css
30+
@import 'tailwindcss';
31+
32+
/* ... */
33+
34+
@plugin 'tailwind-scrollbar';
35+
```
36+
</TabItem>
37+
<TabItem value="js" label="Legacy JavaScript Config">
38+
```javascript
39+
module.exports = {
40+
// ...
41+
plugins: [
42+
// ...
43+
require('tailwind-scrollbar'),
44+
],
45+
};
46+
```
47+
</TabItem>
48+
</Tabs>
3049

3150
## Configuration
3251

3352
### `nocompatible`
3453

3554
By default, only utilities that can have expressions across browsers are available. In order to access additional utilities that may not exist in all browsers, like [rounding](/examples#rounded-bars) and [custom sizes](/examples#custom-sizes), you can add the `nocompatible` flag to the configuration. You may need to also set the [preferred strategy](#preferredstrategy) to `pseudoelements` for `nocompatible` utilities to take effect in newer browsers.
3655

37-
```javascript
38-
module.exports = {
39-
// ...
40-
plugins: [
41-
// ...
42-
require('tailwind-scrollbar')({ nocompatible: true }),
43-
],
44-
};
45-
```
56+
<Tabs groupId="config">
57+
<TabItem value="css" label="New CSS Config" default>
58+
```css
59+
@import 'tailwindcss';
60+
61+
/* ... */
62+
63+
@plugin 'tailwind-scrollbar' {
64+
nocompatible: true;
65+
}
66+
```
67+
</TabItem>
68+
<TabItem value="js" label="Legacy JavaScript Config">
69+
```javascript
70+
module.exports = {
71+
// ...
72+
plugins: [
73+
// ...
74+
require('tailwind-scrollbar')({ nocompatible: true }),
75+
],
76+
};
77+
```
78+
</TabItem>
79+
</Tabs>
4680

4781
### `preferredStrategy`
4882

4983
The default scrollbar strategy used by the plugin is to prefer the standards-track properties (`scrollbar-width` and `scrollbar-color`) and fall back to pseudoelements only when standards-track properties are not supported. Although this strategy is encouraged, it does have drawbacks: available features are limited compared to the pseudoelement strategy, and some browser/OS combinations ignore scrollbar properties entirely. If you'd prefer to default to the pseudoelement strategy instead, pass `preferredStrategy: 'pseudoelements'` to the plugin configuration. Note that since Firefox does not support pseudoelements at all, it will continue to use standards-track properties.
5084

51-
```javascript
52-
module.exports = {
53-
// ...
54-
plugins: [
55-
// ...
56-
require('tailwind-scrollbar')({ preferredStrategy: 'pseudoelements' }), // default: 'standard'
57-
],
58-
};
59-
```
85+
<Tabs groupId="config">
86+
<TabItem value="css" label="New CSS Config" default>
87+
```css
88+
@import 'tailwindcss';
89+
90+
/* ... */
91+
92+
@plugin 'tailwind-scrollbar' {
93+
preferredStrategy: 'pseudoelements';
94+
}
95+
```
96+
</TabItem>
97+
<TabItem value="js" label="Legacy JavaScript Config">
98+
```javascript
99+
module.exports = {
100+
// ...
101+
plugins: [
102+
// ...
103+
require('tailwind-scrollbar')({ preferredStrategy: 'pseudoelements' }), // default: 'standard'
104+
],
105+
};
106+
```
107+
</TabItem>
108+
</Tabs>
109+
110+
:::tip
111+
If you're using multiple configuration options, make sure you get the syntax right. It should look like this:
112+
113+
<Tabs groupId="config">
114+
<TabItem value="css" label="New CSS Config" default>
115+
```css
116+
@import 'tailwindcss';
117+
118+
/* ... */
119+
120+
@plugin 'tailwind-scrollbar' {
121+
nocompatible: true;
122+
preferredStrategy: 'pseudoelements';
123+
}
124+
```
125+
</TabItem>
126+
<TabItem value="js" label="Legacy JavaScript Config">
127+
```javascript
128+
module.exports = {
129+
// ...
130+
plugins: [
131+
// ...
132+
require('tailwind-scrollbar')({
133+
nocompatible: true,
134+
preferredStrategy: 'pseudoelements',
135+
}),
136+
],
137+
};
138+
```
139+
</TabItem>
140+
</Tabs>
141+
:::
60142

61143
## Usage
62144

‎website/docs/migrating.md

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
sidebar_position: 2
3+
---
4+
5+
# Migrating to v4
6+
7+
`tailwind-scrollbar@^4.0.0` supports Tailwindcss v4, but there are some **breaking changes** to be aware of.
8+
9+
### `hover:` and `active:`
10+
11+
In v3, hover and active variants could be applied with Tailwind's built-in `hover:` and `active:` (e.g. `hover:scrollbar-thumb-red-100`). In v4, this has different, arguably more predictable, semantics: an element with `hover:scrollbar-thumb-red-100` will cause its scrollbar's thumb to change colour when the **element** is hovered, not the scrollbar's thumb.
12+
13+
Let's be honest, though, that's probably not what you're after. To apply variants just to the scrollbar's thumb, use `scrollbar-hover:` and `scrollbar-active:`. If, for some reason, you're wanting to apply these variants to the track or corner elements, `scrollbar-track-hover:`, `scrollbar-track-active:`, `scrollbar-corner-hover:`, and `scrollbar-corner-active:` are there for you.
14+
15+
**In most cases, globally replacing `hover:scrollbar` with `scrollbar-hover:scrollbar` and `active:scrollbar` with `scrollbar-active:scrollbar` should be enough.**

‎website/docs/utilities.md

+18-5
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
---
2-
sidebar_position: 4
2+
sidebar_position: 5
33
---
44

5-
# Complete list of utilities
5+
# Complete list of utilities/variants
66

77
## Base utilities
88
These utilities initialize scrollbar styling. You always need one of them, even if you're using custom widths.
@@ -22,10 +22,8 @@ All of the asterisks can be replaced [with any tailwind colour](https://tailwind
2222
| <span className="whitespace-nowrap">`scrollbar-track-*`</span> | Sets the colour of the scrollbar track | |
2323
| <span className="whitespace-nowrap">`scrollbar-corner-*`</span> | Sets the colour of the scrollbar corner | The corner will only appear if you have both vertical and horizontal scrollbars. |
2424

25-
Additionally, `hover:` and `active:` [variants](https://tailwindcss.com/docs/hover-focus-and-other-states#hover-focus-and-active) may be used, but they will be ignored by Firefox since it defines these styles itself.
26-
2725
## Nocompatible utilities
28-
These styles are only available in [`nocompatible` mode](/getting-started#configuration). They won't have any effect in Firefox.
26+
These styles are only available in [`nocompatible` mode](/getting-started#configuration). They won't have any effect on standards-track scrollbars, such as those used by Firefox or by Chrome/Edge by default.
2927

3028
| Utility | Effect | Notes |
3129
|-------------|--------|-------|
@@ -35,3 +33,18 @@ These styles are only available in [`nocompatible` mode](/getting-started#config
3533
| <span className="whitespace-nowrap">`scrollbar-track-rounded-*`</span> | Rounds a scrollbar track's corners | See above, but for the track |
3634
| <span className="whitespace-nowrap">`scrollbar-corner-rounded-*`</span> | Rounds a scrollbar corner's corners | See above, but for the corner pseudoelement created when both horizontal and vertial scrollbars are present |
3735

36+
## Variants
37+
38+
:::warning
39+
These variants are not available in `tailwind-scrollbar`@v3. Use the built-in `hover:` and `active:` instead.
40+
:::
41+
42+
These variants don't have any effect on standards-track scrollbars, such as those used by Firefox or by Chrome/Edge by default. The responsibility of styling hover and active states is assumed by the browser in that scenario.
43+
44+
| Variant | Effect |
45+
| ------------------------- | -------------------------------------------------------- |
46+
| `scrollbar-hover:` | Applies a utility when the scrollbar's thumb is hovered |
47+
| `scrollbar-active:` | Applies a utility when the scrollbar's thumb is active |
48+
| `scrollbar-track-hover:` | Applies a utility when the scrollbar's track is hovered |
49+
| `scrollbar-track-active:` | Applies a utility when the scrollbar's track is active |
50+
| `scrollbar-corner-hover:` | Applies a utility when the scrollbar's corner is hovered |

‎website/src/css/custom.css

+4-1
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,6 @@
1010
nocompatible: true;
1111
preferredStrategy: "pseudoelements";
1212
}
13-
@plugin 'tailwindcss/plugin';
1413

1514
@variant dark (&:is([data-theme="dark"] *));
1615

@@ -54,3 +53,7 @@
5453
--ifm-color-primary-lightest: #bae6fd;
5554
--docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3);
5655
}
56+
57+
ol {
58+
list-style: decimal;
59+
}

0 commit comments

Comments
 (0)