--- title: "Scroll button" description: "A floating button that appears once the reader scrolls away from an edge and jumps back to the bottom or the top, of a scroll container or the whole page." url: "https://susonwaiba.github.io/htmx-ui/docs/components/scroll-button" section: "Components" --- # Scroll button A floating button that appears once the reader scrolls away from an edge and jumps back to the bottom or the top, of a scroll container or the whole page. ```html
  1. Event 1: build step finished12:01
  2. Event 2: build step finished12:02
  3. Event 3: build step finished12:03
  4. Event 4: build step finished12:04
  5. Event 5: build step finished12:05
  6. Event 6: build step finished12:06
  7. Event 7: build step finished12:07
  8. Event 8: build step finished12:08
  9. Event 9: build step finished12:09
  10. Event 10: build step finished12:10
  11. Event 11: build step finished12:11
  12. Event 12: build step finished12:12
  13. Event 13: build step finished12:13
  14. Event 14: build step finished12:14
  15. Event 15: build step finished12:15
  16. Event 16: build step finished12:16
  17. Event 17: build step finished12:17
  18. Event 18: build step finished12:18
  19. Event 19: build step finished12:19
  20. Event 20: build step finished12:20
  21. Event 21: build step finished12:21
  22. Event 22: build step finished12:22
  23. Event 23: build step finished12:23
  24. Event 24: build step finished12:24
  25. Event 25: build step finished12:25
  26. Event 26: build step finished12:26
  27. Event 27: build step finished12:27
  28. Event 28: build step finished12:28
  29. Event 29: build step finished12:29
  30. Event 30: build step finished12:30
  31. Event 31: build step finished12:31
  32. Event 32: build step finished12:32
  33. Event 33: build step finished12:33
  34. Event 34: build step finished12:34
  35. Event 35: build step finished12:35
  36. Event 36: build step finished12:36
  37. Event 37: build step finished12:37
  38. Event 38: build step finished12:38
  39. Event 39: build step finished12:39
  40. Event 40: build step finished12:40
``` ## Markup - The button is an ordinary icon [`.btn`](https://susonwaiba.github.io/htmx-ui/docs/components/button) plus `.scroll-button`. Give it `type="button"` and an `aria-label` such as "Scroll to bottom". - `data-scroll-button` adds the behaviour. Its value is the edge it jumps to: `bottom` (the default) or `top`. - While its scroll target is near that edge the button is hidden: `data-state="hidden"` fades and shrinks it, and `inert` takes it out of the tab order and the accessibility tree. Once the reader scrolls away it turns `data-state="visible"`. It stays in the DOM throughout. - It follows the content too: when messages are appended or grow, the button appears without a scroll event, so a chat's "jump to bottom" shows up as replies stream in. ## In a scroll container Lay the button over the box it scrolls: wrap both in a `relative` element, mark the box `data-scroll-container` and add `.scroll-button-float`, which centres the button at the bottom of the wrapper (at the top for a `top` button). Give the box `tabindex="0"` so keyboard users can scroll it; when the button hides under the focus, focus moves back to the box. ```html

Can you summarise the release notes?

Sure: the release adds a loader, a scroll button and a faster build, and fixes three bugs in the docs search.

Can you summarise the release notes?

Sure: the release adds a loader, a scroll button and a faster build, and fixes three bugs in the docs search.

Can you summarise the release notes?

Sure: the release adds a loader, a scroll button and a faster build, and fixes three bugs in the docs search.

Can you summarise the release notes?

Sure: the release adds a loader, a scroll button and a faster build, and fixes three bugs in the docs search.

Can you summarise the release notes?

Sure: the release adds a loader, a scroll button and a faster build, and fixes three bugs in the docs search.

Can you summarise the release notes?

Sure: the release adds a loader, a scroll button and a faster build, and fixes three bugs in the docs search.

``` The button finds its target in this order: `data-scroll-target`; the closest `[data-scroll-container]` around it; a `[data-scroll-container]` beside it; the nearest ancestor with `overflow-y: auto` or `scroll`; otherwise the page. Point it anywhere with a selector: ```html
…
``` ## Back to top of the page Without a container around it, the button scrolls the page. `.scroll-button-fixed` pins it to the bottom-right corner of the viewport (bottom-left in right-to-left text). This page has one: scroll down and it appears in the corner. ```html ``` ## Options - `data-scroll-button="bottom" | "top"`: the edge to jump to (default `bottom`). - `data-scroll-target="#selector"`: the element to scroll, when it isn't found from the markup. - `data-scroll-threshold="200"`: how far from the edge, in pixels, the reader must scroll before the button shows (default 200). - `data-scroll-behavior="smooth" | "instant"`: how it scrolls (default `smooth`; always instant when the reader prefers reduced motion). A text button works as well as an icon one: anything with `.scroll-button` fades in and out. ```html

Line 1 of the build output

Line 2 of the build output

Line 3 of the build output

Line 4 of the build output

Line 5 of the build output

Line 6 of the build output

Line 7 of the build output

Line 8 of the build output

Line 9 of the build output

Line 10 of the build output

Line 11 of the build output

Line 12 of the build output

Line 13 of the build output

Line 14 of the build output

Line 15 of the build output

Line 16 of the build output

Line 17 of the build output

Line 18 of the build output

Line 19 of the build output

Line 20 of the build output

Line 21 of the build output

Line 22 of the build output

Line 23 of the build output

Line 24 of the build output

``` ## JavaScript `initScrollButton(root)` runs with the other components, on load and on content htmx inserts. The helpers it uses are exported from its module too, for a "scroll to bottom" after your own updates: ```ts import { distanceFromEdge, scrollToEdge } from "htmx-ui"; const log = document.querySelector("#log")!; // Keep following new lines, unless the reader has scrolled up to read. const following = distanceFromEdge(log, "bottom") < 40; log.insertAdjacentHTML("beforeend", "

New line

"); if (following) scrollToEdge(log, "bottom", "instant"); scrollToEdge(null, "top"); // null is the page: smooth, or instant under reduced motion ``` ## Reference | Class | Description | | --- | --- | | `.scroll-button` | Fades and shrinks out while data-state="hidden", back in when visible. | | `.scroll-button-float` | Absolutely centred at the bottom of the nearest positioned ancestor (top for a top button). | | `.scroll-button-fixed` | Fixed to the viewport's bottom-right corner. | | `[data-scroll-button="bottom" \| "top"]` | Behaviour: shows away from that edge, scrolls to it on click. | | `[data-scroll-container]` | Marks the element a nearby scroll button scrolls. | | `[data-scroll-target]` | A selector for the element to scroll. | | `[data-scroll-threshold]` | Distance from the edge, in px, before the button shows (200). | | `[data-scroll-behavior]` | smooth (default) or instant. | | `[data-state="visible" \| "hidden"]` | Set by the behaviour; hidden is also inert. | | Function | Description | | --- | --- | | `initScrollButton(root = document)` | Initialises every [data-scroll-button] under root (idempotent). | | `scrollToEdge(target, edge = "bottom", behavior?)` | Scrolls an element, or the page for null, to its top or bottom. | | `distanceFromEdge(target, edge)` | How far, in px, the element (or the page) is from that edge. | | `scrollTargetOf(button)` | The element a scroll button scrolls, or null for the page. |