Router

Define routes

Route are defined in an array of route object. Each route should map to a component.

Signature

type RouteConfig = {
  path: string
  component: Component
  props: any
};

Example

src/app.js

import Home from 'src/components/home';
import About from 'src/components/about';

const routes = [
  {
    path: '/',
    component: Home
  },
  {
    path: '/about',
    component: About
  }
];

Route props

Inject props in the route. Then, props are exposed in the component props.

src/app.js

const app = new App({
  target: document.querySelector('#app'),
  routes: [
    {
      path: '/',
      component: Home,
      props: {
        name: 'John Doe'
      }
    }
  ]
});

Dynamic routing

Dynamic routes can be achieved by dynamic segments declared in the path of the route. Dynamic segments start with a colon. You can have multiple segments in the same route, and they will mapped to the corresponding fields on this.route.params in the component class.

In addition to this.route.params, the this.route object also exposes other useful information such as this.route.path (current path in URL). You can see all the details in the Component reference.

const routes = [
  {
    path: '/person/:id',
    component: Home
  }
];

Try it on CodeSandbox.

Not found route

If no route path matches, the active component is automatically destroyed. To display a template instead, declare a component without the path in the route configuration passed to the app instance.

function NotFound() {
  return <h2>Not found</h2>;
}

const routes = [
  {
    component: NotFound
  }
];

info

If the silentOnNotFound parameter is enabled, the not found route is ignored.

Try it on CodeSandbox.

Navigation

Link

We use the <Link> custom component to create links that match route path in the template. This allows the router to change the url without reloading the page.

Import

import { Link } from 'costro';

Import `Link` with CDN links

Link is exposed in the global variable window.Costro.

JSX

<Costro.Link></Costro.Link>

Template String

`${Costro.Link()}`;

Signature

export declare function Link(options: Options, isHtml: boolean): HTMLElement | string;

type Options = {
  to: string
  children: any[]
  attrs: {
    [key: string]: string
  }
};

Parameters

Parameter	Type	Description
options.to	String	Route path
options.children	(HTMLElement\|String)[]	The children of the element
options.attrs	...Object	The attributes of the element
isHtml	Boolean	The function is called from HTML

Return

The output generated as an HTMLElement for JSX or a string for HTML.

Example

JSX

<Link to="/about">About</Link>

Try it on CodeSandbox.

Template String

`${Link(
  {
    to: '/about',
    children: ['About']
  },
  true
)}`;

Try it on CodeSandbox.

HTML

<a href="/about">About</a>

tip

Links can have any valid HTML attribute and children as text or Node elements.

Navigate

We use the navigate function to trigger navigation changes. It can be used with event handling or anywhere in component.

Import

import { navigate } from 'costro';

Import `navigate` with CDN links

navigate is exposed in the global variable window.Costro.

Costro.navigate();

Signature

navigate(to: string): void;

Example

src/components/home.js

class Home extends Component {
  render() {
    return <button onClick={() => navigate('/about')}>About</button>;
  }
}

Try it on CodeSandbox.

History mode

The router's default mode is hash mode. It uses URL hash to perform URL navigation without reloading the page, e.g. https://example.com/#/about.

To not use hash, we can use the router's history mode, based on the history.pushState API to perform the same behavior, e.g. https://example.com/about.

const app = new App({
  mode: 'history',
  target: document.querySelector('#app'),
  routes: []
});

Try it on CodeSandbox.

info

When using history mode, you need to add a fallback route to your server. If the URL does not match any static element, it must serve the same index.html page that your application resides on.

Server configurations

The following examples assume you are serving your app from the root folder. If you are deploying to a subfolder, you need to adjust the examples below to use the subfolder path instead of the root folder path (e.g. for Apache, replace RewriteBase / with RewriteBase /subfolder-path/).

Apache

<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteBase /
  RewriteRule ^index\.html$ - [L]
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d
  RewriteRule . /index.html [L]
</IfModule>

nginx

location / {
  try_files $uri $uri/ /index.html;
}