Scrollable

Intro

Scrollable does three things:

1. It adds an overflow:auto property to the container.
2. It enables CSS Scroll Snap
3. It prevents outlines from being cut off (optional enhancement).

Basic Usage

Horizontal Scrollbars

You can create a horizontal scrollable component with Scrollable-horizontal. This uses Horizontal under the hood.

<div class="Scrollable-horizontal">
  ...
</div>

Vertical Scrollbars

You can create a vertical scrollable component with Scrollable-vertical. For Vertical scrollbars, you would need a height or max-height declaration to determine the size of the container.

<div class="Scrollable-vertical max-h-60">
  ...
</div>

CSS Scroll Snap

CSS Scroll Snap is enabled in Scrollable (both horizontal and vertical) by default. To alter CSS Scroll Snap behaviour and positions, you need to change --snap-type, --snap-align or --scroll-margin.

Snap Type

--snap-type determines the strictness of the snap points if there is one.

Possible values are:

• none: Disables CSS Scroll Snap
• proximity: Enforces snap points loosely. (Default value).
• mandatory: Enforces snap points strictly

<div class="Scrollable-horizontal [--snap-type:mandatory]">
  ...
</div>

Snap Align

--snap-align determines where the snap point is. Possible values are: start (default), center, and end.

<div class="Scrollable-horizontal [--snap-align:center]">
  ...
</div>

Scroll Margin

--scroll-margin determines the amount of space between the edge of the container and the snap point. The default value is 1rem.

<div class="Scrollable-horizontal [--snap-align:center]">
  ...
</div>

Disabling CSS Scroll Snap

To disable CSS Scroll Snap, you can use Scrollable-noSnap or set --snap-type to none

<div class="Scrollable-horizontal Scrollable-noSnap">
  ...
</div>

Prefer Horizontal Scroll

The big problem for content with horizontal scrollbars is: most people don’t know they can scroll horizontally with the mouse.

We’ve created a ScrollableHorizontal script that combats this problem by converting vertical scrolls to horizontal scrolls with finese and taste. (As much as possible, at least)

Here’s what it does in a nutshell:

• It hijacks vertical mousewheel scrolls only when needed
• When needed means it hijacks only when these conditions are met:
  1. There is horizontal overflow
  2. The user is mousing over the Scrollable element
  3. The user is scrolling vertically
  4. The user has not scrolled to the end (left or right, depending on the scroll direction)
• The full vertical scroll amount is transferred to horizontal scroll to retain expected scrolling behaviour.
• Once the user has scrolled to the end, it releases the hijack and allows users to scroll vertically again.
• It does not hijack trackpad scrolls because users can scroll horizontally with trackpads

Using the script

To use the script, you need to import and run ScrollableHorizontal from the layouts library.

import { ScrollableHorizontal } from '@splendidlabz/layouts/scripts'
ScrollableHorizontal()

Next, add the Scrollable-prefersHorizontalScroll class to your Scrollable-horizontal element.

<div class="Scrollable-horizontal Scrollable-preferHorizontalScroll">
  ...
</div>

Usage with CSS Scroll Snap

ScrollableHorizontal disables CSS Scroll Snap when scrolling in order for a scroll to work as you would expect. It enables CSS Scroll Snap again after scrolling.

You can adjust this delay between when a user scrolls and when CSS Scroll Snap is enabled again with --scrollSnapDelay(in milliseconds).

<div class="
  Scrollable-horizontal
  Scrollable-preferHorizontalScroll
  [--scrollSnapDelay:2000]
">
  ...
</div>

Async containers

ScrollableHorizontal does not scan for elements that were created after the script has run.

If you add a Scrollable layout afterward and you want to use Scrollable-preferHorizontalScroll, make sure you run the ScrollableHorizontal script again when the component is loaded.

Styling scrollbars

The best way to style scrollbars is to use variables provided by our Scrollbar component.

* {
  --scrollbar-width: thin;
  --scrollbar-size: 12px;
  --scrollbar-thumb-color: pink;
  --scrollbar-track-color: darkpink;
}

Preserving outlines

When Scrollable components have an overflow, the container behaves somewhat like overflow:hidden where any outlines — which are used for focus states in Splendid Labz — will be cut off.

To prevent outlines from being cut off, you can use Scrollable-preserveOutlines. This adds negative margins and positive paddings to expand the scrollable container — just enough to show the outlines.

Here’s an example for you to see this at work.

<div class="Scrollable-horizontal">
  <button>One</button>
  <button>Two</button>
  <button>Three</button>
  ...
</div>

<div class="Scrollable-horizontal Scrollable-preserveOutlines">
  <button>One</button>
  <button>Two</button>
  <button>Three</button>
  ...
</div>

Here’s the CSS for Scrollable.

[class*='Scrollable'] {
  display: flex;
  gap: var(--gap, 1rem);

  > :where(*) {
    flex-grow: 0;
    flex-shrink: 0;
    scroll-snap-align: var(--snap-align, start);
    scroll-margin: var(--scroll-margin, 1rem);
  }
}

.Scrollable-horizontal {
  overflow: auto hidden;
  flex-direction: row;
  max-width: 100%;
  scroll-snap-type: x var(--snap-type, proximity);
}

.Scrollable-vertical {
  overflow: hidden auto;
  flex-direction: column;
  scroll-snap-type: y var(--snap-type, proximity);
}

.Scrollable-noSnap {
  --snap-type: none;
}

.Scrollable-preserveOutlines {
  box-sizing: content-box;
  margin: calc(var(--outline-width) * -1);
  padding: calc(var(--outline-width));
}

Scrollable

Modifiers

CSS Variables

Scrollable Horizontal Script

CSS Variables