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> ) }
slidesToShow
The number of slides within the track. This effects the width of each slide.
breakpoints
Makes your slider responsive by overriding your slider settings for any CSS media queries.
slideOnSelect
When true
, navigates the slider directly to any slide that is clicked.
scrollOffset
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)
A callback fired on every slide change. Returns the current slide index.
scrollable
Enables both wheel and drag-based events to scroll the track. Defaults to true
. If desired, you can disable dragScroll independently.
dragScroll
Enables drag-based events to scroll the track. Automatically enabled when scrollable scrollable is true
.
scrollSnap
Enables native CSS Scroll Snap. Defaults to true
.
autoPlay
Whether to autoplay on load. Defaults to false
.
autoplaySpeed
The speed of the autoplay. Only applicable when autoplay
is true
. Defaults to 2000
.
marquee
Whether to marquee the slider which scrolls slowly through the track as opposed to sliding one-by-one. autoPlay
must not be enabled.
marqueeSpeed
The speed of the marquee. Only applicable when marquee
is true
. Defaults to 50
.
pauseOnHover
Only applicable when autoPlay
is true
. Defaults to true
.
pause
Stops and startsautoPlay
. Set to undefined
to return control back to the slider.
alignLastSlide
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
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]
This prop will be deprecated in the next major release. Use scrollable
instead.
currentSlideIndex
The index of the current slide.
sliderTrackRef
A reference to the <SliderTrack>
.
goToNextSlide()
Navigates to the next slide. If on the last slide, navigates to the first.
goToPrevSlide()
Navigates to the previous slide. If on the first slide, navigates to the last.
goToSlideIndex(index: string)
Navigates to the given slide index.
slides
An array of every slide in the slider.
isPaused
Returns whether the slider is currently paused. One applicable when pauseOnHover
is true
.
scrollRatio
The current scroll progress of the slider.
slideWidth
The width of each slide in pixels, based on slidesToShow
.
...settings
All settings are spread into the context.
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> ) }
htmlElement
Customize the HTML element that is rendered in the DOM. Defaults to div
.
...rest
All other props are spread onto the DOM element as HTML attributes.
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> ) }
index*
| requiredThe index of the slide.
htmlElement
Customize the HTML element that is rendered in the DOM. Defaults to div
.
...rest
All other props are spread onto the DOM element as HTML attributes.
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> ) }
direction
Set to previous
or next
to navigate to the slider to either the previous or next slide.
index
Navigates the slider to the given index.
Customize the HTML element that is rendered in the DOM. Defaults to button
.
...rest
All other props are spread onto the DOM element as HTML attributes.
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> ) }
htmlElement
Customize the HTML element that is rendered in the DOM. Defaults to div
.
...rest
All other props are spread onto the DOM element as HTML attributes.
indicator
Allows you to customize the indicator component.
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> ) }
dotClassName
A class name to apply to each dot. This could also be achieve using dotProps
.
activeDotClassName
A class name to apply to active dots.
dotProps
Arbitrary rops to spread onto each dot button.
htmlElement
Customize the HTML element that is rendered in the DOM. Defaults to div
.
...rest
All other props are spread onto the DOM element as HTML attributes.
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 ( ... ) };
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.
All types can be directly imported.
import { ISliderContext, SliderSettings, SliderProviderProps, ISlide, SlideProps, SliderProgressProps, ProgressIndicatorProps, SliderButtonProps, DotsNavProps, SliderTrackProps } from '@faceless-ui/slider/dist/types';