React <AwesomeSlider />

@rcaferati/react-awesome-slider provides a fast, production-ready slider/carousel with optional HOCs:

• AwesomeSlider — animated media/children slider
• withAutoplay — autoplay wrapper
• withCaptionedImages — caption overlay wrapper
• withAnimatedLettering — “screens → `

lines” wrapper - **Navigation utilities** —Provider,Link,withNavigationContext,withNavigationHandlers`

This README is updated for the current v5 patterns (functional core + CSS variables + optional CSS Modules support).

---

Installation

npm install @rcaferati/react-awesome-slider

Peer dependencies:

• react >= 18
• react-dom >= 18

---

Quick Start

Plain CSS (no CSS Modules)

import React from 'react';
import AwesomeSlider from '@rcaferati/react-awesome-slider';
import '@rcaferati/react-awesome-slider/styles.css';

export default function Example() {
  return (
    <AwesomeSlider>









    </AwesomeSlider>
  );
}

Media prop (recommended for deterministic slides)

import React from 'react';
import AwesomeSlider from '@rcaferati/react-awesome-slider';
import '@rcaferati/react-awesome-slider/styles.css';

export default function Example() {
  return (
    <AwesomeSlider
      media={[
        { source: 'https://picsum.photos/id/1018/1200/600', slug: 'slide-1' },
        { source: 'https://picsum.photos/id/1015/1200/600', slug: 'slide-2' },
        { source: 'https://picsum.photos/id/1019/1200/600', slug: 'slide-3' },
      ]}
    />
  );
}

---

Animations

Default animation: sideAnimation

The default “side” animation ships in the base stylesheet:

import '@rcaferati/react-awesome-slider/styles.css';

Extra animation recipes

Load one of the extra animation stylesheets and set animation:

• cubeAnimation
• fallAnimation
• foldOutAnimation
• openAnimation
• scaleOutAnimation

import React from 'react';
import AwesomeSlider from '@rcaferati/react-awesome-slider';

import '@rcaferati/react-awesome-slider/styles.css';
import '@rcaferati/react-awesome-slider/custom-animations/cube-animation.css';

export default function Example() {
  return (
    <AwesomeSlider animation="cubeAnimation">









    </AwesomeSlider>
  );
}

Tip: when using the default side animation, omit the animation prop entirely.

Importing animation module objects

This package also exports animation subpaths such as:

• @rcaferati/react-awesome-slider/custom-animations/cube-animation
• @rcaferati/react-awesome-slider/custom-animations/fall-animation

Those module exports are useful for cssModule setups because they provide the class-name mapping object.

Important: in current consumer setups such as Vite, the JS/MJS animation import alone should not be treated as enough to load the stylesheet into the page. You should still import the public CSS file as a side effect.

Plain CSS users

Use only the public CSS file:

import '@rcaferati/react-awesome-slider/custom-animations/cube-animation.css';

cssModule users

Import both:

1. the public CSS file so the rules are actually injected
2. the JS module export so you can pass the mapping object into cssModule

import React from 'react';
import AwesomeSlider from '@rcaferati/react-awesome-slider';
import sliderStylesRaw from '@rcaferati/react-awesome-slider/styles';

import '@rcaferati/react-awesome-slider/styles.css';

import '@rcaferati/react-awesome-slider/custom-animations/cube-animation.css';
import cubeAnimationRaw from '@rcaferati/react-awesome-slider/custom-animations/cube-animation';

const sliderStyles = sliderStylesRaw?.default ?? sliderStylesRaw;
const cubeAnimation = cubeAnimationRaw?.default ?? cubeAnimationRaw;

export default function Example() {
  return (
    <AwesomeSlider
      animation="cubeAnimation"
      cssModule={[sliderStyles, cubeAnimation]}
    >






    </AwesomeSlider>
  );
}

In other words:

• .css import → injects the stylesheet
• JS/MJS import → provides the module mapping for cssModule

For the widest compatibility, prefer the public CSS files whenever possible.

---

Styling

CSS variables (recommended)

The core stylesheet exposes CSS variables on the slider root element (default root key: awssld). You can override them per instance using style:

import React from 'react';
import AwesomeSlider from '@rcaferati/react-awesome-slider';
import '@rcaferati/react-awesome-slider/styles.css';

export default function Example() {
  return (
    <AwesomeSlider
      style={{
        // arrows
        '--organic-arrow-color': 'rgba(255,255,255,0.9)',
        '--organic-arrow-height': '44px',
        '--organic-arrow-thickness': '4px',

        // bullets
        '--control-bullet-color': 'rgba(255,255,255,0.35)',
        '--control-bullet-active-color': 'rgba(255,255,255,0.9)',

        // content
        '--content-background-color': '#10131a',
      }}
      media={[
        { source: 'https://picsum.photos/id/1018/1200/600' },
        { source: 'https://picsum.photos/id/1015/1200/600' },
      ]}
    />
  );
}

CSS Modules (cssModule)

If your bundler emits CSS module maps, you can pass module objects via cssModule.

The package exports a styles entry:

