diff --git a/docs/resources/ui/widgets/built-in-widgets/carousel.md b/docs/resources/ui/widgets/built-in-widgets/carousel.md index 9063f189..c5bc08c0 100644 --- a/docs/resources/ui/widgets/built-in-widgets/carousel.md +++ b/docs/resources/ui/widgets/built-in-widgets/carousel.md @@ -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. -
- -
-

- -## 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.
-
-

- -### 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. - -
- -

-### 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**. - -
- -
-

+## 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.
-
-

- -### 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. - -
- -
-

- -### 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. - -
- -

-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. -
- -
-

+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.