GUILD OF GLEKS UIv21.19.0

gog-scroll

Scroll

A drop-in replacement for a native overflow: auto region. Content keeps scrolling natively — wheel, touch, keyboard, focus-into-view all still work — only the browser's own scrollbar chrome is hidden and replaced with a themeable, draggable overlay thumb.

Overview

Import the component and give it a height (or width).

typescript
import { ScrollComponent } from '@guildofgleks/ui';

@Component({
  // ...
  imports: [ScrollComponent],
})

Basic usage — gog-scroll scrolls whatever does not fit the box its host is given, so the height is set on the element. Leave the host's display alone: it is a flex column, and that is what carries the height down to the viewport.

Row 1

Row 2

Row 3

Row 4

Row 5

Row 6

Row 7

Row 8

Row 9

Row 10

Row 11

Row 12

Row 13

Row 14

Row 15

Row 16

Row 17

Row 18

Row 19

Row 20

Row 21

Row 22

Row 23

Row 24

Row 25

Row 26

Row 27

Row 28

Row 29

Row 30

<!-- The region scrolls whatever does not fit the box its host is given: set a height on it. -->
<gog-scroll style="height: 200px" ariaLabel="Example list">
  @for (item of items; track item) {
    <p>{{ item }}</p>
  }
</gog-scroll>

Examples

Size and auto-hide

size="thin" shrinks the track and thumb. With autoHide on (the default) the thumb shows while the region is scrolled or the pointer moves over it, and fades hideDelay ms later; off, it stays. Hover, drag and the track's own hover are live.

Row 1

Row 2

Row 3

Row 4

Row 5

Row 6

Row 7

Row 8

Row 9

Row 10

Row 11

Row 12

Row 13

Row 14

Row 15

Row 16

Row 17

Row 18

Row 19

Row 20

Row 21

Row 22

Row 23

Row 24

Row 25

Row 26

Row 27

Row 28

Row 29

Row 30

size="normal", autoHide on

Row 1

Row 2

Row 3

Row 4

Row 5

Row 6

Row 7

Row 8

Row 9

Row 10

Row 11

Row 12

Row 13

Row 14

Row 15

Row 16

Row 17

Row 18

Row 19

Row 20

Row 21

Row 22

Row 23

Row 24

Row 25

Row 26

Row 27

Row 28

Row 29

Row 30

size="normal", autoHide off

Row 1

Row 2

Row 3

Row 4

Row 5

Row 6

Row 7

Row 8

Row 9

Row 10

Row 11

Row 12

Row 13

Row 14

Row 15

Row 16

Row 17

Row 18

Row 19

Row 20

Row 21

Row 22

Row 23

Row 24

Row 25

Row 26

Row 27

Row 28

Row 29

Row 30

size="thin", autoHide on

Row 1

Row 2

Row 3

Row 4

Row 5

Row 6

Row 7

Row 8

Row 9

Row 10

Row 11

Row 12

Row 13

Row 14

Row 15

Row 16

Row 17

Row 18

Row 19

Row 20

Row 21

Row 22

Row 23

Row 24

Row 25

Row 26

Row 27

Row 28

Row 29

Row 30

size="thin", autoHide off

@for (size of sizes; track size) {
  @for (autoHide of [true, false]; track autoHide) {
    <div>
      <gog-scroll
        style="height: 160px"
        [size]="size"
        [autoHide]="autoHide"
        ariaLabel="Example list"
      >
        @for (item of items; track item) {
          <p>{{ item }}</p>
        }
      </gog-scroll>
      <p>size="{{ size }}", autoHide {{ autoHide ? 'on' : 'off' }}</p>
    </div>
  }
}

Axis

vertical (the default), horizontal or both — which axes get a thumb. The other axis is not scrollable at all: vertical clips horizontal overflow rather than scrolling it natively.

Item 1

Item 2

Item 3

Item 4

Item 5

Item 6

Item 7

Item 8

Item 9

Item 10

Item 11

Item 12

Item 13

Item 14

Item 15

Item 16

Item 17

Item 18

Item 19

Item 20

axis="vertical" (default)

Item 1
Item 2
Item 3
Item 4
Item 5
Item 6
Item 7
Item 8
Item 9
Item 10
Item 11
Item 12
Item 13
Item 14
Item 15
Item 16
Item 17
Item 18
Item 19
Item 20

axis="horizontal"

