xrpl-dev-portal/shared/patterns/CarouselFeatured/README.md

CarouselFeatured

A featured image carousel pattern with a two-column layout on desktop (image left, content right) and single-column layout on tablet/mobile (content top, image bottom). Features a heading, feature list with dividers, optional buttons, and navigation controls.

Usage

import { CarouselFeatured } from '@/shared/patterns/CarouselFeatured';

<CarouselFeatured
  slides={[
    {
      id: 1,
      heading: "Powered by Developers",
      features: [
        { title: "Easy-to-Integrate APIs", description: "Build with common languages..." },
        { title: "Full Lifecycle Support", description: "From dev tools to deployment..." },
      ],
      buttons: [
        { label: "Get Started", href: "/docs" },
        { label: "Learn More", href: "/about" }
      ],
      imageSrc: '/image1.jpg',
      imageAlt: 'Slide 1'
    },
  ]}
  background="grey"
/>

Props

Required Props

Prop	Type	Description
slides	CarouselSlide[]	Array of slides to display in the carousel

Optional Props

Prop	Type	Default	Description
background	'grey' | 'neutral' | 'yellow'	'grey'	Background color variant
transition	'slide' | 'fade'	'fade'	Slide transition style. See Transitions

Transitions

Value	Behavior
'fade' (default)	Slides crossfade in place with no lateral movement. The image and heading lead, then the feature list, then the buttons, each on a 60ms stagger. Reads best when slides share a heading and only the supporting content changes — a horizontal wipe would drag the identical heading across the screen and set it back down where it started.
'slide'	Slides wipe horizontally. Opt into this when each slide is a genuinely distinct panel and the lateral movement communicates that.

Both styles collapse to an instant swap under prefers-reduced-motion: reduce.

'fade' stacks every slide in a single CSS grid cell, so the carousel still sizes to the tallest slide and won't change height between slides.

Type Definitions

CarouselSlide

interface CarouselSlide {
  id: string | number;  // Unique identifier for the slide
  heading: string;      // Heading text for the slide
  features: CarouselFeatureItem[]; // Slide feature list
  buttons?: ButtonConfig[]; // Optional slide buttons
  imageSrc: string;     // Image source URL
  imageAlt: string;     // Alt text for the image
}

CarouselFeatureItem

interface CarouselFeatureItem {
  title: React.ReactNode;        // Feature title node
  description: React.ReactNode;  // Feature description node
}

ButtonConfig

interface ButtonConfig {
  label: string;        // Button text
  href?: string;        // Optional link URL
  onClick?: () => void; // Optional click handler
}

Background Variants

The component supports three background variants that adapt to light/dark mode:

• grey (default): Light mode: gray-200 (#E6EAF0), Dark mode: gray-300 (#CAD4DF)
• neutral: Light mode: white (#FFF), Dark mode: black (#141414)
• yellow: Light mode: yellow-100 (#F3F1EB), Dark mode: yellow-100 (#F3F1EB)

Features

• Responsive Layout: Two-column on desktop (lg+), single-column on mobile/tablet
• Image Carousel: Navigate through multiple slides with prev/next buttons
• Auto-hide Navigation: Navigation buttons automatically hide when only one slide is present
• Feature List: Display multiple features with dividers
• Button Group: Supports 1-2 buttons with validation
• Background Variants: Three color options with light/dark mode support
• Accessibility: Proper ARIA labels for navigation buttons

Layout Behavior

Desktop (lg+)

• Image column on the left (6 columns)
• Content column on the right (6 columns)
• Navigation buttons in header (desktop variant)

Tablet/Mobile

• Content section at the top
• Image section at the bottom
• Navigation buttons in CTA section (mobile variant)

Examples

See the Props and Transitions sections above for the available configurations.

Notes

• Navigation buttons are automatically hidden when slides.length === 1
• Buttons are validated using validateButtonGroup with a maximum of 2 buttons
• Button colors are automatically adjusted based on the background variant
• The component uses ButtonGroup pattern for consistent button styling