To source

a-track

A scroll-container with slider utility functions.

Implemented with Slider and Drawer.

Track

A Track is a custom element that provides a interface for scrolling content. It can be used to create carousels, slideshows, and other scrolling elements. It provides functions to go to a specific child element, emits events on changes, and optimizes ux based on input device.

Example

<a-track snap class="flex w-full overflow-visible">
  <div class="flex-none w-full">
    <canvas width={720} height={480} class="w-full bg-slate-400 m-1" />
  </div>
  <div class="flex-none w-full">
    <canvas width={720} height={480} class="w-full bg-slate-400 m-1" />
  </div>
</a-track>

Attributes

Name Type Default value Description
align "start" | "center" "start"

Item alignment in the track. "start" (left/top) or "center"
current undefined | number undefined

The index of the current item.
loop boolean false

Whether the track should loop back to the start when reaching the end.
overflow "scroll" | "auto" | "ignore" "auto"

Change the overflow behavior.

  • "auto" - Only scrollable when necessary.
  • "scroll" - Always scrollable.
  • "ignore" - Ignore any overflow.
snap boolean false

Whether the track should snap to the closest child element.
vertical boolean false

Whether the track should scroll vertically, instead of horizontally.

Events

Name Description
format

Emitted when: slots changed, window load and resize or children size changes. Can be canceled.
change

Emitted when the current index changed.
scroll

Emitted when the position changed.
move

Emitted when the position is about to cahnge by a user action. Can be canceled.

Methods

Track.addTrait(trait: T)

src/Track.ts:821

Add a trait.

Track.elementItemIndex(ele: HTMLElement)

src/Track.ts:890

Get the index of the item that contains given element. Returns -1 if it is not in any item.

Track.findTrait(id: string)

src/Track.ts:831

Get a trait by id.

Track.getClosestItemPosition(offset: number)

src/Track.ts:868

Get the absolute position of the closest item to the current position.

Track.getItemAtPosition(pos: Vec2)

src/Track.ts:1297

Get the item at a specific position.

Track.getToItemPosition(index: number)

src/Track.ts:902

Get the position of the item to the given index, relative to the current item.

Track.moveBy(byItems: number, easing: Easing)

src/Track.ts:963

Move by given count of items.

Track.moveTo(index: number, easing: Easing)

src/Track.ts:977

Move to index of item.

Track.removeTrait(trait: Trait)

src/Track.ts:826

Remove a trait.

Track.setTarget(vec: undefined | Vec2 | number[], ease: Easing)

src/Track.ts:935

Set the target position to transition to.

Track.startAnimate()

src/Track.ts:981

Track.stopAnimate()

src/Track.ts:988

Trait

The Track implements a trait system, which can be used to add new behaviours to the track.

Custom traits can be added to the track by calling the Track.addTrait method.

Or the Track class can be extended to override add new behaviours entirely.

Example

import { type InputState, Track, type Trait } from "@sv/elements/track";

export class CustomTrack extends Track {
  public traits: Trait[] = [
    // satefies the "Trait" interface
    {
      id: "custom-trait",
      input(track: Track, inputState: InputState) {
        if (inputState.release.value) {
          // log track posiiton on pointer/touch release
          console.log(track.posiiton);
        }
      },
    },
  ];
}

customElements.define("custom-track", CustomTrack);

SnapTrait

The SnapTrait addes the snapping of items to the track.

Different example confugrations of tracks.

Free scroll

Snap scroll

Align center

Arrow key navigation

Vertical snap scroll

Dynamic children

When children change, and the last selected item does not exist anymore, it will recover to the closest available child.

Configure format behaviour:

track.addEventListener("format", e => {
  // prevent default behaviour (move to the closest available child)
  e.preventDefault();
  // instead move to the first child
  e.currentTarget?.moveTo(0);
});

Nested

Loop Snap