Carousel

A professional carousel/slider component that automatically rotates slides, provides navigation controls, and supports customizable transitions. It can display images, text overlays, and call‑to‑action buttons, making it suitable for any site type.

Use Cases

• Hero banners (rotating messages, multiple value propositions)
• Featured products (e-commerce highlights, new arrivals, bestsellers)
• Testimonials (customer quotes, reviews, success stories)
• Image showcases (portfolio highlights, before/after, property tours)
• Promotional content (sales announcements, special offers, events)
• Case studies (project highlights, client work, success stories)
• Team spotlights (employee features, department highlights)
• News/announcements (updates, blog highlights, press mentions)
• Service features (multi-step explanations, benefit highlights)
• Event galleries (conference photos, wedding moments, celebrations)

Properties

slides

Array of slide objects. Each slide contains an image, optional title, description, and CTA button. Type: array. Required: true. Recommendations: count – 3‑5 slides optimal; more than 7 slides reduces effectiveness. images – Use landscape‑oriented images (16:9 or 3:2 aspect ratio) at 1200px+ width. text – Contrast matters! Ensure text is readable over image (component adds dark overlay). consistency – Keep slide structure consistent (all with buttons, or none with buttons).

autoplay

Whether slides automatically rotate. Pauses on user interaction. Type: boolean. Default: true. Visual Impact: true – Slides advance automatically every autoplayDelay milliseconds. Professional and engaging. false – Slides remain static until user clicks navigation. More user‑controlled. Recommendations: hero‑carousels – Use true for dynamic, attention‑grabbing hero sections. testimonials – Use true for rotating customer quotes. detail‑heavy – Use false when slides contain important info users should read at their own pace.

autoplayDelay

Time in milliseconds between automatic slide changes (when autoplay is enabled). Type: number. Default: 5000. Visual Impact: 3000‑4000 – Fast rotation, dynamic feel. Use for simple images/short text. 5000‑6000 – Balanced timing (recommended default). Comfortable reading time. 7000‑8000 – Slow rotation, contemplative feel. Use for detailed content. Recommendations: default – 5000ms (5 seconds) works well for most content. text‑heavy – Use 7000‑8000ms for slides with longer descriptions. image‑focused – Use 4000‑5000ms for visual‑only slides.

showNavigation

Whether to show previous/next arrow buttons on hover. Type: boolean. Default: true. Visual Impact: true – Shows circular arrow buttons on left/right sides (visible on hover). Professional standard. false – No arrow buttons. Users rely on pagination dots or autoplay. Recommendations: default – Use true for best UX. Arrows are standard carousel UI. minimal – Use false only for purely decorative carousels where user control isn’t critical.

showPagination

Whether to show dot indicators at bottom of carousel. Type: boolean. Default: true. Visual Impact: true – Shows dots at bottom indicating total slides and current position. Clickable for direct slide access. false – No dot indicators. Less visual clutter but users can’t see slide count/position. Recommendations: default – Use true. Pagination dots are UX best practice for carousels. many‑slides – Especially important when you have 4+ slides (shows progress).

effect

Transition animation between slides. Type: string. Enum: slide, fade. Default: slide. Visual Impact: slide – Slides horizontally across the screen. Classic carousel feel. More dynamic. fade – Crossfades between slides. Smooth, elegant. More sophisticated. Recommendations: default – Use ‘slide’ for general‑purpose carousels. premium – Use ‘fade’ for luxury/premium brands or sophisticated feel. testimonials – Use ‘fade’ for testimonial carousels (less distracting).

loop

Whether carousel loops back to first slide after last slide (continuous rotation). Type: boolean. Default: true. Visual Impact: true – After last slide, loops back to first slide. Infinite rotation. false – After last slide, stops (or requires manual navigation back to start). Recommendations: autoplay – Use true when autoplay is enabled for continuous rotation. manual – Use false when users manually control slides and looping feels awkward.

customCss

Custom CSS styles for advanced styling. Parsed as CSS property‑value pairs. Applies to outermost Section container. Type: string. Recommendations: none. Examples: “border-radius: 16px; box-shadow: 0 8px 24px rgba(0,0,0,0.12);”, “margin: 40px 0; border: 2px solid #e5e7eb;”, “box-shadow: 0 20px 60px rgba(0,0,0,0.3);”. Security Note: Parsed by cssParser utility. Tenants only affect their own pages (multi‑tenant isolation enforced).

Best Practices

• Use 3‑5 slides for optimal user experience (too many = users won’t see all)
• Keep autoplay delay at 5000ms (5 seconds) for comfortable reading time
• Always include navigation arrows AND pagination dots for user control
• Use high‑quality, landscape‑oriented images (1200px+ width recommended)
• Keep slide titles concise (5‑8 words) and descriptions to 2‑3 sentences
• Include CTA buttons only when actionable (don’t force buttons on every slide)
• Use ‘slide’ effect for general content, ‘fade’ for elegant transitions
• Enable loop for continuous rotation (especially with autoplay)
• Use search_unsplash for professional, contextually relevant slide images

Common Mistakes

Using too many slides (8+ slides)

Why it's a problem: Users won’t see all slides. Carousel effectiveness drops dramatically after 5‑6 slides.

Fix: Limit to 3‑5 slides. If you have more content, use multiple carousels or different component.

Setting autoplayDelay too short (<3000ms)

Why it's a problem: Users can’t read slide content before it changes. Creates frustration and poor UX.

Fix: Use minimum 5000ms (5 seconds) for slides with text. 7000ms for detailed content.

Not using search_unsplash for slide images

Why it's a problem: Without real image URLs, carousel shows broken images.

Fix: Call search_unsplash for EACH slide with relevant queries. Use EXACT urls returned.

Inconsistent slide structure (some with buttons, some without)

Why it's a problem: Creates visual inconsistency. Users don’t know which slides are actionable.

Fix: Either all slides have buttons, or none do. Be consistent.

Using low-resolution or portrait images

Why it's a problem: Carousel is full‑width and 500px tall. Portrait images get cropped awkwardly. Low‑res looks unprofessional.

Fix: Use landscape images (16:9 or 3:2 aspect ratio) at 1200px+ width from Unsplash.

Putting critical information only in carousel

Why it's a problem: Not all users will see all slides (especially without autoplay). Critical info gets missed.

Fix: Use carousel for highlights/features. Put critical info in static sections.

Disabling both navigation and pagination (showNavigation: false, showPagination: false)

Why it's a problem: Users have no way to control the carousel manually. Bad UX.

Fix: Always enable at least one control method. Default: both enabled.