Carousel

The Carousel widget, also known as an image slider or slideshow, is a popular UI component used to display a series of items (images, content cards, or custom widgets) in a horizontal or vertical scrollable format. Users can swipe through slides manually or let them auto-play.

Carousels are perfect for showcasing featured content, product galleries, onboarding screens, testimonials, or promotional banners within limited screen space.

Our Carousel widget works like Flutter's carousel_slider package, providing smooth transitions, auto-play capabilities, and extensive customization options for creating engaging content sliders.

Use Cases

Carousel is ideal for:

• Image Galleries: Display product photos, portfolio images, or photo albums.

• Featured Content: Highlight promotions, announcements, or top stories.

• Onboarding Screens: Guide users through app features with tutorial slides.

• Product Showcases: Display product details, features, or variations.

• Testimonials: Rotate through customer reviews or success stories.

• News & Articles: Show latest news items or blog posts.

• Promotional Banners: Display rotating ads or special offers.

• Before/After Comparisons: Swipe between comparison images.

User Experience Tip: Carousels are most effective when they have 3-7 slides. Too many slides can overwhelm users, while too few may not justify the carousel format.

---

Core Concepts

1. Dynamic Children Only

The Carousel widget requires a data source to function. You provide a JsonArray of data, and Carousel automatically creates a slide for each item in the array. Each slide uses a single child widget template that you design.

This is the same pattern as ListView and GridView—Carousel is built for data-driven content.

2. Viewport Fractions & Multi-Item Display

Unlike a full-screen slider, Carousel can show multiple items at once:

• Viewport Fraction controls how much of the viewport each slide occupies.

• A value of 1.0 means each slide fills the entire width (single item view).

• A value of 0.8 means each slide takes 80% of the width, showing portions of adjacent slides.

This "peek" effect helps users understand there's more content to explore.

3. Center Page Enlargement

For added visual emphasis, you can enlarge the center (active) slide while keeping adjacent slides at normal size:

• Enable Enlarge Center Page to activate this effect.

• Use Enlarge Factor to control how much bigger the center slide appears.

• Creates a 3D-like "focus" effect that draws attention to the active slide.

---

Data Source Property

The Data Source is required for the Carousel to function. It determines what slides will be displayed.

How to Configure the Data Source

1. In the properties panel, locate the Data Source field.

2. You can provide data in two ways:

Option 1: Static JsonArray

Enter a fixed JSON array directly:

[
  {"image": "https://example.com/image1.jpg", "title": "Slide 1", "description": "First slide"},
  {"image": "https://example.com/image2.jpg", "title": "Slide 2", "description": "Second slide"},
  {"image": "https://example.com/image3.jpg", "title": "Slide 3", "description": "Third slide"}
]

This is useful for prototyping or displaying a fixed set of slides.

Option 2: Dynamic Expression

Bind the data source to an expression that returns a JsonArray:

• From an API Response: ${apiResponse.data.banners}

• From App State: ${appState.featuredProducts}

• From a Variable: ${carouselItems}

The Carousel will automatically update whenever the data source changes.

Accessing Item Data with currentItem

Inside the child template, you have access to special variables:

• currentItem: The data for the current slide being rendered.

  • For objects: ${currentItem.image}, ${currentItem.title}

  • For simple values: ${currentItem}

• index: The zero-based index of the current slide.

Important: The Data Source must be a JsonArray. If you bind it to a non-array value, the Carousel will not render any slides.

---

Properties

Layout & Sizing

Property	Description
Height	The fixed height of the carousel container. Controls how tall the carousel appears on the screen.
Width	The fixed width of the carousel container. If not set, it will expand to fill available width.
Aspect Ratio	The aspect ratio of each slide (width:height). For example, 16:9 for widescreen, 1:1 for square, 4:3 for standard.

Important: When a fixed Height is provided, the Aspect Ratio property has no effect. The carousel will use the specified height directly. To use aspect ratio for responsive sizing, leave the Height property empty or unset.

Scrolling Behavior

Property	Description
Direction	The scroll direction of the carousel. Can be Horizontal (default) or Vertical.
Initial Page	The zero-based index of the slide to show initially. For example, 0 shows the first slide, 1 shows the second slide.
Page Snapping	If true, the carousel snaps to the nearest slide when scrolling stops. Default is true.
Infinite Scroll	If true, the carousel loops continuously—after the last slide, it goes back to the first. Default is true.
Reverse Scroll	If true, the carousel scrolls in the opposite direction.

Viewport & Visual Effects

Property	Description
Viewport Fraction	The fraction of the viewport that each slide occupies. Values between 0 and 1. 1.0 = full width, 0.8 = 80% width (shows peek of adjacent slides). Default is 0.8.
Pad Ends	If true, adds padding to the first and last slides so they can be centered properly.
Enlarge Center Page	If true, the center (active) slide will be larger than adjacent slides, creating a focus effect.
Enlarge Factor	When Enlarge Center Page is enabled, this controls how much bigger the center slide appears. Values between 0 and 1. Default is 0.3 (30% larger).
Keep Alive	If true, the state of each slide is preserved as it scrolls off-screen. Useful for maintaining form inputs or scroll positions within slides.

Auto-Play Settings

Property	Description
Auto Play	If true, the carousel automatically advances to the next slide at regular intervals.
Auto Play Interval (ms)	The delay (in milliseconds) between auto-play transitions. For example, 3000 = 3 seconds between slides. Default is 4000.
Animation Duration (ms)	The duration (in milliseconds) of the slide transition animation. For example, 800 = 0.8 seconds to slide to the next item. Default is 300.

