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 stringto 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 !
Comments are closed.