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

{% embed url="<https://www.youtube.com/watch?v=HnC7rdMnt9A>" %}

Watch this on Youtube: <https://www.youtube.com/watch?v=HnC7rdMnt9A>

<figure><img src="https://3626461507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbhApDTL7kHrXte2TTtjs%2Fuploads%2Fgit-blob-9b6973fd0f71613d8733008c4d5bdd4114f3267b%2Fpinned_header.gif?alt=media" alt="A hero image showing a refresh indicator with pull-to-refresh animation on a mobile screen." height="300"><figcaption><p>The Refresh Indicator widget provides pull-to-refresh functionality for scrollable content.</p></figcaption></figure>

{% hint style="warning" %}
**Important**: Pinned Header **only works inside Smart Scroll View**. Using it outside of Smart Scroll View will result in an error or unexpected behavior.
{% endhint %}

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

{% hint style="success" %}
**Best Practice**: Always place Pinned Header as the first child inside a Smart Scroll Group within Smart Scroll View for optimal sticky behavior.
{% endhint %}

### 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](https://api.flutter.dev/flutter/widgets/SliverPersistentHeader-class.html).

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