Skip to main content

Snap

Manages carousel-like behavior. Supports

  • Tracks slide progress
  • Numerous callbacks for event handling
  • Snapping
  • Wheel interaction
  • Swipe/Drag events
  • Custom gaps with css units supported
  • Smooth transitions
  • and more...
note
  • Snap does not apply any styles to the container or slides, it only provides logic, which allows you building custom carousels.

Example​

Explore a basic example on CodePen:

Props​

Static Props​

Static properties are set during initialization and cannot be modified later.

container​

  • Type: HTMLElement
  • Default: none
  • HTML container element where listeners are attached.

eventsEmitter​

  • Type: HTMLElement | null
  • Default: null
  • HTML element used to emit events.

activeIndex​

  • Type: number
  • Default: 0
  • Default active index.

Mutable Props​

Mutable properties can be updated at runtime using .updateProps().

slides​

  • Type: (HTMLElement | SnapSlide)[] | false;
  • Default: false
  • Slides instances. If false, all container's children will be considered as slides.

direction​

  • Type: 'horizontal' | 'vertical'
  • Default: 'horizontal'
  • Sliding direction.
    See example

centered​

  • Type: boolean
  • Default: false
  • Centered slides.
    See example

loop​

  • Type: boolean
  • Default: false
  • Detects if need to loop the slides.
    See example

gap​

  • Type: number | string
  • Default: 0
  • The gap between slides. Supports css units like px, rem, vw, vh, svh.

lerp​

  • Type: number
  • Default: 0.2
  • Linear interpolation factor for smooth animation.
    See example

freemode​

  • Type: boolean
  • Default: false
  • Disables friction and snapping to the nearest slide.
    See example

stickOnResize​

  • Type: boolean
  • Default: true
  • Stick to the nearest slide on window resize.

friction​

  • Type: number
  • Default: 0.15
  • Friction that makes the slides tend to the nearest slide magnet. The value is a number between 0 and 1 which is multiplied by the lerp value. 0 disables friction.
    See example

edgeFriction​

  • Type: number
  • Default: 0.85
  • Maximum friction between the final slide and the maximum translation value. From 0 to 1. The higher value the more resistance is applied.

duration​

  • Type: number | ((distance: number) => number)
  • Default: 500
  • Slide animation duration.
    See example

easing​

  • Type: TEasingType
  • Default: EaseOutCubic
  • Easing type for smoother animation. Accepts standard easing types or an array of bezier values.
    See easing types for more information
    See example

slideSize​

  • Type: 'auto' | 'stretch' | number | string
  • Default: 'auto'
  • Default slide size. Supported values:
    • auto detects slide size depending on the element or container size.
    • stretch detects slide size as the container size.
    • number defines the slide size in pixels.
    • CSS units like px, rem, vw, vh, svh.
  • Note that this property does not change real slide sizes. It is used for virtual slides & custom logic.

swipe​

  • Type: boolean
  • Default: true
  • Enable or disable swipe events.

grabCursor​

  • Type: boolean
  • Default: false
  • User will see the "grab" cursor when hovering and "grabbing" when swiping.

swipeSpeed​

  • Type: number
  • Default: 1
  • Speed factor for swipe movements.
    See example

swipeAxis​

  • Type: 'x' | 'y' | 'auto'
  • Default: 'auto'
  • Swipe axis. If auto, the axis will be automatically detected depending on direction.

followSwipe​

  • Type: boolean
  • Default: false
  • If false, then slider will be animated only when you release the finger, it will not move while you hold your finger on it.

shortSwipes​

  • Type: boolean
  • Default: true
  • When true, swipes shorter than shortSwipeDuration can trigger slide change. Short swipes work only when followSwipe is true.

shortSwipesDuration​

  • Type: number
  • Default: 300
  • Short swipe maximum duration.

shortSwipesThreshold​

  • Type: number
  • Default: 30
  • Minimum distance in pixels to trigger slide change for short swipes.

swipeFriction​

  • Type: boolean
  • Default: false
  • Defines if friction is allowed when swiping. Doesn't work with short swipes or when followSwipe is false.
    See example

swipeLerp​

  • Type: number | false
  • Default: vevet.mobile ? 1 : 0.6
  • Linear interpolation factor for smooth progress updates during swipe move. false means that the main lerp option will be used.

swipeThreshold​

  • Type: number
  • Default: 5
  • Length in pixels that must be swiped to trigger swipe start.

swipeMinTime​

  • Type: number
  • Default: 0
  • Minimum time in milliseconds to trigger swipe move.

wheel​

  • Type: boolean
  • Default: false
  • Enable or disable mouse wheel control.
    See example

wheelSpeed​

  • Type: number
  • Default: 1
  • Speed factor for mouse wheel control.

wheelAxis​

  • Type: 'x' | 'y' | 'auto'
  • Default: 'auto'
  • Wheel axis. If auto, the axis will be automatically detected depending on direction.

followWheel​

  • Type: boolean
  • Default: true
  • If false, then slider will be animated only when you stop scrolling the wheel.

wheelThrottle​

  • Type: number | 'auto'
  • Default: auto
  • Throttle wheel events, value in milliseconds. Works only if followWheel is disabled.

