Search packages, repositories and app categories

Package detailsv1.2.1

vrouter

A navigation package that makes navigation and routing easy on every platform. Built on top of Navigator 2.

30-day downloads
285
Likes
322
Pub points
55

Install package

flutter pub add vrouter

Package Overview

Package selection guidance compiled from public package information, community data, and project usage.

vRouter is a navigation package for Flutter that simplifies routing and navigation across all platforms. Built on top of Navigator 2, it provides a declarative and type-safe way to manage app navigation with nested routes, deep linking, and dynamic route handling. It enhances developer experience by reducing boilerplate and improving route management scalability. The package supports platform-agnostic routing logic, making it ideal for complex applications requiring consistent navigation behavior.

Use cases

  • Single-page applications with nested navigation
  • Cross-platform apps needing unified routing
  • Apps requiring deep linking support
  • Complex route hierarchies with dynamic segments
  • Simplified state management in navigation flows

Key features

  • Declarative route configuration
  • Support for nested and dynamic routes
  • Built on Navigator 2 for modern routing
  • Platform-agnostic navigation logic
  • Type-safe route definitions
  • Easy integration with existing Flutter apps

Suitable for

  • Developers building scalable Flutter apps
  • Teams managing complex navigation structures
  • Projects requiring deep linking and URL handling
  • Apps targeting multiple platforms with consistent routing
  • Developers seeking cleaner, more maintainable navigation code

Considerations

  • Requires understanding of Navigator 2 concepts
  • May need additional setup for advanced use cases
  • Limited documentation compared to mainstream packages
  • Best suited for apps with structured navigation needs

Original README

Original README snapshot from the linked source repository. Visit the repository for the latest content.

VRouter logo

VRouter website Join our discord Github repo pub package


A Flutter package that makes navigation and routing easy.

Learn more at vrouter.dev

Here are a few things that this package will make easy:

  • Automated web url handling
  • Nesting routes
  • Transition
  • Advanced url naming
  • Reacting to route changing
  • Customizable pop events
  • And much more...

Index

Getting started

VRouter

VRouter is a widget which handles the navigation, it acts as a MaterialApp but also takes a routes arguments.

VRouter(
 debugShowCheckedModeBanner: false, // VRouter acts as a MaterialApp
 routes: [...], // Put your VRouteElements here
)

VRouteElements

VRouteElements are the building blocs of your routes.

Note that they are not widgets but the way you use them is very similar to widgets.

VWidget

VWidget maps a path to a widget:

VWidget(path: '/login', widget: LoginScreen())
VGuard

VGuard allows you to take actions when the route is accessed/leaved:

VGuard(
 beforeEnter: (vRedirector) async => , // Triggered when a route in stackedRoutes is first displayed
 beforeUpdate: (vRedirector) async => , // Triggered when a route in stackedRoutes is displayed but changes
 beforeLeave: (vRedirector, _) async => , // Triggered when VGuard is not part of a new route
 stackedRoutes: [...],
);
VRouteRedirector

VRouteRedirector redirects from a route to another:

VRouteRedirector(path: '/old/home', redirectTo: '/home')
VNester

VNester are used when you need to nested widgets instead of stacking them:

VNester(
 path: '/home',
 widgetBuilder: (child) => MyScaffold(body: child), // child will take the value of the widget in nestedRoutes
 nestedRoutes: [
   VWidget(path: 'profile', widget: ProfileScreen()), // path '/home/profile'
   VWidget(path: 'settings', widget: SettingsScreen()), // path '/home/settings'
 ],
)
VPopHandler

VPopHandler helps you control pop events:

VPopHandler(
 onPop: (vRedirector) async =>, // Called when this VRouteElement is popped
 onSystemPop: (vRedirector) async =>, // Called when this VRouteElement is popped by android back button
 stackedRoutes: [...],
)

Navigation

Navigating is easy, just access VRouter with context.vRouter and navigate:

context.vRouter.to('/home'); // Push the url '/home'

context.vRouter.toSegments(['home', 'settings']); // Push the url '/home/settings'

Useful notions

Composition

VRouteElements are designed like widgets: compose them to create the route you need.

Compose VRouteElements

To compose VRouteElements, use the stackedRoutes attribute (or the nestedRoutes attribute for VNester):

// Composing a VGuard and a VWidget
VGuard(
 beforeEnter: (vRedirector) async => !isLoggedIn ? vRedirector.to('/login') : null,
 stackedRoutes: [
   VWidget(path: '/home', widget: HomeScreen()),
 ],
)
Create custom VRouteElements

