Pinned Header

The Pinned Header widget creates a sticky header that remains fixed at the top of the scrollable area while the content below scrolls underneath it. It provides a persistent navigation or context area that stays visible during scrolling.

The Refresh Indicator widget provides pull-to-refresh functionality for scrollable content.

Important: Pinned Header only works inside Smart Scroll View. Using it outside of Smart Scroll View will result in an error or unexpected behavior.

Core Concepts

Sticky Positioning

Pinned Header uses Flutter's sliver system to create a header that:

• Stays fixed at the top of the scrollable area

• Allows content to scroll underneath it

• Maintains its position regardless of scroll direction

• Provides smooth transitions when appearing/disappearing

Sliver Integration

As a sliver-based widget, Pinned Header:

• Works within CustomScrollView (which Smart Scroll View uses)

• Coordinates with other slivers for unified scrolling

• Handles complex scroll behaviors automatically

• Optimizes performance for large content

Content Flexibility

Can contain any widgets as children:

• Text titles and descriptions

• Buttons and action icons

• Custom layouts and components

• Images and branding elements

Relationship with Smart Scroll View

Pinned Header is specifically designed to work within Smart Scroll View:

• Parent Container: Must be placed inside Smart Scroll View

• Sliver Context: Requires the sliver-based scrolling system

• Coordination: Works with Smart Scroll Group for complex layouts

• Error Prevention: Framework prevents incorrect usage

Best Practice: Always place Pinned Header as the first child inside a Smart Scroll Group within Smart Scroll View for optimal sticky behavior.

Properties

Pinned Header inherits properties from its parent Smart Scroll View and doesn't have additional configurable properties of its own.

📚 Learn More: To understand the underlying Flutter implementation, see the Flutter SliverPersistentHeader documentation.

Default Properties

Layout

The Pinned Header widget supports the following layout properties:

• width

• height

• padding

• margin

Alignment

The Pinned Header widget supports the following alignment property:

• align

Visibility

The Pinned Header widget supports the following visibility property:

• visible

Use Cases

Use Pinned Header when you need:

• Sticky section titles

  • Chapter headers, category names, or section labels that stay visible

  • "Products", "Reviews", "Settings" headers in long content

• Persistent navigation

  • Tab bars or filter options that remain accessible while scrolling

  • Search bars or action buttons that shouldn't scroll away

• Context preservation

  • Important information that users need to reference while scrolling

  • Progress indicators or status information

• Coordinated scrolling experiences

  • Headers that work with scrollable content below them

  • Smooth transitions between pinned and unpinned states