Auto-Play Best Practice: Use auto-play sparingly and ensure the interval is long enough for users to read the content. Always provide manual controls (navigation dots or arrows) so users can pause or navigate manually.

---

Page Indicator Properties

The page indicator (dots) shows users which slide is currently active and how many total slides exist.

Property	Description
Show Indicator	If true, displays page indicator dots below the carousel.
Indicator Offset	The vertical offset (in pixels) of the indicator from the bottom of the carousel. Positive values move it up, negative values move it down.
Dot Width	The width of each indicator dot in pixels.
Dot Height	The height of each indicator dot in pixels.
Spacing	The horizontal spacing between indicator dots in pixels.
Dot Color	The color of inactive (non-active) indicator dots in HEX format.
Active Dot Color	The color of the active indicator dot in HEX format.
Indicator Effect	The animation effect for the indicator transition. Options may include Worm, Expanding, Jumping, Slide, etc.

---

Event Handlers

The Carousel widget supports an event handler that triggers when the active slide changes:

On Changed

This event is triggered whenever the user swipes to a new slide or when auto-play advances to the next slide. The event provides the index of the newly active slide.

Available Data:

• index: The zero-based index of the slide that just became active. You can use this value in your actions to track which slide is currently displayed.

Use Cases:

• Update a custom page counter (e.g., "Slide 2 of 5")

• Track analytics for which slides users view

• Load related content based on the active slide index

• Update app state with the current slide position

• Trigger animations or effects when specific slides are reached

How to Use:

1. Select the Carousel widget.

2. Navigate to Event Handlers in the properties panel.

3. Find On Changed and click + Add Action.

4. Add your desired action (e.g., Set State, Call API, Show Toast).

5. Use ${index} in your action to access the new slide index.

Example: Set a state variable to track the current slide:

• Action: Set State

• Variable: currentSlide

• Value: ${index}

Or display a toast with the slide number:

• Action: Show Toast

• Message: ${concat("Now viewing slide ", sum(index, 1))}

Note: Carousel does not support programmatic navigation via controllers or actions. All slide changes are triggered by user swipes or auto-play. Use the On Changed event to respond to slide transitions.

---

Complete Setup Example

Here's a comprehensive example of setting up a Carousel for a product showcase:

1. Data Source (API or Static)

Static Example:

[
  {
    "productId": 1,
    "name": "Premium Headphones",
    "image": "https://example.com/headphones.jpg",
    "price": 299.99
  },
  {
    "productId": 2,
    "name": "Wireless Speaker",
    "image": "https://example.com/speaker.jpg",
    "price": 149.99
  },
  {
    "productId": 3,
    "name": "Smart Watch",
    "image": "https://example.com/watch.jpg",
    "price": 399.99
  }
]

2. Carousel Configuration

• Data Source: Static array above or ${apiResponse.data.products}

• Height: 300

• Aspect Ratio: 16:9

• Direction: Horizontal

• Initial Page: 0

• Viewport Fraction: 0.85

• Enlarge Center Page: true

• Enlarge Factor: 0.2

• Auto Play: true

• Auto Play Interval: 4000 (4 seconds)

• Animation Duration: 600

• Infinite Scroll: true

• Show Indicator: true

• Dot Color: #CCCCCC

• Active Dot Color: #333333

3. Slide Template (Child Widget)

• Container

  • Padding: 16px

  • Border Radius: 12px

  • Stack

    • Image: ${currentItem.image} (fills container)

    • Positioned (bottom gradient overlay)

      • Column

        • Text: ${currentItem.name} (white, bold)

        • Text: $${currentItem.price} (white)

---

Default Properties

The Carousel widget supports the Layout and Appearance sections from Default Properties. This includes:

• Margin

• Background Color

• Border and Border Radius

• Visibility

Note: Padding is typically controlled by the slide template itself rather than the Carousel container. Add padding to your child widget template for consistent slide spacing.

---

Guides

For comprehensive examples and real-world implementations, see:

https://github.com/Digia-Technology-Private-Limited/digiaDocs/blob/main/docs/guides/carousel-image-sliders.md

This guide includes:

• Product Image Gallery - Build professional product carousels with thumbnails and zoom

• Onboarding Carousel - Create interactive app tours with skip and navigation controls

• Promotional Banners - Implement auto-rotating marketing banners with CTAs

• Featured Content Cards - Design Netflix-style content showcases with peek effects

• Advanced patterns including vertical carousels, manual navigation, and parallax effects

---

Best Practices

• Limit the number of slides to 3-7 items for optimal user experience.

• Make slides tappable by adding onClick actions to the child template to navigate to detail pages.

• Use high-quality images that are optimized for mobile (compressed but clear).

• Provide alternative navigation if using auto-play (dots, arrows, or swipe gestures).

• Set appropriate auto-play intervals (3-5 seconds minimum) so users can read content.

• Use page indicators to show users how many slides exist and their current position.

• Test on different screen sizes to ensure viewport fractions work well across devices.

• Consider accessibility: Auto-play can be disorienting for some users; provide pause controls.

• Optimize slide templates: Keep child widgets lightweight for smooth scrolling performance.

• Use aspect ratios wisely: Consistent aspect ratios create a professional, polished look.