Skip to content

feat: Add support for the NavigationBar widget #476

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
divyanshub024 merged 4 commits into from
May 13, 2026
Merged

feat: Add support for the NavigationBar widget #476

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
a49d1e4
feat: add navigation bar and related components
divyanshub024 May 9, 2026
5358298
refactor: update navigation components for improved state management
divyanshub024 May 12, 2026
882ab1b
Merge branch 'dev' into dv/navigation-bar
divyanshub024 May 12, 2026
594d7db
refactor: enhance index handling in NavigationController
divyanshub024 May 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -133,6 +133,7 @@
"widgets/linear_progress_indicator",
"widgets/list_tile",
"widgets/listview",
"widgets/navigation_bar",
"widgets/network_widget",
"widgets/outlined_button",
"widgets/page_view",
Expand Down
317 changes: 317 additions & 0 deletions docs/widgets/navigation_bar.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,317 @@
---
title: "NavigationBar"
description: "Documentation for NavigationBar"
---

import { PLAYGROUND_BASE_URL } from "/snippets/playground_base.mdx";

export const navigationBarPreviewJson = {
"type": "defaultNavigationController",
"length": 3,
"child": {
"type": "scaffold",
"appBar": {
"type": "appBar",
"title": {
"type": "text",
"data": "Navigation Bar Screen"
}
},
"body": {
"type": "navigationView",
"children": [
{
"type": "center",
"child": {
"type": "text",
"data": "Home",
"style": {
"fontSize": 24
}
}
},
{
"type": "center",
"child": {
"type": "text",
"data": "Search",
"style": {
"fontSize": 24
}
}
},
{
"type": "center",
"child": {
"type": "text",
"data": "Profile",
"style": {
"fontSize": 24
}
}
}
]
},
"bottomNavigationBar": {
"type": "navigationBar",
"destinations": [
{
"label": "Home",
"icon": {
"type": "icon",
"iconType": "material",
"icon": "home_outlined"
},
"selectedIcon": {
"type": "icon",
"iconType": "material",
"icon": "home"
}
},
{
"label": "Search",
"icon": {
"type": "icon",
"iconType": "material",
"icon": "search"
}
},
{
"label": "Profile",
"icon": {
"type": "icon",
"iconType": "material",
"icon": "account_circle_outlined"
},
"selectedIcon": {
"type": "icon",
"iconType": "material",
"icon": "account_circle"
}
}
]
}
}
};
export const navigationBarPreviewSrc = `${PLAYGROUND_BASE_URL}/embed`;

The Stac NavigationBar lets you build a Material 3 Flutter NavigationBar widget using JSON. It can be placed in the `bottomNavigationBar` slot of a `StacScaffold` and pairs with a `StacDefaultNavigationController` (with a `StacNavigationView` body) to drive selection state.