Item 1 · Item 1Item 1 · Item 2Item 1 · Item 3Item 1 · Item 4Item 1 · Item 5Item 1 · Item 6Item 1 · Item 7Item 1 · Item 8
Item 2 · Item 1Item 2 · Item 2Item 2 · Item 3Item 2 · Item 4Item 2 · Item 5Item 2 · Item 6Item 2 · Item 7Item 2 · Item 8
Item 3 · Item 1Item 3 · Item 2Item 3 · Item 3Item 3 · Item 4Item 3 · Item 5Item 3 · Item 6Item 3 · Item 7Item 3 · Item 8
Item 4 · Item 1Item 4 · Item 2Item 4 · Item 3Item 4 · Item 4Item 4 · Item 5Item 4 · Item 6Item 4 · Item 7Item 4 · Item 8
Item 5 · Item 1Item 5 · Item 2Item 5 · Item 3Item 5 · Item 4Item 5 · Item 5Item 5 · Item 6Item 5 · Item 7Item 5 · Item 8
Item 6 · Item 1Item 6 · Item 2Item 6 · Item 3Item 6 · Item 4Item 6 · Item 5Item 6 · Item 6Item 6 · Item 7Item 6 · Item 8
Item 7 · Item 1Item 7 · Item 2Item 7 · Item 3Item 7 · Item 4Item 7 · Item 5Item 7 · Item 6Item 7 · Item 7Item 7 · Item 8
Item 8 · Item 1Item 8 · Item 2Item 8 · Item 3Item 8 · Item 4Item 8 · Item 5Item 8 · Item 6Item 8 · Item 7Item 8 · Item 8
Item 9 · Item 1Item 9 · Item 2Item 9 · Item 3Item 9 · Item 4Item 9 · Item 5Item 9 · Item 6Item 9 · Item 7Item 9 · Item 8
Item 10 · Item 1Item 10 · Item 2Item 10 · Item 3Item 10 · Item 4Item 10 · Item 5Item 10 · Item 6Item 10 · Item 7Item 10 · Item 8
Item 11 · Item 1Item 11 · Item 2Item 11 · Item 3Item 11 · Item 4Item 11 · Item 5Item 11 · Item 6Item 11 · Item 7Item 11 · Item 8
Item 12 · Item 1Item 12 · Item 2Item 12 · Item 3Item 12 · Item 4Item 12 · Item 5Item 12 · Item 6Item 12 · Item 7Item 12 · Item 8
Item 13 · Item 1Item 13 · Item 2Item 13 · Item 3Item 13 · Item 4Item 13 · Item 5Item 13 · Item 6Item 13 · Item 7Item 13 · Item 8
Item 14 · Item 1Item 14 · Item 2Item 14 · Item 3Item 14 · Item 4Item 14 · Item 5Item 14 · Item 6Item 14 · Item 7Item 14 · Item 8
Item 15 · Item 1Item 15 · Item 2Item 15 · Item 3Item 15 · Item 4Item 15 · Item 5Item 15 · Item 6Item 15 · Item 7Item 15 · Item 8
Item 16 · Item 1Item 16 · Item 2Item 16 · Item 3Item 16 · Item 4Item 16 · Item 5Item 16 · Item 6Item 16 · Item 7Item 16 · Item 8
Item 17 · Item 1Item 17 · Item 2Item 17 · Item 3Item 17 · Item 4Item 17 · Item 5Item 17 · Item 6Item 17 · Item 7Item 17 · Item 8
Item 18 · Item 1Item 18 · Item 2Item 18 · Item 3Item 18 · Item 4Item 18 · Item 5Item 18 · Item 6Item 18 · Item 7Item 18 · Item 8
Item 19 · Item 1Item 19 · Item 2Item 19 · Item 3Item 19 · Item 4Item 19 · Item 5Item 19 · Item 6Item 19 · Item 7Item 19 · Item 8
Item 20 · Item 1Item 20 · Item 2Item 20 · Item 3Item 20 · Item 4Item 20 · Item 5Item 20 · Item 6Item 20 · Item 7Item 20 · Item 8

axis="both"

<div>
  <gog-scroll style="height: 160px" axis="vertical" [autoHide]="false" ariaLabel="Vertical">
    @for (item of items; track item) {
      <p>{{ item }}</p>
    }
  </gog-scroll>
  <p>axis="vertical" (default)</p>
</div>
<div>
  <!-- No height: on the horizontal axis the row sizes itself. -->
  <gog-scroll axis="horizontal" [autoHide]="false" ariaLabel="Horizontal">
    <div style="display: flex; gap: 8px; padding: 8px">
      @for (item of items; track item) {
        <gog-chip [clickable]="false">{{ item }}</gog-chip>
      }
    </div>
  </gog-scroll>
  <p>axis="horizontal"</p>