import React from 'react';
import AwesomeSlider from '@rcaferati/react-awesome-slider';
import sliderStylesRaw from '@rcaferati/react-awesome-slider/styles';
import '@rcaferati/react-awesome-slider/styles.css';

const styles = sliderStylesRaw?.default ?? sliderStylesRaw;

export default function Example() {
  return (
    <AwesomeSlider cssModule={styles}>






    </AwesomeSlider>
  );
}

If you are also using a custom animation module export, combine them as an array and still import the corresponding CSS file:

import React from 'react';
import AwesomeSlider from '@rcaferati/react-awesome-slider';
import sliderStylesRaw from '@rcaferati/react-awesome-slider/styles';

import '@rcaferati/react-awesome-slider/styles.css';

import '@rcaferati/react-awesome-slider/custom-animations/cube-animation.css';
import cubeAnimationRaw from '@rcaferati/react-awesome-slider/custom-animations/cube-animation';

const core = sliderStylesRaw?.default ?? sliderStylesRaw;
const cube = cubeAnimationRaw?.default ?? cubeAnimationRaw;

export default function Example() {
  return (
    <AwesomeSlider animation="cubeAnimation" cssModule={[core, cube]}>






    </AwesomeSlider>
  );
}

In most consumer apps, plain CSS imports are simpler and more portable than CSS-module object imports.

---

AwesomeSlider

Common usage patterns

Children mode

import React from 'react';
import AwesomeSlider from '@rcaferati/react-awesome-slider';
import '@rcaferati/react-awesome-slider/styles.css';

export default function Example() {
  return (
    <AwesomeSlider>



        <h2 style={{ color: 'white' }}>Slide A</h2>






        <h2 style={{ color: '#111' }}>Slide B</h2>



    </AwesomeSlider>
  );
}

Media mode

import React from 'react';
import AwesomeSlider from '@rcaferati/react-awesome-slider';
import '@rcaferati/react-awesome-slider/styles.css';

export default function Example() {
  return (
    <AwesomeSlider
      media={[
        { source: '/img/0.jpg', slug: 'a' },
        { source: '/img/1.jpg', slug: 'b' },
      ]}
    />
  );
}

---

AwesomeSlider Props (current)

Prop	Type	Default	Description
media	MediaItem[]	[]	Slides as objects ({ source, slug, preload? }).
children	ReactNode	null	Slides as React children (supports data-src / data-slug).
selected	number \| string	0	Active slide index (number) or slug (string).
name	string	'awesome-slider'	Instance name (useful when multiple sliders are present).
animation	string \| null	null	Animation key (cubeAnimation, fallAnimation, etc). Omit for default side animation.
buttons	boolean	true	Show next/prev buttons.
bullets	boolean	true	Show bullets.
organicArrows	boolean	true	Use the organic arrow shape styling.
infinite	boolean	true	Wrap-around navigation.
fillParent	boolean	false	Fill parent bounds (fullscreen layouts).
startupScreen	ReactNode	null	Optional startup screen shown before first slide.
startup	boolean	true	If startupScreen is set, whether to auto-start into the first slide.
startupDelay	number	0	Delay before auto-start.
transitionDelay	number	0	Delay before starting transition animation (ms).
controlsReturnDelay	number	0	Delay to remove the “controls active” class after transitions (ms).
mobileTouch	boolean	true	Enables touch/swipe navigation.
cssModule	object \| object[] \| null	null	CSS module map(s) used to map class names.
className	string \| null	null	Extra className(s) added to the root element.
style	React.CSSProperties	{}	Inline styles, including CSS variable overrides.
onFirstMount	(info) => void	null	Called once after mount with getInfo() payload.
onTransitionStart	(info) => void	null	Called on transition start.
onTransitionEnd	(info) => void	null	Called on transition end.
onTransitionRequest	(info) => void	null	Called when the user requests a transition (next/prev/bullet).
onTransitionReject	(info) => void	null	Called when a transition is rejected (for example, busy/loading).
onLoadStart	(payload) => void	null	Optional custom preload hook. Call payload.next() when ready.

getInfo() payload (high level)

getInfo() is used by the event callbacks and includes, best-effort:

• slides — slide count
• currentIndex — current index
• currentMedia — current media item
• currentSlide — active slide element (when available)
• element — slider root element

---

HOCs

Autoplay

import React from 'react';
import AwesomeSlider from '@rcaferati/react-awesome-slider';
import withAutoplay from '@rcaferati/react-awesome-slider/autoplay';
import '@rcaferati/react-awesome-slider/styles.css';

const AutoplaySlider = withAutoplay(AwesomeSlider);

export default function Example() {
  return (
    <AutoplaySlider
      play={true}
      cancelOnInteraction={false}
      interval={6000}
      media={[
        { source: 'https://picsum.photos/id/1018/1200/600' },
        { source: 'https://picsum.photos/id/1015/1200/600' },
      ]}
    />
  );
}

Captioned Images

```jsx import React from 'react'; import AwesomeSlider from '@rcaferati/react-awesome-slider'; import withCaptionedImages from '@rcaferati/react-awesome-slider/captioned';

import '@rcafer