#Slider API

#<SliderProvider>

This component provides a new slider context to any section of your app. It has no required props and renders nothing in the DOM. This is where the slider settings are defined.

import React from 'react';
import { SliderProvider } from '@faceless-ui/slider';

export const MyComponent = () => {
  return (
    <SliderProvider
      slidesToShow={3}
    >
      ...
    </SliderProvider>
  )
}

#<SliderProvider> Props

slidesToShow
  :  number
  |  optional

The number of slides within the track. This effects the width of each slide.

breakpoints
  :  object
  |  optional

Makes your slider responsive by overriding your slider settings for any CSS media queries.

slideOnSelect
  :  boolean
  |  optional

When true, navigates the slider directly to any slide that is clicked.

scrollOffset
  :  number
  |  optional

Adjusts the scroll target when navigating slides. Useful when slides need to maintain alignment with other elements on the page. Defaults to 0.

onSlide(index: number)
  :  method
  |  optional

A callback fired on every slide change. Returns the current slide index.

scrollable
  :  boolean
  |  optional

Enables both wheel and drag-based events to scroll the track. Defaults to true. If desired, you can disable dragScroll independently.

dragScroll
  :  boolean
  |  optional

Enables drag-based events to scroll the track. Automatically enabled when scrollable scrollable is true.

scrollSnap
  :  boolean
  |  optional

Enables native CSS Scroll Snap. Defaults to true.

autoPlay
  :  boolean
  |  optional

Whether to autoplay on load. Defaults to false.

autoplaySpeed
  :  number
  |  optional

The speed of the autoplay. Only applicable when autoplay is true. Defaults to 2000.

marquee
  :  boolean
  |  optional

Whether to marquee the slider which scrolls slowly through the track as opposed to sliding one-by-one. autoPlay must not be enabled.

marqueeSpeed
  :  number
  |  optional

The speed of the marquee. Only applicable when marquee is true. Defaults to 50.

pauseOnHover
  :  boolean
  |  optional

Only applicable when autoPlay is true. Defaults to true.

pause
  :  boolean
  |  optional

Stops and startsautoPlay. Set to undefined to return control back to the slider.

alignLastSlide
  :  string or number
  |  optional

Renders an invisible div at the end of your <SliderTrack> used to align the last slide of your slider to various points along your track. Accepts a CSS value or number, with negative values beginning from track-right (i.e. 40, -25px, etc). Set to trackLeft to align to the left edge of your last slide to the left edge of your slider track. Set to offsetLeft to include your scrollOffset.

id
  :  string
  |  optional

A unique ID used to match ARIA attributes between the slider components. Defaults to a random string from the useId hook. See accessibility for full details.

useFreeScroll [DEPRECATED]
  :  boolean
  |  optional

This prop will be deprecated in the next major release. Use scrollable instead.

#<SliderProvider> Context

currentSlideIndex
  :  number

The index of the current slide.

sliderTrackRef
  :  object

A reference to the <SliderTrack>.

goToNextSlide()
  :  method

Navigates to the next slide. If on the last slide, navigates to the first.

goToPrevSlide()
  :  method

Navigates to the previous slide. If on the first slide, navigates to the last.

goToSlideIndex(index: string)
  :  method

Navigates to the given slide index.

slides
  :  array

An array of every slide in the slider.

isPaused
  :  boolean

Returns whether the slider is currently paused. One applicable when pauseOnHover is true.

scrollRatio
  :  number

The current scroll progress of the slider.

slideWidth
  :  string

The width of each slide in pixels, based on slidesToShow.

...settings

All settings are spread into the context.

#<SliderTrack>

This will add a scrollable element onto the page which overflows its content as necessary. Acts as the root of each slide's intersection observer.

import React from 'react';
import { SliderTrack } from '@faceless-ui/slider';

export const MyComponent = () => {
  return (
    <SliderTrack>
      ...
    </SliderTrack>
  )
}

#<SliderTrack> Props

htmlElement
  :  string
  |  optional

Customize the HTML element that is rendered in the DOM. Defaults to div.

...rest
  :  object
  |  optional

All other props are spread onto the DOM element as HTML attributes.

#<Slide>

Each slide is a wrapper around the Intersection Observer API, and syncs its isIntersecting status to the provider.

import React from 'react';
import { Slide } from '@faceless-ui/slider';