</div>
<div>
  <gog-scroll style="height: 160px" axis="both" [autoHide]="false" ariaLabel="Both">
    <table>
      <tbody>
        @for (row of items; track row) {
          <tr>
            @for (column of items.slice(0, 8); track column) {
              <td style="white-space: nowrap">{{ row }} · {{ column }}</td>
            }
          </tr>
        }
      </tbody>
    </table>
  </gog-scroll>
  <p>axis="both"</p>
</div>

No track — showTrack

[showTrack]="false" removes the thumb and the track while the region still scrolls by wheel, touch, keyboard and script — for a viewport whose position is driven some other way, the way gog-tabs drives its header row. Settable app-wide via GOG_CONFIG.scroll.showTrack.

Row 1

Row 2

Row 3

Row 4

Row 5

Row 6

Row 7

Row 8

Row 9

Row 10

Row 11

Row 12

Row 13

Row 14

Row 15

Row 16

Row 17

Row 18

Row 19

Row 20

Row 21

Row 22

Row 23

Row 24

Row 25

Row 26

Row 27

Row 28

Row 29

Row 30

<!-- No thumb and no track; wheel, touch, keyboard and script still scroll it. -->
<gog-scroll style="height: 160px" [showTrack]="false" ariaLabel="Example list">
  @for (item of items; track item) {
    <p>{{ item }}</p>
  }
</gog-scroll>

Horizontal wheel

Hover the first row and turn the wheel: the page moves. A vertical wheel over a region with nothing to scroll vertically belongs to the browser, and this component draws its thumb over native scrolling rather than replacing it, so that is the default and always was. [horizontalWheel]="true" is the opt-in exception — the second row is the same markup with that one input.

What it does not do is the part worth reading. Scroll the second row to its right-hand end and keep turning: the page starts moving again. The translation only happens while there is room left in the direction of the turn, so a region can never swallow the wheel and leave the page feeling stuck — which would be a worse bug than the one this fixes. It also keeps out of the way of anything that already works: a trackpad's sideways swipe and Shift+wheel carry a horizontal delta the browser applies correctly, Ctrl+wheel is pinch-zoom, and a region that can still scroll vertically is left alone — so axis="both" keeps scrolling down while there is down to go.

Off by default, because it changes what an existing region does with a gesture it currently passes on. GOG_CONFIG.scroll.horizontalWheel turns it on app-wide.

off — a vertical wheel scrolls the page (the default)

Column 1
Column 2
Column 3
Column 4
Column 5
Column 6
Column 7
Column 8
Column 9
Column 10
Column 11
Column 12
Column 13
Column 14
Column 15
Column 16
Column 17
Column 18
Column 19
Column 20

horizontalWheel — the same turn scrolls the row

Column 1
Column 2
Column 3
Column 4
Column 5
Column 6
Column 7
Column 8
Column 9
Column 10
Column 11
Column 12
Column 13
Column 14
Column 15
Column 16
Column 17
Column 18
Column 19
Column 20
<!-- The same content on the same axis; only the input differs. Hover each and turn the wheel. -->
<p>off — a vertical wheel scrolls the page (the default)</p>
<gog-scroll axis="horizontal" [autoHide]="false" ariaLabel="Columns, wheel off">
  <div style="display: flex; gap: 8px; padding: 8px">
    @for (item of items; track item) {
      <gog-chip [clickable]="false">{{ item }}</gog-chip>
    }
  </div>
</gog-scroll>

<p>horizontalWheel — the same turn scrolls the row</p>
<gog-scroll axis="horizontal" [autoHide]="false" horizontalWheel ariaLabel="Columns, wheel on">
  <div style="display: flex; gap: 8px; padding: 8px">
    @for (item of items; track item) {
      <gog-chip [clickable]="false">{{ item }}</gog-chip>
    }
  </div>
</gog-scroll>

Overscroll

overscrollBehavior is the CSS property: contain keeps a scroll that reaches the region's end from moving the page behind it, which is what a dropdown or a side panel wants. Scroll each to its end and keep going.

Row 1

Row 2

Row 3

Row 4

Row 5

Row 6

Row 7

Row 8

Row 9

Row 10

Row 11

Row 12

Row 13

Row 14

Row 15

Row 16

Row 17

Row 18

Row 19

Row 20

Row 21

Row 22

Row 23

Row 24

Row 25

Row 26

Row 27

Row 28

Row 29

Row 30

overscrollBehavior="auto"

