Scroll Controller

A Scroll Controller is a special variable type that controls the scrolling behavior of scrollable widgets. It allows you to programmatically control scroll positions, create scroll-driven animations, and respond to scroll events.

Supported Widgets

The Scroll Controller can be used with:

• Animation Builder

• Smart Scroll View

• Grid View

• List View

When to Use

Use a Scroll Controller when you need to:

• Programmatically scroll to specific positions

• Create "scroll to top" buttons

• Implement scroll-driven animations (parallax, fade effects)

• Animate scrolling with custom easing curves

• Track and respond to scroll positions

• Synchronize scroll positions across multiple widgets

Creating a Scroll Controller

1. Navigate to Variables in your project

2. Click Add Variable

3. Select Scroll Controller as the type

4. Give it a descriptive name (e.g., listScrollController, pageScrollController)

Binding to Widgets

ListView Example

ListView:
  Controller: ${listScrollController}
  Data Source: ${items}

GridView Example

GridView:
  Controller: ${gridScrollController}
  Data Source: ${products}

Smart Scroll View Example

Smart Scroll View:
  Controller: ${pageScrollController}

Controller Methods

Use the Control Object action to invoke these methods on the controller.

jumpTo

Instantly jumps to a scroll position without animation.

Parameter	Type	Description
offset	Number	The scroll position in pixels

Example Use Cases:

• Jump to top: offset: 0

• Jump to bottom: offset: 99999

• Jump to specific position: offset: 500

When to Use:

• Immediate positioning needed (e.g., reset scroll on navigation)

• No animation required

• Faster than animateTo

---

animateTo

Smoothly animates the scroll to a given position.

Parameter	Type	Description
offset	Number	The scroll position in pixels
durationInMs	Number	Animation duration in milliseconds
curve	String	The easing curve for animation

Available Curves:

• linear - Constant speed

• easeIn - Slow start, fast end

• easeOut - Fast start, slow end

• easeInOut - Slow start and end, fast middle

• bounceOut - Bouncing effect at end

• elasticOut - Elastic spring effect

Example Use Cases:

• Smooth scroll to top: offset: 0, durationInMs: 500, curve: 'easeOut'

• Scroll to section: offset: 1200, durationInMs: 800, curve: 'easeInOut'

• Quick scroll: offset: 500, durationInMs: 200, curve: 'linear'

When to Use:

• Better UX with smooth transitions

• Highlighting a scroll action

• Drawing attention to content

---

Common Use Cases

1. Scroll to Top Button

Show a button that appears after scrolling down, which scrolls back to top when clicked.

Setup:

Variable: showScrollTop (Boolean)
Initial Value: false

Variable: listScrollController (Scroll Controller)

Implementation:

ListView:
  Controller: ${listScrollController}

Animation Builder (using same controller):
  Controller: ${listScrollController}
  
  Child:
    Floating Action Button:
      Visible: ${gt(animationValue, 300)}
      On Click:
        Control Object:
          Object: ${listScrollController}
          Method: animateTo
          Arguments:
            offset: 0
            durationInMs: 500
            curve: 'easeOut'

2. Scroll-Driven Animations

Create effects that respond to scroll position (headers that fade, parallax backgrounds).

Setup:

Variable: scrollController (Scroll Controller)

ListView:
  Controller: ${scrollController}

Animation Builder:
  Controller: ${scrollController}
  
  Child:
    Container (Header):
      Opacity: ${clamp(diff(1, divide(animationValue, 200)), 0, 1)}
      Height: ${clamp(diff(200, animationValue), 50, 200)}

The animationValue variable inside Animation Builder represents the current scroll offset.

See the Using ListView with Animation Builder guide for detailed examples.

3. Navigate to Specific Section

Scroll to a specific item or section in a list.

On Section Button Click:
  Control Object:
    Object: ${pageScrollController}
    Method: animateTo
    Arguments:
      offset: ${sectionOffset}
      durationInMs: 600
      curve: 'easeInOut'

4. Reset Scroll on Navigation

Reset scroll position when navigating to a page.

On Page Load:
  Control Object:
    Object: ${listScrollController}
    Method: jumpTo
    Arguments:
      offset: 0

5. Synchronized Scrolling

Use the same controller on multiple widgets to synchronize their scroll positions.

Variable: sharedController (Scroll Controller)

ListView:
  Controller: ${sharedController}

GridView:
  Controller: ${sharedController}

Both widgets will scroll together.

Best Practices

• One controller per scrollable widget: Each scrollable widget should have its own controller unless you want synchronized scrolling

• Use descriptive names: Name controllers after their purpose (listScrollController, pageScrollController)

• Choose appropriate curves: Use easeOut for most scroll animations, linear for quick jumps

• Set reasonable durations: 300-600ms works well for most scroll animations; too long feels sluggish

• Handle edge cases: Check scroll bounds before jumping to calculated positions

• Use jumpTo for immediate actions: Use jumpTo on page load, animateTo for user-triggered actions

• Optimize animation performance: Avoid heavy animations while scrolling for better performance

Common Patterns

Scroll to Top

Control Object:
  Object: ${scrollController}
  Method: animateTo
  Arguments:
    offset: 0
    durationInMs: 500
    curve: 'easeOut'

Scroll to Bottom

Control Object:
  Object: ${scrollController}
  Method: animateTo
  Arguments:
    offset: 99999
    durationInMs: 500
    curve: 'easeOut'

Conditional Visibility Based on Scroll

Animation Builder:
  Controller: ${scrollController}
  
  Child:
    Container:
      Visible: ${gt(animationValue, 200)}

Smooth Scroll to Section

Control Object:
  Object: ${scrollController}
  Method: animateTo
  Arguments:
    offset: ${mul(sectionIndex, itemHeight)}
    durationInMs: 400
    curve: 'easeInOut'

Troubleshooting

Controller Not Working

• Ensure the controller variable is properly created in Variables

• Check that the controller is bound to the widget using ${controllerName}

• Verify the widget supports Scroll Controller

Animation Feels Choppy

• Reduce animation duration

• Use a simpler easing curve like linear

• Check for heavy widgets that might slow rendering

Scroll Position Not Accurate

• Ensure offset values are correct

• Check that content is fully loaded before scrolling

• Consider using jumpTo first, then animateTo

Related Documentation

• Animation Builder - Create scroll-driven animations

• Using ListView with Animation Builder - Detailed guide with examples

• ListView - Scrollable list widget

• GridView - Scrollable grid widget

• Control Object Action - Invoke controller methods

• Variables Overview - Learn about all variable types