export const MyComponent = () => {
  return (
    <SliderTrack>
      <Slide index={0}>
        ...
      </Slide>
      <Slide index={1}>
        ...
      </Slide>
    </SliderTrack>
  )
}

#<Slide> Props

index*  |  required

The index of the slide.

htmlElement
  :  string
  |  optional

Customize the HTML element that is rendered in the DOM. Defaults to div.

...rest
  :  object
  |  optional

All other props are spread onto the DOM element as HTML attributes.

#<SliderButton>

The slider button is a simple wrapper around the useSlider hook, used to quickly and easily navigate to any slide in the slider.

import React from 'react';
import { SliderButton } from '@faceless-ui/slider';

export const MyComponent = () => {
  return (
    <SliderButton direction="next">
      ...
    </SliderButton>
  )
}

#<SliderButton> Props

direction
  :  string
  |  optional

Set to previous or next to navigate to the slider to either the previous or next slide.

index
  :  number
  |  optional

Navigates the slider to the given index.

htmlElement
  :  string
  |  optional

Customize the HTML element that is rendered in the DOM. Defaults to button.

...rest
  :  object
  |  optional

All other props are spread onto the DOM element as HTML attributes.

#<SliderProgress>

An alternative to the native scrollbar. It can be placed anywhere in your slider DOM.

import React from 'react';
import { SliderProgress } from '@faceless-ui/slider';

export const MyComponent = () => {
  return (
    <SliderProvider>
      <SliderProgress />
    </SliderProvider>
  )
}

#<SliderProgress> Props

htmlElement
  :  string
  |  optional

Customize the HTML element that is rendered in the DOM. Defaults to div.

...rest
  :  object
  |  optional

All other props are spread onto the DOM element as HTML attributes.

indicator
  :  object
  |  optional

Allows you to customize the indicator component.

#<DotNav>

A dot-based navigation component used to control your slider and/or indicate its current position.

import React from 'react';
import { DotNav } from '@faceless-ui/slider';

export const MyComponent = () => {
  return (
    <SliderProvider>
      <DotNav
        className="dot"
        dotClassName="dot"
        activeDotClassName="dotIsActive"
      />
    </SliderProvider>
  )
}

#<DotNav> Props

dotClassName
  :  string
  |  optional

A class name to apply to each dot. This could also be achieve using dotProps.

activeDotClassName
  :  string
  |  optional

A class name to apply to active dots.

dotProps
  :  object
  |  optional

Arbitrary rops to spread onto each dot button.

htmlElement
  :  string
  |  optional

Customize the HTML element that is rendered in the DOM. Defaults to div.

...rest
  :  object
  |  optional

All other props are spread onto the DOM element as HTML attributes.

#useSlider

This is a hook you can use to access the context.

import react from 'react';
import { useSlider } from '@faceless-ui/slider;

export const MyComponent = () => {
  const slider = useSlider();
  return (
    ...
  )
};

#Accessibility

This package strictly follows the WAI-ARIA pattern for carousels:

  • <Slide> has the following properties:
    • role is group
    • aria-roledescription is slide
    • aria-label is CURRENT_INDEX of TOTAL_SLIDES
  • <SliderTrack> has the following properties:
    • aria-live is either polite or off based on autoPlay
  • <SliderButton> is a <button> element with the following properties:
    • aria-label is either Go to previous slide, Go to next slide, or Go to slide SLIDE_INDEX
    • aria-controls is SLIDER_ID
  • <DotNav> renders <button> elements with the following properties:
    • aria-label is either Go to slide SLIDE_INDEX
    • aria-controls is SLIDER_ID

You should also add the following to your own markup on the top-level element that contains the slider components. This is because this part of the DOM is out of the scope of this module:

  • aria-roledescription should be carousel
  • aria-label should be an accessible name not including the keyword carousel

NOTE: To match ARIA attributes between DOM elements, a random string is generated with the useId hook. To opt out of this, just pass your own id to the <SliderProvider> and it will be used instead.

#TypeScript

All types can be directly imported.

import {
  ISliderContext,
  SliderSettings,
  SliderProviderProps,
  ISlide,
  SlideProps,
  SliderProgressProps,
  ProgressIndicatorProps,
  SliderButtonProps,
  DotsNavProps,
  SliderTrackProps
} from '@faceless-ui/slider/dist/types';