To know more about the NavigationBar widget in Flutter, refer to the [official documentation](https://api.flutter.dev/flutter/material/NavigationBar-class.html).

## Properties

| Property | Type | Description |
|---------------------------|-----------------------------------------------|------------------------------------------------------------------------------------------|
| destinations | `List<StacNavigationDestination>` | The destinations shown in the navigation bar. |
| animationDuration | `StacDuration` | Transition time for each destination as it goes between selected and unselected. |
| selectedIndex | `int` | Initial selected index. Ignored if a `StacDefaultNavigationController` is provided. |
| backgroundColor | `StacColor` | The color of the navigation bar itself. |
| elevation | `double` | The z-coordinate at which to place this navigation bar. |
| shadowColor | `StacColor` | The color used for the drop shadow to indicate elevation. |
| surfaceTintColor | `StacColor` | The color used as an overlay on `backgroundColor` to indicate elevation. |
| indicatorColor | `StacColor` | The color of the selected destination's indicator. |
| indicatorShape | `StacBorder` | The shape of the selected destination's indicator. |
| height | `double` | The height of the navigation bar. |
| labelBehavior | `StacNavigationDestinationLabelBehavior` | Defines how labels are laid out and when they are displayed. |
| labelTextStyle | `StacTextStyle` | The text style for destination labels. |
| labelPadding | `StacEdgeInsets` | The padding around each destination's label widget. |
| maintainBottomViewPadding | `bool` | Whether the underlying `SafeArea` maintains the bottom `viewPadding` instead of `padding`.|

## NavigationDestination

The Stac NavigationDestination represents a single destination inside a NavigationBar. To know more, refer to the [official documentation](https://api.flutter.dev/flutter/material/NavigationDestination-class.html).

### Properties

| Property | Type | Description |
|--------------|----------------|-------------------------------------------------------------------|
| icon | `StacWidget` | The icon shown when this destination is unselected. |
| label | `String` | The text label for this destination. |
| selectedIcon | `StacWidget` | The icon shown when this destination is selected. |
| tooltip | `String` | Tooltip text shown on long press. |
| enabled | `bool` | Whether this destination is enabled. Defaults to `true`. |

## Example

<Tabs sync={false}>
<Tab title="Dart">

```dart
StacDefaultNavigationController(
length: 3,
child: StacScaffold(
appBar: StacAppBar(
title: StacText(data: 'Navigation Bar Screen'),
),
body: StacNavigationView(
children: [
StacCenter(
child: StacText(
data: 'Home',
style: StacTextStyle(fontSize: 24),
),
),
StacCenter(
child: StacText(
data: 'Search',
style: StacTextStyle(fontSize: 24),
),
),
StacCenter(
child: StacText(
data: 'Profile',
style: StacTextStyle(fontSize: 24),
),
),
],
),
bottomNavigationBar: StacNavigationBar(
destinations: [
StacNavigationDestination(
label: 'Home',
icon: StacIcon(iconType: 'material', icon: 'home_outlined'),
selectedIcon: StacIcon(iconType: 'material', icon: 'home'),
),
StacNavigationDestination(
label: 'Search',
icon: StacIcon(iconType: 'material', icon: 'search'),
),
StacNavigationDestination(
label: 'Profile',
icon: StacIcon(iconType: 'material', icon: 'account_circle_outlined'),
selectedIcon: StacIcon(iconType: 'material', icon: 'account_circle'),
),
],
),
),
)
```

</Tab>
<Tab title="JSON">

```json
{
"type": "defaultNavigationController",
"length": 3,
"child": {
"type": "scaffold",
"appBar": {
"type": "appBar",
"title": {
"type": "text",
"data": "Navigation Bar Screen"
}
},
"body": {
"type": "navigationView",
"children": [
{
"type": "center",
"child": {
"type": "text",
"data": "Home",
"style": {
"fontSize": 24
}
}
},
{
"type": "center",
"child": {
"type": "text",
"data": "Search",
"style": {
"fontSize": 24
}
}
},
{
"type": "center",
"child": {
"type": "text",
"data": "Profile",
"style": {
"fontSize": 24
}
}
}
]
},
"bottomNavigationBar": {
"type": "navigationBar",
"destinations": [
{
"label": "Home",
"icon": {
"type": "icon",
"iconType": "material",
"icon": "home_outlined"
},
"selectedIcon": {
"type": "icon",
"iconType": "material",
"icon": "home"
}
},
{
"label": "Search",
"icon": {
"type": "icon",
"iconType": "material",
"icon": "search"
}
},
{
"label": "Profile",
"icon": {
"type": "icon",
"iconType": "material",
"icon": "account_circle_outlined"
},
"selectedIcon": {
"type": "icon",
"iconType": "material",
"icon": "account_circle"
}
}
]
}
}
}
```

</Tab>
<Tab title="Preview">
<Frame>
<iframe
id="stac"
src={navigationBarPreviewSrc}
title="Stac Playground"
className="w-full rounded-xl border-0"
style={{ height: "640px" }}
loading="lazy"
onLoad={(event) => {
const iframe = event.currentTarget;
const targetOrigin = PLAYGROUND_BASE_URL;
const message = {
type: "stac-preview-json",
payload: navigationBarPreviewJson
};

let attempts = 0;
const maxAttempts = 12;
const interval = setInterval(() => {
iframe.contentWindow?.postMessage(message, targetOrigin);
attempts += 1;

if (attempts >= maxAttempts) {
clearInterval(interval);
}
}, 250);
}}
/>
</Frame>
</Tab>
</Tabs>
22 changes: 22 additions & 0 deletions examples/stac_gallery/assets/json/home_screen.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -531,6 +531,28 @@
}
}
},
{
"type": "listTile",
"leading": {
"type": "icon",
"icon": "navigation"
},
"title": {
"type": "text",
"data": "Stac Navigation Bar"
},
"subtitle": {
"type": "text",
"data": "Material 3 navigation bar with selectable destinations"
},
"onTap": {
"actionType": "navigate",
"widgetJson": {
"type": "exampleScreen",
"assetPath": "assets/json/navigation_bar_example.json"
}
}
},
{
"type": "listTile",
"leading": {
Expand Down
Loading
Loading