Skip to content

Update Carousel Widget #562

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
pinkeshmars wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update Carousel Widget #562

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
299 changes: 63 additions & 236 deletions docs/resources/ui/widgets/built-in-widgets/carousel.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,56 +2,22 @@
slug: carousel
title: Carousel
tags: [Layout Elements]
description: Learn how to add Carousel widget in your FlutterFlow project.
description: Learn how to add and customize a Carousel widget in your FlutterFlow project.
---

# Carousel
The Carousel widget, often called an image slider, is a popular design element used to display a series of images or content in a horizontal or sometimes vertical format. The primary purpose of a carousel slider is to showcase multiple pieces of information, such as images, product features, news articles, or testimonials, within limited screen space.

<div style={{
position: 'relative',
paddingBottom: 'calc(56.67989417989418% + 41px)', // Keeps the aspect ratio and additional padding
height: 0,
width: '100%'}}>
<iframe
src="https://www.loom.com/embed/bab0e793fb1c4235b9e535223fb5e2ad?sid=2d987f69-d133-48ca-904f-74af107be539"
title=""
style={{
position: 'absolute',
top: 0,
left: 0,
width: '100%',
height: '100%',
colorScheme: 'light'
}}
frameborder="0"
loading="lazy"
webkitAllowFullScreen
mozAllowFullScreen
allowFullScreen
allow="clipboard-write">
</iframe>
</div>
<p></p>

## Adding Carousel widget

To add the Carousel widget to your app:

1. Add the **Carousel** widget from the **Layout Elements** tab.
2. By default, it adds four slides and shows the first one in the canvas. In the widget tree, it is represented as **Carousel Page**. To see another slide in the canvas, move to the **Properties Panel >** set the **Active Page** to the slide you want to see.
3. To add a new slide, move to the **Properties Panel > Active Page >** click **+ Add Page**.
4. To delete any slide, select the **Carousel Page** from the widget tree or the canvas area and press the **Delete** key on the keyboard.
5. By default, Carousel Page contains an Image widget; however, you can customize it as per your requirements.
The **Carousel** widget displays a sequence of images or other content within a limited area. Use it for product highlights, onboarding steps, featured articles, testimonials, and other content that users can browse horizontally or vertically.

<div style={{
position: 'relative',
paddingBottom: 'calc(56.67989417989418% + 41px)', // Keeps the aspect ratio and additional padding
paddingBottom: 'calc(56.67989417989418% + 41px)',
height: 0,
width: '100%'}}>
<iframe
src="https://www.loom.com/embed/511b49c17a0b4d53a2185214c77169ab?sid=4a0fa5e5-a7ba-45be-a4a9-3bd9a67a96ae"
title=""
width: '100%'
}}>
<iframe
src="https://demo.arcade.software/buZIamQKiolwkvo2ATdq?embed&show_copy_link=true"
title="Carousel widget overview"
style={{
position: 'absolute',
top: 0,
Expand All @@ -60,7 +26,7 @@ To add the Carousel widget to your app:
height: '100%',
colorScheme: 'light'
}}
frameborder="0"
frameBorder="0"
loading="lazy"
webkitAllowFullScreen
mozAllowFullScreen
Expand All @@ -70,22 +36,28 @@ To add the Carousel widget to your app:
</div>
<p></p>

## Customizing
## Adding a Carousel Widget

You can customize the appearance and behavior of this widget using the various properties available under the properties panel.
To add and configure a Carousel widget:

### Changing the scroll direction
1. Add the **Carousel** widget from **Layout Elements** in the **Widget Palette**.
2. In the **Properties Panel**, use **Active Page** to select the Carousel Page (slide) you want to preview and edit.
3. Click **+ Add Page** to add a page. To remove one, select its **Carousel Page** in the **Widget Tree** and delete it.
4. Replace the default Image widget or add other widgets to build the content for each page.

