Skip to main content
The NavigationData class is the core building block for defining routes in NavigationUtils. It encapsulates all the necessary information for a route including the URL pattern, page builder, and optional metadata.

​
Overview

Each route in your application is defined using a NavigationData instance. This class maps URLs to specific pages and provides configuration options for page transitions, dialogs, and more. 
NavigationData(
  label: ProjectPage.name,
  url: '/project',
  builder: (context, routeData, globalData) => const ProjectPage(),
)

​
Properties

​
label
String?
Optional label for the route, used for named navigation. This allows you to reference routes by name instead of URL, similar to Navigator 1.
NavigationData(
  label: ProjectsPage.name,
  url: '/projects',
  builder: (context, routeData, globalData) => const ProjectsPage(),
)
​
url
String
required
The URL pattern for this route. Must start with /. Supports path parameters using : syntax.
// Simple URL
url: '/projects'

// URL with path parameter
url: '/project/:id'

// Nested URL
url: '/user/:userId/posts/:postId'
​
builder
NavigationPageFactory
required
Function that builds the widget for this route. Receives three parameters:
  • context - The build context
  • routeData - Route data containing path, query parameters, etc.
  • globalData - Global data associated with the route
builder: (context, routeData, globalData) => ProjectPage(
  id: int.tryParse(routeData.queryParameters['id'] ?? ''),
)
​
pageType
PageType?
The type of page transition to use. Available options:
  • PageType.material - Material Design page transition (default)
  • PageType.transparent - Transparent page transition
  • PageType.cupertino - iOS-style page transition
NavigationData(
  url: '/dialog',
  pageType: PageType.transparent,
  builder: (context, routeData, globalData) => DialogPage(),
)
​
fullScreenDialog
bool?
Whether this route should be displayed as a fullscreen dialog. When true, the page will be presented modally.
NavigationData(
  url: '/settings',
  fullScreenDialog: true,
  builder: (context, routeData, globalData) => SettingsPage(),
)
​
barrierColor
Color?
The barrier color for modal routes. Only applies when using transparent page type.
NavigationData(
  url: '/overlay',
  pageType: PageType.transparent,
  barrierColor: Colors.black54,
  builder: (context, routeData, globalData) => OverlayPage(),
)
​
metadata
Map<String, dynamic>
Optional metadata associated with this route. Useful for route guards, analytics, or custom logic.
NavigationData(
  url: '/premium',
  metadata: {'requiresAuth': true, 'tier': 'premium'},
  builder: (context, routeData, globalData) => PremiumPage(),
)
​
pageBuilder
CustomPageBuilder?
Optional custom page builder for this route. If provided, this takes precedence over the default page building logic.
NavigationData(
  url: '/custom',
  builder: (context, routeData, globalData) => CustomPage(),
  pageBuilder: (key, name, child, routeData, globalData, arguments) {
    return CustomTransitionPage(
      key: key,
      name: name,
      child: child,
    );
  },
)
​
group
String?
Routes can be grouped together by setting a common group name. By default, Flutter identifies routes with unique URLs as unique pages. Setting a group alias overrides this behavior and identifies those routes as the same page.This is particularly useful for tab navigation where multiple URLs should reuse the same widget instance.
NavigationData(
  label: 'home',
  url: '/',
  builder: (context, routeData, globalData) => HomePage(tab: 'home'),
  group: HomePage.name,
),
NavigationData(
  label: 'games',
  url: '/games',
  builder: (context, routeData, globalData) => HomePage(tab: 'games'),
  group: HomePage.name,
),

​
Computed properties

​
uri
Uri
The parsed URI from the url property.
final navigationData = NavigationData(
  url: '/projects?category=flutter',
  builder: (context, routeData, globalData) => ProjectsPage(),
);

print(navigationData.uri); // Prints parsed Uri object
​
path
String
The canonical path from the url, without query parameters.
final navigationData = NavigationData(
  url: '/projects?category=flutter',
  builder: (context, routeData, globalData) => ProjectsPage(),
);

print(navigationData.path); // Prints '/projects'
​
queryParameters
Map<String, String>
The query parameters extracted from the url.
final navigationData = NavigationData(
  url: '/projects?category=flutter&sort=recent',
  builder: (context, routeData, globalData) => ProjectsPage(),
);

print(navigationData.queryParameters); 
// Prints {'category': 'flutter', 'sort': 'recent'}

​
Usage examples

​
Basic route

NavigationData(
  url: '/home',
  builder: (context, routeData, globalData) => const HomePage(),
)

​
Named route with query parameters

NavigationData(
  label: ProjectPage.name,
  url: '/project',
  builder: (context, routeData, globalData) => ProjectPage(
    id: int.tryParse(routeData.queryParameters['id'] ?? ''),
  ),
)

​
Route with path parameters

NavigationData(
  label: ProjectPage.name,
  url: '/project/:projectId',
  builder: (context, routeData, globalData) => ProjectPage(
    id: int.tryParse(routeData.pathParameters['projectId'] ?? ''),
  ),
)

​
Grouped routes for tab navigation

List<NavigationData> routes = [
  NavigationData(
    label: 'home',
    url: '/',
    builder: (context, routeData, globalData) => HomePage(tab: 'home'),
    group: 'home_tabs',
  ),
  NavigationData(
    label: 'games',
    url: '/games',
    builder: (context, routeData, globalData) => HomePage(tab: 'games'),
    group: 'home_tabs',
  ),
  NavigationData(
    label: 'apps',
    url: '/apps',
    builder: (context, routeData, globalData) => HomePage(tab: 'apps'),
    group: 'home_tabs',
  ),
];
All three routes share the same widget instance due to the common group value. Navigating between tabs updates the widget instead of recreating it.

​
Route with custom page type

NavigationData(
  url: '/modal',
  pageType: PageType.transparent,
  barrierColor: Colors.black54,
  builder: (context, routeData, globalData) => const ModalPage(),
)

​
Route with metadata for guards

NavigationData(
  url: '/admin',
  metadata: {
    'requiresAuth': true,
    'requiredRole': 'admin',
  },
  builder: (context, routeData, globalData) => const AdminPage(),
)

​
Type definitions

typedef NavigationPageFactory = Widget Function(
  BuildContext context,
  DefaultRoute routeData,
  Map<String, dynamic> globalData
);
Function type for building navigation pages. This function is called to build the widget for a given route.

​
CustomPageBuilder

typedef CustomPageBuilder = Page Function(
  ValueKey<String>? key,
  String? name,
  Widget child,
  DefaultRoute routeData,
  Map<String, dynamic> globalData,
  Object? arguments,
);
Function type for custom page building. Allows custom creation of Page objects with full control over the page configuration.
The url property must start with /. If it doesn’t, an assertion error will be thrown during initialization.
Use the label property for named navigation to make your code more maintainable and less prone to typos when referencing routes.

Build docs developers (and LLMs) love

Get started for freeTalk to us