Download this source code for
5 USD


Download this source code for
5 USD


Download this source code for
5 USD


Download this source code for
5 USD

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 !


Download this source code for
5 USD


Download this source code for
5 USD


Download this source code for
5 USD


Download this source code for
5 USD

Top