By default, the Carousel comes with a horizontal scroll for the slides. To change the scroll direction to vertical, move to the **Properties Panel > Carousel Properties >** set the **Axis** to **Vertical**.
:::tip
Each Carousel page can contain a complete widget tree instead of only an image. For example, you can combine text, buttons, images, and other widgets to create onboarding steps or featured-content cards.
:::

<div style={{
position: 'relative',
paddingBottom: 'calc(56.67989417989418% + 41px)', // Keeps the aspect ratio and additional padding
paddingBottom: 'calc(56.67989417989418% + 41px)',
height: 0,
width: '100%'}}>
<iframe
src="https://www.loom.com/embed/53ef57bfc81745fa9d5801a6d6b2f981?sid=92e6838a-c3d5-48e4-9c11-00e0b41e974e"
title=""
width: '100%'
}}>
<iframe
src="https://demo.arcade.software/AoNsIVHV6LTAXukT5HFv?embed&show_copy_link=true"
title="Add and edit Carousel pages"
style={{
position: 'absolute',
top: 0,
Expand All @@ -94,109 +66,52 @@ By default, the Carousel comes with a horizontal scroll for the slides. To chang
height: '100%',
colorScheme: 'light'
}}
frameborder="0"
frameBorder="0"
loading="lazy"
webkitAllowFullScreen
mozAllowFullScreen
allowFullScreen
allow="clipboard-write">
</iframe>
</div>
<p></p>

### Trigger action on slide chang

You might want to trigger an action when the slide is swiped. For example, If your carousel has an auto-play feature, you can listen for slide change events to pause or resume auto-play. You could also have a custom indicator below the Carousel and have it synchronize with the current slide to provide users with clear feedback about their position within the carousel.

To trigger action on page or slide change:

1. Select the widget from the widget tree or canvas area.
2. Select **Actions** from the Properties panel (the right menu), and click **+ Add Action**.
3. You will notice that the **Type of Action** (aka callback) is already set to **On Page Change**. That means actions added under this will be called whenever the slide is swiped.
4. Now you can add any action here.

Here is an example showing the snackbar message whenever the slide is swiped.

<div style={{
position: 'relative',
paddingBottom: 'calc(56.67989417989418% + 41px)', // Keeps the aspect ratio and additional padding
height: 0,
width: '100%'}}>
<iframe
src="https://www.loom.com/embed/29c3d883bef041a0ba5000a6511186b7?sid=a6de26a0-3d0c-425d-8bca-21de2a254956"
title=""
style={{
position: 'absolute',
top: 0,
left: 0,
width: '100%',
height: '100%',
colorScheme: 'light'
}}
frameborder="0"
loading="lazy"
webkitAllowFullScreen
mozAllowFullScreen
allowFullScreen
allow="clipboard-write">
</iframe>
</div>
<p></p>

### Setting initial page index

You might want to display a specific slide as soon as it is loaded. To do so, move to the **Properties Panel > Carousel Properties >** enter the **Initial Page Index** value. Please **note** that the slide index starts from 0. So, if you want to set slide 1, you should enter 0. If you want to set slide 2, you should enter 1, and so on.
## Customizing a Carousel Widget

![set-initial-index](../../imgs/set-initial-index.png)
Select the Carousel widget and use the following options in the **Properties Panel**:

### Loop carousel contents
- **Axis:** Sets whether users move through the pages horizontally or vertically.
- **Initial Page Index:** Sets the page displayed when the Carousel loads. Page indexes are zero-based: `0` is the first page, `1` is the second, and so on.
- **Loop Carousel Contents:** Allows continuous navigation between the first and last pages.
- **Wrap Items in Center Widget:** Centers the content within each Carousel page.
- **Viewport Fraction:** Sets how much of the available viewport the focused page occupies. Enter a value from `0` to `1`.
- **Shrink Factor:** Scales pages that are not in focus. Enter a value from `0` to `1`, where `1` keeps them at full size and `0.5` displays them at half size.
- **Autoplay:** Automatically advances through the pages. Enable **Loop Carousel Contents** if autoplay should continue from the last page back to the first.
- **Duration:** Sets the page transition time in milliseconds when autoplay is enabled.
- **Delay:** Sets, in milliseconds, how long each page remains visible before autoplay advances.

