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 → <p> 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).

---

Preview

---

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>
      <div data-src="https://picsum.photos/id/1018/1200/600" />
      <div data-src="https://picsum.photos/id/1015/1200/600" />
      <div data-src="https://picsum.photos/id/1019/1200/600" />
    </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">
      <div data-src="https://picsum.photos/id/1018/1200/600" />
      <div data-src="https://picsum.photos/id/1015/1200/600" />
      <div data-src="https://picsum.photos/id/1019/1200/600" />
    </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]}
    >
      <div data-src="https://picsum.photos/id/1018/1200/600" />
      <div data-src="https://picsum.photos/id/1015/1200/600" />
    </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}>
      <div data-src="https://picsum.photos/id/1018/1200/600" />
      <div data-src="https://picsum.photos/id/1015/1200/600" />
    </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]}>
      <div data-src="https://picsum.photos/id/1018/1200/600" />
      <div data-src="https://picsum.photos/id/1015/1200/600" />
    </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>
      <div style={{ background: '#0b0f18', height: '100%' }}>
        <h2 style={{ color: 'white' }}>Slide A</h2>
      </div>
      <div style={{ background: '#f4f6fb', height: '100%' }}>
        <h2 style={{ color: '#111' }}>Slide B</h2>
      </div>
    </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

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

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

const Captioned = withCaptionedImages(AwesomeSlider);

export default function Example() {
  return (
    <Captioned
      screens={[
        {
          media: 'https://picsum.photos/id/1018/1200/600',
          caption: 'The first captioned slide',
          backgroundColor: '#ffffff',
        },
        {
          media: 'https://picsum.photos/id/1015/1200/600',
          caption: 'Second slide — caption overlay',
          backgroundColor: '#ffffff',
        },
      ]}
    />
  );
}

Animated Lettering

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

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

const Lettering = withAnimatedLettering(AwesomeSlider);

export default function Example() {
  return (
    <Lettering
      screens={[
        {
          backgroundColor: '#ffffff',
          children: [
            'React Awesome Slider',
            'Animated Lettering',
            'Each line is a <p>',
          ],
        },
        {
          backgroundColor: '#f5f5f5',
          children: ['Transitions are slide-based', 'Text moves on change'],
        },
      ]}
    />
  );
}

Adaptive Controls

Adaptive Controls is currently part of the repository work and Storybook examples, but it is not listed as a public package export in the current package exports map.

That means:

• it is available in the source repository
• it is not currently documented here as a stable public import path from the npm package

If and when it becomes a public export, it should be documented with its exact import path.

---

Fullpage Navigation Utilities

These are designed for SPA / “slides-as-routes” setups.

Provider

import React from 'react';
import { Provider } from '@rcaferati/react-awesome-slider/navigation';

export default function App({ children }) {
  return (
    <Provider slug={window.location.pathname} defaultSlug="home">
      {children}
    </Provider>
  );
}

Link

import React from 'react';
import { Link } from '@rcaferati/react-awesome-slider/navigation';

export default function Nav() {
  return (
    <nav>
      <Link href="/home">Home</Link>
      <Link href="/about">About</Link>
      <Link href="/contact">Contact</Link>
    </nav>
  );
}

withNavigationHandlers

Wrap a slider so URL ↔ slider selection stays aligned.

import React from 'react';
import AwesomeSlider from '@rcaferati/react-awesome-slider';
import { withNavigationHandlers } from '@rcaferati/react-awesome-slider/navigation';

const SliderWithNav = withNavigationHandlers(AwesomeSlider);

export default function Page() {
  return <SliderWithNav />;
}

withNavigationContext

If you need raw navigation state + setter injected into a component:

import React from 'react';
import { withNavigationContext } from '@rcaferati/react-awesome-slider/navigation';

function Status(props) {
  const { fullpage } = props;
  return <pre>{JSON.stringify(fullpage.navigation, null, 2)}</pre>;
}

export default withNavigationContext(Status);

---

Recommended patterns (current)

✅ Prefer media for stable routing

If you use slugs + navigation handlers, keep media entries stable and include slug.

✅ Keep animations modular

• Always load styles.css
• Load one extra animation CSS only when that animation is selected
• If you use animation module objects with cssModule, still import the matching .css file

✅ Customize via CSS variables first

Theme, contrast, and visual polish are usually easiest via the exposed custom properties.

✅ Use CSS module exports only when your bundler supports them

For the widest compatibility:

• use styles.css
• use captioned.css
• use lettering.css
• use custom-animations/*.css

Use @rcaferati/react-awesome-slider/styles or @rcaferati/react-awesome-slider/custom-animations/* module exports only when your bundler setup expects JS style-module entries, and pair them with the corresponding CSS file imports.

---

Author

Rafael Caferati
Website: https://caferati.dev
GitHub: https://github.com/rcaferati

---

License

MIT