a-track

Lit

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"
loop	boolean	false	Whether the track should loop back to the start when reaching the end.
overflowscroll	boolean	false	Only scroll when items are overflown. Like "overflow: auto".
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

---

Show ↴ ↶

Track.addTrait(trait: T)

src/Track.ts:588

Add a trait.

Track.elementItemIndex(ele: HTMLElement)

src/Track.ts:691

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:598

Get a trait by id.

Track.getClosestItemPosition(offset: number)

src/Track.ts:378

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

Track.getItemAtPosition(pos: Vec2)

src/Track.ts:1125

Get the item at a specific position.

Track.getToItemPosition(index: number)

src/Track.ts:703

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

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

src/Track.ts:771

Move by given count of items.

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

src/Track.ts:783

Move to index of item.

Track.removeTrait(trait: Trait)

src/Track.ts:593

Remove a trait.

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

src/Track.ts:743

Set the target position to transition to.

Track.startAnimate()

src/Track.ts:787

Track.stopAnimate()

src/Track.ts:795

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, PointerTrait, Track, type Trait } from "@sv/elements/track";

export class CustomTrack extends Track {
  public traits: Trait[] = [
    new PointerTrait(),
    // 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);

PointerTrait

The PointerTrait addes the ability to move the track with the mouse or touch inputs by dragging.

Example

---

new PointerTrait({
  borderBounce?: number;
  borderResistance?: number;
})

SnapTrait

The SnapTrait addes the snapping of items to the track.

Different example confugrations of tracks.

Free scroll

Snap scroll

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