By default, the content of the carousel loops continuously. To stop this behavior, move to the **properties panel > Carousel Properties >** disable **Loop carousel contents**.

<div style={{
position: 'relative',
paddingBottom: 'calc(56.67989417989418% + 41px)', // Keeps the aspect ratio and additional padding
height: 0,
width: '100%'}}>
<iframe
src="https://www.loom.com/embed/4753d753382f4ef1ae0869c7590742e9?sid=7dda2093-d11f-40d7-9bda-a6487d4248b4"
title=""
style={{
position: 'absolute',
top: 0,
left: 0,
width: '100%',
height: '100%',
colorScheme: 'light'
}}
frameborder="0"
loading="lazy"
webkitAllowFullScreen
mozAllowFullScreen
allowFullScreen
allow="clipboard-write">
</iframe>
</div>
<p></p>
## Using Dynamic Carousel Pages

### Wrap items in a center widget
You can create Carousel pages from a list, such as records returned by a backend query. Select the Carousel widget, open the [**Generate Dynamic Children**](../composing-widgets/generate-dynamic-children.md) tab, and select the list that will provide the Carousel content. Configure the widgets on the generated Carousel page and bind their values to the current list item.

If you want all items in a center position, move to the **properties panel > Carousel Properties >** enable **Wrap items in Center Widget**.
FlutterFlow repeats the Carousel page for every item in the list, making this approach useful for product galleries, promotional content, testimonials, or any collection with a variable number of items.

![wrap-items-in-center-widget](../../imgs/wrap-items-in-center-widget.png)
## Triggering Actions on Page Change

### Changing Viewport and Shrink factor
Use the **On Page Change** trigger to run an action whenever the displayed page changes. For instance, you can update a custom page indicator, save the current page index, or show a message.

You can use the **Viewport Fraction** to change the size of a single item, i.e., the item in the center. The **Shrink Factor** lets you adjust the size of other items, i.e., items that are not in focus. Both the properties accept the value between 0 and 1. where 1 is full size, and 0.5 is half of the actual size.
To add the trigger, select the Carousel widget, open the **Actions** tab in the **Properties Panel**, choose **On Page Change**, and add the action you want to run.

<div style={{
position: 'relative',
paddingBottom: 'calc(56.67989417989418% + 41px)', // Keeps the aspect ratio and additional padding
paddingBottom: 'calc(56.67989417989418% + 41px)',
height: 0,
width: '100%'}}>
<iframe
src="https://www.loom.com/embed/b13c9f9021154347be2bed1df64c783e?sid=664e2f8d-d4ed-44ae-bed0-90ef4ec78b68"
title=""
width: '100%'
}}>
<iframe
src="https://demo.arcade.software/BneySAfYYorg5kcCHsPX?embed&show_copy_link=true"
title="Run an action when a Carousel page changes"
style={{
position: 'absolute',
top: 0,
Expand All @@ -205,123 +120,35 @@ You can use the **Viewport Fraction** to change the size of a single item, i.e.,
height: '100%',
colorScheme: 'light'
}}
frameborder="0"
frameBorder="0"
loading="lazy"
webkitAllowFullScreen
mozAllowFullScreen
allowFullScreen
allow="clipboard-write">
</iframe>
</div>
<p></p>

### Enabling autoplay

When autoplay is enabled, the carousel will automatically transition from one slide to the next at regular intervals, determined by the following options:

- **Duration**: The amount of time (in milliseconds) that it takes to transition from the current slide to the next.
- **Delay**: The amount of time (in milliseconds) that the item remains in the center before moving to the next one.

