Home

Roact Router Basics

Roact Router is a module that provides routing components for Roact based off of React Training's React Router

Router

(Full API: https://github.com/headjoe3/rbx-roact-router/wiki/Router)

The Router component is a path-based browsing space that holds a set of routes, which are conditionally visible based on matching paths.

<Router>
    <Route exact={true} path='/' component={HomePage}/>
    <Route path='/about' component={AboutPage}/>
    <Route path='/contact' component={ContactPage}/>
</Router>

The router can route to a single URL at a time, and the Route components update their visibility based on the Router URL.

The default router path is '/'

Caching:

A router can optionally cache inactive routes. If caching is enabled, inactive routes will keep their elements, but will not be reconciled, and will simply appear in a frame with Visible set to false. This means that rendered components will not re-mount every time the router redirects to a new route, and Instances will not be created or destroyed excessively. This is ideal for having high-performance menus that are rapidly switched.

<Router caching={true}>
    <Route Key="Menu1" exact={true} path='/' component={Menu1}/>
    <Route Key="Menu2" path='/menu2' component={Menu2}/>
</Router>

Nested routes without caching (Menu 1 is active; Menu 2 is inactive):

Nested routes with caching (Menu 2 is still inactive, but it is placed in an invisible frame):

Switch

(Full API: https://github.com/headjoe3/rbx-roact-router/wiki/Switch)

A switch prevents multiple routes from being active at the same time. You can use switches to resolve missing paths

<Router>
    <Switch>
        <Route path="/home" component={HomePage}/>
        <Route path="/about" component={AboutPage}/>
        <Route path="/contact" component={ContactPage}/>
        <Route path="/" render={() => (
            <Redirect to="/home"/>
        )}/>
    </Switch>
</Router>

The last route acts as a default path, since all Router URLs will match '/'

Because Lua tables do not retain the order of string keys, you can use the priority property of routes to set the switch priority for named routes. The routes with the lowest priority property will be checked first when resolving the Router's URL.

<Switch>
    <Router caching={true}>
        <Route priority={0} Key="Menu1" exact={true} path='/' component={Menu1}/>
        <Route priority={1} Key="Menu2" path='/menu2' component={Menu2}/>
    </Router>
</Switch>

Route

(Full API: https://github.com/headjoe3/rbx-roact-router/wiki/Route)

A route renders a single static component when the router's URL resolves to the route's path.

<Route path='/path/to/route' component={MyComponent}/>

Unless the exact property is assigned, all sub paths will be caught by the route. For example:

<Route path='/' component={MyComponent}/>

will catch all routes that begin with '/'. If you only want the literal path "/" to resolve to a route, use the exact property

<Router>
    <Switch>
        <Route exact={true} path="/" component={HomePage}/>
        <Route path="/about" component={AboutPage}/>
        <Route path="/" render={() => (
            <Redirect to="/"/>
        )}/>
    </Switch>
</Router>

The Route component must either have a component property (a component class of type Roact.Component<RoactRouter.RouteComponentProps>), or a render function, which returns a single static component. The render function takes in the RouteComponentProps as a parameter

<Route path="/" render={(props: RoactRouter.RouteComponentProps) => (
    <MyComponent someCallback={() => props.router.redirect("/someURL")}/>
)}/>

Route Component Props

Components that are wrapped by a Route are given a special props, which are defined by the Router that the component is nested in. With the typescript definitions, these components have the type RoactRouter.RouteComponentProps

RouteComponentProps are the main way in which the Router can be redirected by script.

class MyComponent extends Roact.Component<RoactRouter.RouteComponentProps> {
     ...

<Route path='/path' component={MyComponent}/>

The RouteComponentProps can also be accessed by non-Route components which are nested inside of a router using the withRouter(wrappedComponent) function.

class WrappedComponent extends Roact.Component<RoactRouter.RouteComponentProps> {
     ...
}
export const MyComponent = RoactRouter.withRouter(WrappedComponent)

<Router>
     <MyComponent/>
</Router>

match:

The match prop gives information about the URL that was used to match the current active route.

render() {
    const textToDisplay = (
        "Matched URL '" + this.props.match.url + "'\n" +
        "Displaying information for user '" + this.props.match.params.user + "'"
    )
    return (
        <textlabel Text={textToDisplay} Size={new UDim2(0, 100, 0, 100)}/>
    )
}

• props.match.path - The path pattern (defined in the Route's props) that was used to match the active route
• props.match.url - The matched portion of the URL
• props.match.isExact - True iff the entire URL was matched (no trailing characters)
• props.match.params - An object of string route parameters passed in through the route

router:

The router prop contains the essential information and callbacks for controlling the Router that a component is nested in.

render() {
    return (
        <textbutton Text="Go to Menu 2" Size={new UDim2(0, 100, 0, 50)} Event={{
            MouseButton1Click: () => {
                this.props.router.redirect("/menu2")
            }
        }}/>
    )
}

• props.router.redirect(url: string, delay?: number) - Redirects the Router to a new URL. If a delay parameter is provided, the router will spawn a new thread that redirects after the provided duration, as long as the Router is not redirected again in that interval.
• props.router.location - The current URL of the Router component.

Redirect

The Redirect component can also be used to change the URL of a Router. The Redirect changes the Router's path whenever it is rendered, so keep in mind the placement of your Redirects in order to avoid infinite redirect loops.

<Redirect to="/home"/>

By default, Redirect components yield 1/30 of a second before the URL is changed. This interval can be modified through the delay property

<Redirect to="/nowhere" delay={1}/>