Pure React Carousel

``` ### <ButtonBack /> A button for moving the slider backwards. Backwards on a horizontal carousel means "move to the left". Backwards on a vertical carousel means "move to the top". The slider will traverse an amount of slides determined by the step property of CarouselProvider. When `children` has no accessible text content and neither `aria-label` nor `aria-labelledby` is provided, `aria-label="previous"` is applied by default. | property | type | default | required | purpose | | -------- | ---- | ------- | -------- | ------- | | **children** | [string|node] | | **Yes** | Children is a special React property. Basically, the ButtonBack component needs to wrap other components and/or JSX | | className | [string|null] | null | No | Optional className string that will be appended to the component's className string. | | disabled | [boolean|null] | null | No | Null means ButtonBack will automatically determine if this button is disabled. Setting this to true will force the button to be disabled. Setting this to false will prevent the button from ever being disabled. | | onClick | [function|null] | null | No | Optional callback function that is called after the internal onClick function is called. It is passed the React synthetic event | #### The ButtonBack component creates the following pseudo HTML by default: ```HTML [props.children] ``` ### <ButtonNext /> A button for moving the slider forwards. Forwards on a horizontal carousel means "move to the right". Backwards on a vertical carousel means "move to the bottom". The slider will traverse an amount of slides determined by the step property of CarouselProvider. When `children` has no accessible text content and neither `aria-label` nor `aria-labelledby` is provided, `aria-label="next"` is applied by default. | property | type | default | required | purpose | | -------- | ---- | ------- | -------- | ------- | | **children** | [string|node] | | **Yes** | Children is a special React property. Basically, the ButtonNext component needs to wrap other components and/or JSX | | className | [string|null] | null | No | Optional className string that will be appended to the component's className string. | | disabled | [boolean|null] | null | No | Null means ButtonNext will automatically determine if this button is disabled. Setting this to true will force the button to be disabled. Setting this to false will prevent the button from ever being disabled. | | onClick | [function|null] | null | No | Optional callback function that is called after the internal onClick function is called. It is passed the React synthetic event | #### The ButtonNext component creates the following pseudo HTML by default: ```HTML [props.children] ``` ### <ButtonFirst /> Moves the slider to the beginning of the slides. When `children` has no accessible text content and neither `aria-label` nor `aria-labelledby` is provided, `aria-label="first"` is applied by default. | property | type | default | required | purpose | | -------- | ---- | ------- | -------- | ------- | | **children** | [string|node] | | **Yes** | Children is a special React property. Basically, the ButtonFirst component needs to wrap other components and/or JSX | | className | [string|null] | null | No | Optional className string that will be appended to the component's className string. | | disabled | [boolean|null] | null | No | Null means ButtonFirst will automatically determine if this button is disabled. Setting this to true will force the button to be disabled. Setting this to false will prevent the button from ever being disabled. | | onClick | [function|null] | null | No | Optional callback function that is called after the internal onClick function is called. It is passed the React synthetic event | #### The ButtonFirst component creates the following pseudo HTML by default: ```HTML [props.children] ``` ### <ButtonLast /> Moves the slider to the end of the slides (totalSlides - visibleSlides). When `children` has no accessible text content and neither `aria-label` nor `aria-labelledby` is provided, `aria-label="last"` is applied by default. | property | type | default | required | purpose | | -------- | ---- | ------- | -------- | ------- | | **children** | [string|node] | | **Yes** | Children is a special React property. Basically, the ButtonLast component needs to wrap other components and/or JSX | | className | [string|null] | null | No | Optional className string that will be appended to the component's className string. | | disabled | [boolean|null] | null | No | Null means ButtonLast will automatically determine if this button is disabled. Setting this to true will force the button to be disabled. Setting this to false will prevent the button from ever being disabled. | | onClick | [function|null] | null | No | Optional callback function that is called after the internal onClick function is called. It is passed the React synthetic event | #### The ButtonLast component creates the following pseudo HTML by default: ```HTML [props.children] ``` ### <ButtonPlay /> Pressing this button causes the slides to automatically advance by CarouselProvider's step property after an interval determined by CarouselProvider's interval property. When the active content (`childrenPlaying` / `childrenPaused` and `children`) has no accessible text content and neither `aria-label` nor `aria-labelledby` is provided, `aria-label="play"` is applied by default. | property | type | default | required | purpose | | -------- | ---- | ------- | -------- | ------- | | children | [string|node] | null | No | Children is a special React property. Content wrapped by ButtonPlay will appear AFTER the content of childrenPaused and childrenPlaying | | childrenPaused | [string|node] | null | No | Content to display when the slide show is paused. | | childrenPlaying | [string|node] | null | No | Content to display when the slide show is playing. | | className | [string|null] | null | No | Optional className string that will be appended to the component's className string. | | disabled | boolean | false | No | Optional boolean passed to the underlying `` element to disable the play/pause button. | | onClick | [function|null] | null | No | Optional callback function that is called after the internal onClick function is called. It is passed the React synthetic event | #### The ButtonPlay component creates the following pseudo HTML by default: ```HTML [props.childrenPlaying | props.childrenPaused] [props.children] ``` ### Hooks and `useContext` `CarouselProvider` uses React's native Context API (`CarouselContext`) and automatically triggers re-renders on consumers whenever the carousel store state updates. You can consume `CarouselContext` directly with `useContext(CarouselContext)` in any functional component rendered inside ``: ```jsx import React, { useContext } from 'react'; import { CarouselContext } from 'pure-react-carousel'; export function MyComponentUsingContext() { const carouselContext = useContext(CarouselContext); const { currentSlide, totalSlides } = carouselContext.state; return (

Slide {currentSlide + 1} of {totalSlides}

carouselContext.setStoreState({ currentSlide: 0 })} > Back to First Slide

); } ``` For backwards compatibility (or if you need an imperative callback when state changes), `carouselContext.subscribe(callback)` and `carouselContext.unsubscribe(callback)` are also supported: ```jsx import React, { useContext, useEffect, useState } from 'react'; import { CarouselContext } from 'pure-react-carousel'; export function MySubscribedComponent() { const carouselContext = useContext(CarouselContext); const [currentSlide, setCurrentSlide] = useState(carouselContext.state.currentSlide); useEffect(() => { function onChange() { setCurrentSlide(carouselContext.state.currentSlide); } carouselContext.subscribe(onChange); return () => carouselContext.unsubscribe(onChange); }, [carouselContext]); return `The current slide is: ${currentSlide}`; } ``` ### WithStore() Higher Order Component __NOTE: ADVANCED USE ONLY.__ (For new functional components, prefer `useContext(CarouselContext)` above.) Use this HOC to pass `CarouselProvider` state properties as props to a component (either a functional component or a class component). Your custom component must be a descendant of ``. It doesn't have to be a direct descendant; it just needs to be rendered somewhere inside ``: ```jsx ``` `WithStore` accepts two arguments: `WithStore(Component, [mapStateToProps])` - The first argument is the component to wrap (e.g., `YourComponentHere`) and is required. Both functional and class components are supported. - The second argument is an optional `mapStateToProps` function `(state) => ({ ... })` that maps the current `CarouselProvider` state to props passed to your component. Here is an example showing the properties available on `CarouselProvider` state: ```jsx import React from 'react'; import { WithStore } from 'pure-react-carousel'; function YourComponentHere(props) { return

Current slide: {props.currentSlide}

; } export default WithStore(YourComponentHere, (state) => ({ // State properties are deeply frozen (read-only). // Pick only the properties your component needs: currentSlide: state.currentSlide, disableAnimation: state.disableAnimation, disableKeyboard: state.disableKeyboard, hasMasterSpinner: state.hasMasterSpinner, imageErrorCount: state.imageErrorCount, imageSuccessCount: state.imageSuccessCount, infinite: state.infinite, interval: state.interval, isIntrinsicHeight: state.isIntrinsicHeight, isPageScrollLocked: state.isPageScrollLocked, isPlaying: state.isPlaying, lockOnWindowScroll: state.lockOnWindowScroll, masterSpinnerFinished: state.masterSpinnerFinished, masterSpinnerThreshold: state.masterSpinnerThreshold, naturalSlideHeight: state.naturalSlideHeight, naturalSlideWidth: state.naturalSlideWidth, orientation: state.orientation, pauseOnInteract: state.pauseOnInteract, playDirection: state.playDirection, slideSize: state.slideSize, slideTraySize: state.slideTraySize, snapAlign: state.snapAlign, snapStop: state.snapStop, snapType: state.snapType, step: state.step, dragStep: state.dragStep, totalSlides: state.totalSlides, touchEnabled: state.touchEnabled, dragEnabled: state.dragEnabled, visibleSlides: state.visibleSlides, })); ``` Any component wrapped with `WithStore` also receives a prop called `carouselStore`, which exposes `getStoreState` and `setStoreState` to read or update the `CarouselProvider`'s state. __setStoreState__: 🦄 🌈 🎂 Use this to update any of the state properties listed above. For example, to skip to slide 2: ```jsx import React from 'react'; import { WithStore } from 'pure-react-carousel'; function YourComponentHere({ carouselStore }) { const handleClick = () => { carouselStore.setStoreState({ currentSlide: 2 }); }; return ( Go to slide 3 ); } export default WithStore(YourComponentHere); ``` Fun fact: you can add any arbitrary values that you want to the `CarouselProvider`'s state. So, if you have several custom components that need to share data, have at it. __masterSpinnerError__: 💀 DON'T USE THIS (internal use only). __masterSpinnerSuccess__: ⚠️ DON'T USE THIS (internal use only). __subscribeMasterSpinner__: 💩 DON'T USE THIS (internal use only). __unsubscribeMasterSpinner__: 🔥 DON'T USE THIS (internal use only). __unsubscribeAllMasterSpinner__: Don't call this manually unless you have some sort of super-customized carousel. This is called internally once all `` and all `` components are finished loading their images. Calling this directly will force a "success" state and the master spinner (the spinner that covers the entire carousel while loading) will turn off. ## TypeScript usage Pure React Carousel is written in TypeScript and ships with complete type definitions in `dist/types/index.d.ts`. Simply import components, hooks, or types directly from `'pure-react-carousel'`. ### Hooks and `useContext` `CarouselContext` is typed as `React.Context`, giving full type inference for `state` (`CarouselState`) and `setStoreState`: ```tsx import React, { useContext } from 'react'; import { CarouselContext } from 'pure-react-carousel'; export function SlideCounter() { const carouselStore = useContext(CarouselContext); return ( carouselStore.setStoreState({ currentSlide: 0 })} > Slide {carouselStore.state.currentSlide + 1} of {carouselStore.state.totalSlides} ); } ``` ### WithStore() Higher Order Component Both functional components and class components (`React.ComponentType`) are supported by `WithStore`. The state and injected store interfaces are exported from `'pure-react-carousel'`: ```ts export interface CarouselState { readonly currentSlide: number; readonly disableAnimation: boolean; readonly disableKeyboard: boolean; readonly hasMasterSpinner: boolean; readonly imageErrorCount: number; readonly imageSuccessCount: number; readonly infinite: boolean; readonly interval?: number; readonly isIntrinsicHeight: boolean; readonly isPageScrollLocked?: boolean; readonly isPlaying: boolean; readonly lockOnWindowScroll: boolean; readonly masterSpinnerFinished: boolean; readonly masterSpinnerThreshold?: number; readonly MasterSpinnerThreshold?: number; readonly naturalSlideHeight: number; readonly naturalSlideWidth: number; readonly orientation: 'horizontal' | 'vertical'; readonly pauseOnInteract?: boolean; readonly playDirection?: 'forward' | 'backward'; readonly privateUnDisableAnimation?: boolean; readonly slideSize: number; readonly slideTraySize: number; readonly snapAlign?: 'start' | 'center' | 'end' | 'none'; readonly snapStop?: 'normal' | 'always'; readonly snapType?: 'mandatory' | 'proximity' | 'none'; readonly step: number; readonly dragStep: number; readonly totalSlides: number; readonly touchEnabled: boolean; readonly dragEnabled: boolean; readonly visibleSlides: number; } export interface CarouselInjectedProps { readonly carouselStore: Pick< CarouselStoreInterface, | 'getStoreState' | 'masterSpinnerError' | 'masterSpinnerSuccess' | 'setStoreState' | 'subscribeMasterSpinner' | 'unsubscribeAllMasterSpinner' | 'unsubscribeMasterSpinner' >; } ``` ### Examples: - With `mapStateToProps` and custom props: ```tsx import React from 'react'; import { CarouselInjectedProps, CarouselProvider, WithStore, } from 'pure-react-carousel'; interface CustomProps { readonly name: string; } interface MappedStateProps { readonly currentSlide: number; readonly disableAnimation: boolean; } function InjectedComponent({ name, currentSlide, disableAnimation, carouselStore, }: CustomProps & MappedStateProps & CarouselInjectedProps) { return (

{name}: Slide {currentSlide} (animation disabled: {String(disableAnimation)}) carouselStore.setStoreState({ currentSlide: 0 })} > Reset

); } const DecoratedComponent = WithStore( InjectedComponent, (state) => ({ currentSlide: state.currentSlide, disableAnimation: state.disableAnimation, }), ); // Usage inside : // ``` - Without `mapStateToProps`: ```tsx import React from 'react'; import { CarouselInjectedProps, WithStore } from 'pure-react-carousel'; interface CustomProps extends CarouselInjectedProps { readonly name: string; } function InjectedComponent({ name, carouselStore }: CustomProps) { return ( carouselStore.setStoreState({ currentSlide: 0 })} > {name} ); } const DecoratedComponent = WithStore(InjectedComponent); ``` ## Advanced Concept: Accessing the "View" Components Directly All the components in Pure React Carousel were designed using the container (model) -> presentation (view) pattern. The `index.ts` file for each component connects to `CarouselContext` via the `WithStore` HOC, selects the required state properties from the carousel store, and passes them to the presentation component as props. For example, look at the structure of the `Slide` component folder: ``` Slide/ ├─ index.ts (container / store connector) ├─ Slide.tsx (view) ``` The `index.ts` file uses the `WithStore` HOC to provide `Slide.tsx` (the view) with all the data it needs from the carousel state—such as `currentSlide`, `naturalSlideWidth`, `naturalSlideHeight`, `slideSize`, `totalSlides`, `visibleSlides`, etc. If you want direct access to the unconnected view component (for example, in unit tests or custom state wrappers), you can import it directly by adding `View` to the end of the component name. This works for all components except `CarouselProvider`: `import { SlideView } from 'pure-react-carousel';` ## Dev Workflow ### Prerequisites - **Node.js**: **v24.18.0** (`>=24.0.0`), pinned in `.nvmrc`, `.node-version`, and `package.json`. - **Vite Plus (`vp`)** *(optional global CLI)*: This repository uses **[Vite Plus](https://viteplus.dev)** (`vite-plus`) for its dev server, bundler, test runner, linter, formatter, and git hooks. All workflows run out of the box via standard `npm run