<div style={{
position: 'relative',
paddingBottom: 'calc(56.67989417989418% + 41px)', // Keeps the aspect ratio and additional padding
height: 0,
width: '100%'}}>
<iframe
src="https://www.loom.com/embed/50f87efbab6c4905bfd8a90645e949b4?sid=6e04b563-0ee0-4710-a667-6ea627bfd060"
title=""
style={{
position: 'absolute',
top: 0,
left: 0,
width: '100%',
height: '100%',
colorScheme: 'light'
}}
frameborder="0"
loading="lazy"
webkitAllowFullScreen
mozAllowFullScreen
allowFullScreen
allow="clipboard-write">
</iframe>
</div>
<p></p>

### Change slide on button press

You might want to allow users to change the slide on button press (e.g., next, previous, and skip buttons) in addition to the swipe. You can do so by adding the **Control Carousel** action on the Tap of a Button widget.

<div style={{
position: 'relative',
paddingBottom: 'calc(56.67989417989418% + 41px)', // Keeps the aspect ratio and additional padding
height: 0,
width: '100%'}}>
<iframe
src="https://www.loom.com/embed/8093ca3175d94916bc18dd011c638a6b?sid=a6fdf60a-f7ff-47fa-bcae-aa59a088ba65"
title=""
style={{
position: 'absolute',
top: 0,
left: 0,
width: '100%',
height: '100%',
colorScheme: 'light'
}}
frameborder="0"
loading="lazy"
webkitAllowFullScreen
mozAllowFullScreen
allowFullScreen
allow="clipboard-write">
</iframe>
</div>
<p></p>

Here's how you do it:

1. First, [add the Carousel](#adding-carousel-widget) widget.
2. Add buttons to go to the previous and next pages.
3. Now select any button and define the [Control Carousel](#control-carousel-action) action.

---
:::tip
To use the displayed page index in an action or widget, select **Set from Variable > Widget State > [Carousel name] > Carousel Current Index**.
:::

## Control Carousel [Action]

By using this action, you can gain more control over the scrolling behavior of the Carousel widget. For instance, you can enable your users to move to the next or previous slide with a single tap of a button.
The **Control Carousel** action lets users navigate the Carousel with a button, icon, or another interactive widget instead of relying only on swiping.

<div style={{
position: 'relative',
paddingBottom: 'calc(56.67989417989418% + 41px)', // Keeps the aspect ratio and additional padding
height: 0,
width: '100%'}}>
<iframe
src="https://www.loom.com/embed/8093ca3175d94916bc18dd011c638a6b?sid=77aea599-ae4a-4820-818c-c6496845f4c3"
title=""
style={{
position: 'absolute',
top: 0,
left: 0,
width: '100%',
height: '100%',
colorScheme: 'light'
}}
frameborder="0"
loading="lazy"
webkitAllowFullScreen
mozAllowFullScreen
allowFullScreen
allow="clipboard-write">
</iframe>
</div>
<p></p>
To configure it:

### Types of action
1. Select the button, icon, or other interactive widget that will control the Carousel.
2. Add an action under the appropriate trigger, such as **On Tap**, and select **Control Carousel**.
3. Select the Carousel you want to control and choose an action type.

These are the types of actions you can add on the Carousel widget.
### Action Types

- **Previous**: Scroll to the previous slide.
- **Next**: Scroll to the next slide.
- **First**: Scroll to the first slide.
- **Last**: Scroll to the last slide.
- **Jump to**: Scroll to a specific slide in the Carousel widget. Please note that the slide index starts from 0. So, if you want to jump to slide 1, you should enter 0. If you want to jump to slide 2, you should enter 1, and so on.
- **Previous:** Moves to the previous page.
- **Next:** Moves to the next page.
- **First:** Moves to the first page.
- **Last:** Moves to the last page.
- **Jump To:** Moves to a specific page using the same zero-based index described above.
Loading