stickOnWheelEnd​

  • Type: boolean
  • Default: true
  • Enable snapping on wheel stop.

Accessors​

note

All Module's accessors are available in this class.

activeIndex​

Type: number

Active slide index

activeSlide​

Type: SnapSlide

Active slide

axis​

Type: "x" | "y"

Get axis name depending on direction

container​

Type: HTMLElement

Get container

domSize​

Type: number

Container size depending on direction (width or height)

eventsEmitter​

Type: HTMLElement

Get events emitter

firstSlideSize​

Type: number

Get first slide size

isEmpty​

Type: boolean

Defines if there's nothing to animate

isTransitioning​

Type: boolean

If transition in progress

scrollableSlides​

Type: SnapSlide[]

Scrollable slides (which size is larger than the container)

slides​

Type: SnapSlide[]

All slides

track.canLoop​

Type: boolean

If can loop

track.current​

Type: number

Gets/sets the current track value.

track.isEnd​

Type: boolean

If the end has been reached

track.isInterpolated​

Type: boolean

Whether the track is interpolated

track.isSlideScrolling​

Type: boolean

Check if the active slide is larger than the container and is being scrolled

track.isStart​

Type: boolean

If the start has been reached

track.loopCount​

Type: number

Get loop count

track.loopedCurrent​

Type: number

Get looped current value

track.max​

Type: number

Get maximum track value

track.min​

Type: number

Get minimum track value

track.offset​

Type: number

Get track offset

track.progress​

Type: number

Get track progress. From 0 to 1 if not loop. From -Infinity to Infinity if loop

track.target​

Type: number

Gets/sets the target track value

Methods​

note

All Module's methods are available in this class.

cancelTransition​

Cancel sticky behavior

instance.cancelTransition();

next​

Go to next slide

instance.next({ duration: 500, skip: 1 });

prev​

Go to previous slide

instance.prev({ duration: 500, skip: 1 });

resize​

Request resize (handled with debounce timeout)

instance.resize(true);

stick​

Stick to the nearest magnet

instance.stick();

toCoord​

Go to a definite coordinate

instance.toCoord(1365, 250);

toSlide​

Go to a slide by index

instance.toSlide(1, { direction: 'next', duration: 500 });

track.clampTarget​

Clamp target value between min and max values

instance.track.clampTarget();

track.iterateTarget​

Iterate track target value

instance.track.iterateTarget(50);

track.lerp​

Interpolate the current track value

instance.track.lerp(0.1);

track.set​

Set current & target value instantly

instance.track.set(1350);

Callbacks​

note

All Module's callbacks are available in this class.

activeSlide​

Triggered on active slide change

const destruct = instance.on('activeSlide', (slide) => console.log(slide.index));

// Cancel the callback
destruct();

rafPause​

Triggered on requestAnimationFrame pause

const destruct = instance.on('rafPause', () => console.log('pause'));

// Cancel the callback
destruct();

rafPlay​

Triggered on requestAnimationFrame play

const destruct = instance.on('rafPlay', () => console.log('play'));

// Cancel the callback
destruct();

reflow​

Triggered on carousel calculation

const destruct = instance.on('reflow', () => console.log('reflow'));

// Cancel the callback
destruct();

resize​

Triggered on carousel resize

const destruct = instance.on('resize', () => console.log('resize'));

// Cancel the callback
destruct();

swipe​

Triggered on swipe move

const destruct = instance.on('swipe', (coord) => console.log(coord));

// Cancel the callback
destruct();

swipe​

Triggered on swipe move

const destruct = instance.on('swipe', (coord) => console.log(coord));

// Cancel the callback
destruct();

swipeEnd​

Triggered on swipe end

const destruct = instance.on('swipeEnd', (coord) => console.log(coord));

// Cancel the callback
destruct();

swipeStart​

Triggered on swipe start

const destruct = instance.on('swipeStart', (coord) => console.log(coord));

// Cancel the callback
destruct();

timelineEnd​

Triggered on timeline animation end

const destruct = instance.on('timelineEnd', () => console.log('end'));

// Cancel the callback
destruct();

timelineEnd​

Triggered on timeline animation end

const destruct = instance.on('timelineEnd', () => console.log('end'));

// Cancel the callback
destruct();

timelineStart​

Triggered on timeline animation start

const destruct = instance.on('timelineStart', () => console.log('start'));

// Cancel the callback
destruct();

timelineStart​

Triggered on timeline animation start

const destruct = instance.on('timelineStart', () => console.log('start'));

// Cancel the callback
destruct();

timelineUpdate​

Triggered on timeline animation progress update

const destruct = instance.on('timelineUpdate', ({ progress, eased }) => {
  console.log(progress, eased);
});

// Cancel the callback
destruct();

update​

Triggered on carousel coords update

const destruct = instance.on('update', () => console.log('update'));

// Cancel the callback
destruct();

wheel​

Triggered on wheel event

const destruct = instance.on('wheel', (evt) => console.log(evt));

// Cancel the callback
destruct();

wheelEnd​

Triggered on wheel events end

const destruct = instance.on('wheelEnd', () => console.log('end'));

// Cancel the callback
destruct();

wheelStart​

Triggered on wheel events start

const destruct = instance.on('wheelStart', () => console.log('start'));

// Cancel the callback
destruct();