Route Matching

There are several rules Kitbag Router uses to determine which of your routes corresponds to the current URL.

Named

Routes without a name property cannot be matched.

External Routes

If a route is defined as external, it will only be matched when the url is also external.

Depth

A route’s depth is determined by the number of parent routes it has. The deeper the route, the higher the priority it has when matching.

const external = createExternalRoute({
  name: 'external',
  host: 'https://kitbag.dev',
  path: '/about-us'
})

✅ https://kitbag.dev/about-us
❌ https://example.com/about-us
❌ /about-us

Path Matches

Routes path must match the structure of the URL pathname.

const route = createRoute({
  ...
  path: '/parent/anything/child'
})

✅ parent/anything/child
❌ parent/123/child
❌ parent//child
❌ parent/child

const route = createRoute({
  ...
  path: '/parent/[myParam]/child'
})

✅ parent/anything/child
✅ parent/123/child
❌ parent//child
❌ parent/child

const route = createRoute({
  ...
  path: '/parent/[?myParam]/child'
})

✅ parent/anything/child
✅ parent/123/child
✅ parent//child
❌ parent/child

Query Matches

Routes query must match the structure of the URL search.

const route = createRoute({
  ...
  query: {
    foo: 'bar',
  },
})

✅ ?foo=bar
✅ ?kitbag=cat&foo=bar
❌ ?foo=123
❌ ?foo

const route = createRoute({
  ...
  query: {
    foo: String,
  },
})

✅ ?foo=bar
✅ ?kitbag=cat&foo=bar
✅ ?foo=123
❌ ?foo

const route = createRoute({
  ...
  query: {
    '?foo': String,
  },
})

✅ ?foo=bar
✅ ?kitbag=cat&foo=bar
✅ ?foo=123
✅ ?foo

TIP

when your query param is optional, the entire property can be missing and the route will still match. For the example above with query foo=[?bar], the url might be /my-route without any query, or it might have an unrelated query /my-route?other=value, and still be a match because the entire foo param is optional.

Params Are Valid

Assuming a route's path and query match the structure of the URL, the last test is to make sure that values provided by the URL pass the Param parsing. By default params are assumed to be strings, so by default if structure matches, parsing will pass as well since the URL is a string. However, if you define your params with Boolean, Number, Date, JSON, or a custom Param the value will be need to pass the param's get function.

const route = createRoute({
  ...
  path: '/parent/[id]'
  query: {
    '?tab': String,
  },
})

✅ parent/123
✅ parent/123?tab=true
✅ parent/123?tab=github
✅ parent/ABC?tab=true

const route = createRoute({
  ...
  path: withParams('/parent/[id]', { id: Number })
  query: {
    '?tab': String,
  },
})

✅ parent/123
✅ parent/123?tab=true
✅ parent/123?tab=github
❌ parent/ABC?tab=true

const route = createRoute({
  ...
  path: withParams('/parent/[id]', { id: Number })
  query: withParams('tab=[?tab]', { tab: Boolean })
})

✅ parent/123
✅ parent/123?tab=true
❌ parent/123?tab=github
❌ parent/ABC?tab=true