# 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="/files/RiUfiAOaG1O4b6EvVnrg" 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.digia.tech/ui-building-blocks/widgets/scrolling-widgets/pinned-header.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.