日本語

React Splide

You're browsing the documentation for v3

Introduction

React Splide is a React component for a Splide slider/carousel.

Installation

Get the latest version by NPM:

$ npm install @splidejs/react-splide

Usage

Components

Import Splide and SplideSlide components:

import { Splide, SplideSlide } from '@splidejs/react-splide';
JavaScript

and render them like this:

<Splide>
  <SplideSlide>
    <img src="image1.jpg" alt="Image 1"/>
  </SplideSlide>
  <SplideSlide>
    <img src="image2.jpg" alt="Image 2"/>
  </SplideSlide>
</Splide>
JSX

CSS

Select a CSS file you want to use, and import it:

import '@splidejs/splide/dist/css/splide.min.css';


// or
import '@splidejs/splide/dist/css/themes/splide-skyblue.min.css';
JavaScript

Props

id

id: string

Determines the ID of the slider root element.

className

className: string

A class name for the slider root element.

options

options: Options

Splide options as an object:

<Splide
  options={ {
    rewind: true,
    width : 800,
    gap   : '1rem',
  } }
>
</Splide>
JSX

This property is reactive, which means if you change values, the component will also update the slider. But do not change readonly options, or the slider will be broken.

Extensions

Extensions: Record<string, ComponentConstructor>

Registers extensions as an object literal.

Transition

Transition: ComponentConstructor

Registers the custom transition component.

hasSliderWrapper

hasSliderWrapper: boolean

Determines whether to wrap the track by the slider element.

hasAutoplayProgress

hasAutoplayProgress: boolean

Determines whether to render the progress bar for autoplay.

hasAutoplayControls

hasAutoplayControls: boolean

Determines whether to render play/pause buttons for autoplay.

playButtonLabel

playButtonLabel: string = 'Play'

Sets the label of the play button.

pauseButtonLabel

pauseButtonLabel: string = 'Pause'

Sets the label of the pause button.

renderControls

renderControls: () => ReactNode | ReactNodeArray

Renders custom controls after the track element. This allows you to add your custom arrows and play/pause buttons, etc.

<Splide
  renderControls={ () => (
    <div className="splide__arrows">
      ...
    </div>
  ) }
>
JSX

Events

You can listen to all Splide events through the Splide component. The name of the callback function is generated by the original name with adding an "on" prefix, converting the format to the camelcase and removing colons. For example, "arrows:mounted" becomes "onArrowsMounted". You can see the event list in this file.

<Splide onArrowsMounted={ ( splide, prev, next ) => { console.log( prev, next ) } }>
JSX

Note that the handler always takes the splide instance as the first argument, and original arguments after it.

Accessing Splide Instance

You can access the splide instance though a Ref object by a React.createRef method or an useRef hook.

<Splide ref={ ref }>
  ...
</Splide>
JSX

After React mounts the Splide component, the splide instance is available on ref.current.splide.

componentDidMount() {
  if ( this.ref.current ) {
    console.log( this.ref.current.splide.length );
  }
}


// or
useEffect( () => {
  if ( ref.current ) {
    console.log( ref.current.splide.length );
  }
} );
JSX

Example

Here is a small example:

import React from 'react';
import { Splide, SplideSlide } from '@splidejs/react-splide';


export default () => {
  return (
    <Splide
      options={ {
        rewind: true,
        gap   : '1rem',
      } }
    >
      <SplideSlide>
        <img src="image1.jpg" alt="Image 1"/>
      </SplideSlide>
      <SplideSlide>
        <img src="image2.jpg" alt="Image 2"/>
      </SplideSlide>
      <SplideSlide>
        <img src="image3.jpg" alt="Image 3"/>
      </SplideSlide>
    </Splide>
  );
}
JSX