CardStack

A small JavaScript utility to stack cards with random rotation and simple navigation.

Installation

npm install @fabien-labs/card-stack

Basic Usage

HTML:

<!-- This container can be styled -->
<div class="cardstack-wrapper">
  <!-- This container must not be styled, as this may cause layout issues -->
  <div id="cardstack">
    <div>Card 1</div>
    <div>Card 2</div>
    <div>Card 3</div>
  </div>
</div>

JavaScript / TypeScript:

import CardStack from '@fabien-labs/card-stack';

const stack = new CardStack('#cardstack', {
  intervalMs: 500,
  rotationMinMax: [-10, 10],
});

stack.setup();

API

Constructor

new CardStack(container, options?)

• container
  HTMLElement or CSS selector string

• options
  Optional configuration object

Methods

• setup()
  Initializes the stack.

• destroy()
  Stops everything and removes all effects added by CardStack.

• next()
  Go to next card.

• previous()
  Go to previous card.

• goTo(index)
  Go to a specific card (1-based index).

• start()
  Start automatic card switching.

• stop()
  Stop automatic card switching.

• show()
  Show the stack.

• hide()
  Hide the stack.

• getCurrentIndex()
  Returns the active card index.

• getTotalCards()
  Returns the total number of cards.

Options

rotationMinMax

rotationMinMax?: [number, number]

Default: [-10, 10]

Defines the minimum and maximum rotation (in degrees).

intervalMs

intervalMs?: number

Default: 500

Time in milliseconds between automatic card changes when start() is used.

randomSeed

randomSeed?: string

Default: ''

If set, rotations become deterministic.

changeRotationOnChange

changeRotationOnChange?: boolean

Default: false

If enabled, the active card receives a new rotation when it becomes active.

Notes

• The outer wrapper defines size and layout.
• The inner container is controlled by CardStack.
• No additional setup is required.

Browser Support

• Modern browsers
• Requires ResizeObserver

License

MIT