You can even create your own VRouteElement, as you extend VWidget. You just need to extends VRouteElementBuilder:

class HomeRoute extends VRouteElementBuilder {
 static String home = '/home';

 @override
 List<VRouteElement> buildRoutes() {
   return [
     VGuard(
       // LoginRoute.login = '/login' for example
       beforeEnter: (vRedirector) async => !isLoggedIn ? vRedirector.to(LoginRoute.login) : null,
       stackedRoutes: [
         VWidget(path: home, widget: HomeScreen()),
       ],
     ),
   ];
 }
}

and then use this VRouteElement as any other:

VRouter(
 routes: [
   HomeRoute(),
   ...
 ],
)

This can be used to:

  • Separate you different routes in different VRouteElement
  • Create reusable VRouteElement
  • Use static String to organise your paths

Note: you often want to use a shared VNester in different VRouteElementBuilders, for this specific use case, see vrouter.dev/Custom VRouteElement And Scaling

Path

Relative path

Paths can be relative: if you don’t start your path with /. If you use null, the path will be the one of the parent:

VNester(
 path: '/home',
 widgetBuilder: (child) => MyScaffold(body: child),
 nestedRoutes: [
   VWidget(path: null, widget: HomeScreen()), // Matches '/home'
   VWidget(path: 'settings', widget: SettingsScreen()), // Matches '/home/settings'
 ]
)
Path parameters

Paths can have path parameters, just use “:” in front of the path parameter’s name:

VWidget(path: '/user/:id', widget: UserScreen())

And access it in your widgets using:

context.vRouter.pathParameters['id'];
Wildcards

Wildcards are noted * and there are of one of two types:

  • Trailing wildcards (a path ending with *) will match everything
  • an in-path wildcard (a wildcard between slashes) will match one word
// Redirects any path to '/unknown'
VRouteRedirector(path: '*', redirectTo: '/unknown')
Path parameters regexp

Path parameters can use regex, just put the regex in parentheses. This is often used in VRedirector to redirect any unknown route:

// The path parameter name is “bookId” and it uses the regex “\d+” to match only digits
VWidget(path: r':bookId(\d+)', widget: BookScreen())

Note that such a VRedirector should be used as your last route otherwise it will always be matched.

Aliases

Use aliases for multiple paths:

// Matches '/settings' and '/other'
VWidget(path: '/settings', aliases: ['/other'], widget: SettingsScreen())

VRedirector

You often want to redirect or stop the current redirection in VGuard and VPopHandler. For that purpose, you get a VRedirector:

VGuard(
 beforeEnter: (vRedirector) async => !isLoggedIn ? vRedirector.to('/login') : null,
 stackedRoutes: [...],
)

VRouterData

VRouter contains data (such as the path or path parameters) that you might want to access in your widget tree. There are 2 ways of doing do:

// Use the context
context.vRouter

// Use the builder constructor of some VWidget or VNester
VWidget.builder(
  path: '/:id', 
  builder: (context, state) => Book(id: state.pathParameters['id'] as int),
)

Go Beyond

We have just scratched the surface of what VRouter can do. Here are a few other things which you might like.

Initial url

Maybe you want to redirect people to a certain part of your app when they first launch it, then use initialUrl:

VRouter(
 initialUrl: '/home',
 routes: [...],
)

Logs

By default, VRouter shows logs of every navigation events.

You can remove these logs using VLogs.none:

VRouter(
  logs: VLogs.none,
  routes: [...],
);

Named route

You might have to access a deeply nested VRouteElement and don’t want to have to write the full url. Just give a name to this VRouteElement:

VWidget(path: 'something', widget: SomeWidget(), name: 'deep')

And navigate using toNamed:

context.vRouter.toNamed('deep');

Transitions

You can either specify a default transition in VRouter, or a custom one in VWidget or VNester

VRouter(
 // Default transition
 buildTransition: (animation1, _, child) => FadeTransition(opacity: animation1, child: child),
 routes: [
   // The custom ScaleTransition will play for '/user'
   VWidget(
     path: '/user',
     widget: UsersScreen(),
     buildTransition: (animation1, _, child) => ScaleTransition(scale: animation1, child: child),
   )
   // The default FadeTransition will play for '/settings'
   VWidget(path: '/settings', widget: SettingsScreen()),
 ],
)

Much more

There is so much more that this package can do, check out the example or have a look at the vrouter.dev website for more documentation and more examples.

Also don’t hesitate to join us on discord !

Categories

Dependencies

Dependency list 3 items

Source repository

Projects using this package

No data available yet.