Row 1

Row 2

Row 3

Row 4

Row 5

Row 6

Row 7

Row 8

Row 9

Row 10

Row 11

Row 12

Row 13

Row 14

Row 15

Row 16

Row 17

Row 18

Row 19

Row 20

Row 21

Row 22

Row 23

Row 24

Row 25

Row 26

Row 27

Row 28

Row 29

Row 30

overscrollBehavior="contain"

@for (behavior of behaviors; track behavior) {
  <div>
    <gog-scroll style="height: 160px" [overscrollBehavior]="behavior" ariaLabel="Example list">
      @for (item of items; track item) {
        <p>{{ item }}</p>
      }
    </gog-scroll>
    <p>overscrollBehavior="{{ behavior }}"</p>
  </div>
}

Reach events

gogReachStart / gogReachEnd fire once per crossing, within reachThreshold pixels of the edge; gogScroll emits live metrics on every scroll and resize.

Row 1

Row 2

Row 3

Row 4

Row 5

Row 6

Row 7

Row 8

Row 9

Row 10

Row 11

Row 12

Row 13

Row 14

Row 15

Row 16

Row 17

Row 18

Row 19

Row 20

Row 21

Row 22

Row 23

Row 24

Row 25

Row 26

Row 27

Row 28

Row 29

Row 30

Scroll to the edges to see gogReachStart / gogReachEnd fire.

<gog-scroll
  style="height: 200px"
  ariaLabel="Example list"
  [reachThreshold]="8"
  (gogReachStart)="reachState.set('At the top')"
  (gogReachEnd)="reachState.set('At the bottom')"
  (gogScroll)="onScroll($event)"
>
  @for (item of items; track item) {
    <p>{{ item }}</p>
  }
</gog-scroll>

<p>
  {{ reachState() }}
  @if (lastMetrics(); as metrics) {
    — scrollTop: {{ metrics.scrollTop | number: '1.0-0' }}
  }
</p>

Scroll methods

Grab the instance with viewChild and call scrollToTop / scrollToBottom / scrollToLeft / scrollToRight / scrollTo directly.

Row 1

Row 2

Row 3

Row 4

Row 5

Row 6

Row 7

Row 8

Row 9

Row 10

Row 11

Row 12

Row 13

Row 14

Row 15

Row 16

Row 17

Row 18

Row 19

Row 20

Row 21

Row 22

Row 23

Row 24

Row 25

Row 26

Row 27

Row 28

Row 29

Row 30

<div>
  <gog-button size="sm" (gogClick)="scroller()?.scrollToTop()">To top</gog-button>
  <gog-button size="sm" (gogClick)="scroller()?.scrollToBottom()">To bottom</gog-button>
</div>
<!-- #scrollRegion, not #scroller: a template reference would shadow the viewChild signal. -->
<gog-scroll #scrollRegion style="height: 200px" ariaLabel="Example list">
  @for (item of items; track item) {
    <p>{{ item }}</p>
  }
</gog-scroll>

App-wide defaults — GOG_CONFIG

size, autoHide, hideDelay and overscrollBehavior default to undefined so they can fall through to an app-wide (or subtree-wide) default set once via provideGogConfig(...), instead of repeating the same inputs on every instance. An instance's own input, when set, always wins.

This example has no template — it is configuration, not markup.

Accessibility

Scrolling stays the browser's, so everything a native region does for assistive tech it still does; the thumb and track are empty pointer affordances on top.

  • Tab stop — while its content overflows, the viewport is a tab stop with role="region", per the WAI-ARIA scrollable-region pattern, so the arrow keys, Page Up / Page Down and Home / End scroll it. With nothing to scroll the stop, the role and the name go away, since a dead stop helps no one.
  • Name — ariaLabel names that region. A region that scrolls with no name logs one console.warn per page in dev mode 21.19.0, never in production — checked when the region appears, so a viewport that never overflows never warns. A gog-table names its own scroll through its ariaLabel.
  • Nested — set focusable to false inside a component that already owns focus, such as a listbox panel or a dialog body, so it adds no redundant stop. Focus moving into content still scrolls it into view either way.

API Reference

Inputs

