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"
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

---

Show ↴ ↶

Track.addTrait(trait: T)

src/Track.ts:699

Add a trait.

Track.elementItemIndex(ele: HTMLElement)

src/Track.ts:768

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

Get a trait by id.

Track.getClosestItemPosition(offset: number)

src/Track.ts:746

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

Track.getItemAtPosition(pos: Vec2)

src/Track.ts:1167

Get the item at a specific position.

Track.getToItemPosition(index: number)

src/Track.ts:780

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

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

src/Track.ts:838

Move by given count of items.

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

src/Track.ts:850

Move to index of item.

Track.removeTrait(trait: Trait)

src/Track.ts:704

Remove a trait.

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

src/Track.ts:810

Set the target position to transition to.

Track.startAnimate()

src/Track.ts:854

Track.stopAnimate()

src/Track.ts:861

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 "@atrium-ui/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