NameTypeDefaultDescription
axis'vertical' | 'horizontal' | 'both''vertical'Which axes get an overlay thumb. Native scrolling on the other axis is unaffected.
size'normal' | 'thin' | undefinedundefinedUnset, falls back to GOG_CONFIG.scroll.size, then to 'normal'.
autoHideboolean | undefinedundefinedFades the thumb out after hideDelay ms of inactivity; false keeps it always visible. Unset, falls back to GOG_CONFIG.scroll.autoHide, then to true.
hideDelaynumber | undefinedundefinedUnset, falls back to GOG_CONFIG.scroll.hideDelay, then to 800.
reachThresholdnumber0Pixel distance from an edge that still counts as "reached" for gogReachStart/gogReachEnd.
focusablebooleantrueRenders the viewport as its own tab stop (tabindex="0", role="region") while its content overflows. Since 21.15.0 the stop, the role and ariaLabel follow the measured overflow, so a frame with nothing to scroll is not a stop, and they come back when the content grows; on the server, before any measurement, it is a stop. Turn off when nesting inside a component that already owns focus/keyboard handling.
ariaLabelstring''Names the viewport while it is a scrolling region (focusable, and its content overflows). A scrolling region with no name warns in dev mode (since 21.19.0); a gog-table passes its own ariaLabel here.
horizontalWheelboolean | undefinedundefinedTurns a vertical wheel into horizontal scrolling on a region that has nothing to scroll vertically. Only acts while there is room left in that direction — at the content’s end the event is left alone and the page takes it — and never touches a horizontal delta (trackpad, Shift+wheel) or a pinch-zoom. Unset, falls back to GOG_CONFIG.scroll.horizontalWheel, then to false.
showTrackboolean | undefinedundefinedWhether the overlay thumb and track render at all. Scrolling itself is unaffected either way — this is purely the visual affordance. Unset, falls back to GOG_CONFIG.scroll.showTrack, then to true.
overscrollBehavior'auto' | 'contain' | 'none' | undefinedundefinedWhat happens when a scroll gesture reaches this instance's edge. Unset, falls back to GOG_CONFIG.scroll.overscrollBehavior, then to 'auto' — chains to the next scrollable ancestor.

Outputs

NamePayloadDescription
gogScrollGogScrollMetricsEmits scrollTop/scrollLeft/scrollHeight/scrollWidth/clientHeight/clientWidth on every scroll/resize.
gogReachStartGogScrollDirectionFires once when that axis crosses back within reachThreshold of its start edge.
gogReachEndGogScrollDirectionFires once when that axis crosses within reachThreshold of its end edge. GogScrollDirection is 'vertical' | 'horizontal', exported since 21.15.0.

Methods

SignatureDescription
scrollTo(options: ScrollToOptions)Forwards to the viewport's native Element.scrollTo.
scrollToTop(behavior = 'smooth')Scrolls to the top.
scrollToBottom(behavior = 'smooth')Scrolls to the bottom.
scrollToLeft(behavior = 'smooth')Scrolls to the left edge.
scrollToRight(behavior = 'smooth')Scrolls to the right edge.

Global Configuration

Set any of these once with provideGogConfig() instead of repeating them on every instance — an instance's own input still wins when it sets one itself. See Global Configuration for the full reference.

  • GOG_CONFIG.scroll.size
  • GOG_CONFIG.scroll.autoHide
  • GOG_CONFIG.scroll.hideDelay
  • GOG_CONFIG.scroll.overscrollBehavior
  • GOG_CONFIG.scroll.showTrack
  • GOG_CONFIG.scroll.horizontalWheel — turns a vertical wheel into horizontal scrolling on a region with nothing to scroll vertically. Off by default, and it never takes a gesture the browser already handles — a horizontal delta, a pinch-zoom, or a turn at the content’s end.

Styling Tokens

Every CSS custom property the scrollbar overlay paints with. Override any of them — on a single instance, a subtree, or a theme — to restyle it. See the Theming guide for the full token-layering model, or the Theme Generator to tweak these live.

TokenDescription
--gog-scroll-track-bg / -track-radiusTrack background and corner radius.
--gog-scroll-thumb-bg / -thumb-hover-bg / -thumb-active-bgDraggable thumb color, per interaction state.
--gog-scroll-thumb-radius / -thumb-insetThumb shape and inset from the track edges.
--gog-scroll-corner-bgBackground of the corner square where two tracks meet.
--gog-scroll-track-startWhere the vertical track starts, 0px by default. Content that pins a header over the top of the viewport sets it to that header’s height, so the thumb never runs over the header; gog-table does this itself for its stickyHeader. New in 21.15.0.
--gog-scroll-fade-durationAuto-hide fade animation timing.
--gog-scroll-focus-ring / -focus-ring-widthKeyboard focus ring on the viewport.
--gog-scroll-{normal|thin}-track-width / -thumb-min-sizeTrack width and minimum thumb length, per size step.