# Documentation for AI agents

This file is generated at build time from the Markdown documentation. Use it to choose the most relevant page before reading the canonical HTML documentation.

## Router by Before Semicolon

URL: https://router.beforesemicolon.com/
Source: docs/index.md
Description: A tiny Web Component router for HTML-first apps. Declare links, routes, redirects, query routes, lazy pages, guards, and route data without framework lock-in.

::: layout landing-hero version="@beforesemicolon/router" title="Routing" title2="in plain HTML." primaryLabel="Get Started" secondaryLabel="$ npm i @beforesemicolon/router" === copy A tiny Web Component router for HTML-first apps. Route by pathname or search query, lazy-load HTML/JS/TXT pages, nest route layouts, guar

## What is Router? - HTML-First Web Component Routing

URL: https://router.beforesemicolon.com/documentation/
Source: docs/documentation/index.md
Description: Learn how Before Semicolon Router brings declarative, lazy, guarded, framework-agnostic routing to HTML, Web Components, SPAs, MPAs, and hybrid apps.

What is Router? @beforesemicolon/router is a Web Component based routing solution for single-page apps, multi-page apps, and hybrid sites that want client-side navigation without adopting a framework router. It uses custom elements, so routes live in the same HTML structure as the views they control. You can start with

## Get Started with Router - Before Semicolon

URL: https://router.beforesemicolon.com/documentation/get-started
Source: docs/documentation/get-started.md
Description: Build your first HTML-first Router app with page-link, page-route, page-data, lazy route files, and 404 redirects.

Get Started Setting up routing does not require a route config file, wrapper framework, or build tool. A small app can be fully routed with HTML tags, and a larger app can move each view into lazy HTML or JavaScript route files. Let's build a simple multi-tab dashboard step-by-step: Step 1: Add the Scripts Import the r

## Install Router - Before Semicolon

URL: https://router.beforesemicolon.com/documentation/installation
Source: docs/documentation/installation.md
Description: Install @beforesemicolon/router with npm, yarn, pnpm, or direct browser script tags for HTML-first Web Component routing.

Installation @beforesemicolon/router works in bundled applications and directly in modern browsers through CDN script tags. Package Managers Install the package via your preferred package manager to bundle it with Vite, Webpack, or Esbuild: npm yarn pnpm Direct CDN (Zero-Build) For simple HTML prototypes or build-less 

## Router Guide & Best Practices - Router by Before Semicolon

URL: https://router.beforesemicolon.com/documentation/guide-best-practices
Source: docs/documentation/guide-best-practices.md
Description: Practical guidance for building maintainable HTML-first routing with Before Semicolon Router, including route structure, redirects, guards, links, and lazy loading.

Guide & Best Practices Router works best when the URL is treated as the source of truth for navigation, filters, tabs, and shareable UI state. Keep route declarations close to the layout they control, then use the JavaScript API only for behavior that cannot be expressed cleanly in HTML. Start With Declarative Routes F

## AI Guide for Before Semicolon Router

URL: https://router.beforesemicolon.com/documentation/ai
Source: docs/documentation/ai.md
Description: A compact reference for AI assistants and developers generating Router code, with accurate components, APIs, patterns, and constraints.

AI Guide Use this page as the compact reference when generating examples, tutorials, migrations, or application code for @beforesemicolon/router. Package Purpose @beforesemicolon/router is an HTML-first routing library built with Web Components. It provides custom elements for navigation and route rendering, plus a sma

## Page Route Component - Router by Before Semicolon

URL: https://router.beforesemicolon.com/documentation/web-components/page-route
Source: docs/documentation/web-components/page-route.md
Description: Learn how to render pathname routes, dynamic params, nested layouts, lazy route files, component props, loading slots, fallbacks, and route groups.

<page-route The <page-route component is the main route container. It mounts slotted content, a lazy src file, or a JavaScript-provided component only when the current pathname matches its route pattern. Attributes | Attribute | Type | Default | Description | | :-------- | :-------- | :---------- | :-------------------

## Page Route Query Component - Router by Before Semicolon

URL: https://router.beforesemicolon.com/documentation/web-components/page-route-query
Source: docs/documentation/web-components/page-route-query.md
Description: Learn how to render views conditionally based on search queries using `<page-route-query>`.

<page-route-query The <page-route-query component mounts content conditionally based on URL search query parameter values (?key=value) instead of the URL pathname. This component is ideal for creating tabbed navigation, filters, or modular modals without writing JavaScript state logic. Attributes | Attribute | Type | D

## Page Link Component - Router by Before Semicolon

URL: https://router.beforesemicolon.com/documentation/web-components/page-link
Source: docs/documentation/web-components/page-link.md
Description: Learn how to manage active states, relative path resolution, and pass history payload data using `<page-link>`.

<page-link The <page-link component renders a standard HTML anchor (<a) tag wrapper that intercepts click events, updates browser history, and highlights itself with an active attribute when matching the current location. Attributes | Attribute | Type | Default | Description | | :-------------------- | :-------- | :---

## Page Redirect Component - Router by Before Semicolon

URL: https://router.beforesemicolon.com/documentation/web-components/page-redirect
Source: docs/documentation/web-components/page-redirect.md
Description: Learn how to manage default paths and handle 404 fallbacks using `<page-redirect>`.

<page-redirect The <page-redirect component triggers programmatic redirection. It is used to handle unknown URLs (404 errors) or to route parent index paths to a default sub-route. Attributes | Attribute | Type | Default | Description | | :-------- | :------------------------ | :---------- | :--------------------------

## Page Data Component - Router by Before Semicolon

URL: https://router.beforesemicolon.com/documentation/web-components/page-data
Source: docs/documentation/web-components/page-data.md
Description: Learn how to display pathname params, search query values, and history state payload values in HTML using `<page-data>`.

<page-data The <page-data component allows you to print current routing parameters, search queries, or history state directly in HTML without writing JavaScript selectors. Attributes | Attribute | Type | Default | Description | | :------------- | :------- | :---------- | :-----------------------------------------------

## Programmatic Navigation - Router by Before Semicolon

URL: https://router.beforesemicolon.com/documentation/routing-apis/navigation
Source: docs/documentation/routing-apis/navigation.md
Description: Learn how to transition paths, pass payloads, and go back/forward in history using JavaScript.

Navigation APIs These functions trigger state updates in the browser's history session, allowing you to transition between pages programmatically. goToPage Adds a new entry to the browser's history stack. Example replacePage Updates the current entry in the history stack instead of creating a new one. This is ideal for

## Subscription Observers - Router by Before Semicolon

URL: https://router.beforesemicolon.com/documentation/routing-apis/subscribing
Source: docs/documentation/routing-apis/subscribing.md
Description: Learn how to observe route patterns or listen to global navigation events.

Subscribing APIs These APIs notify your JavaScript code when URL modifications or navigation events occur. onPage Subscribes to a specific route pattern. The callback triggers whenever the matched state transitions (e.g., active to inactive, or parameters change). - Returns a cleanup function to unsubscribe. - active: 

## Params & Queries APIs - Router by Before Semicolon

URL: https://router.beforesemicolon.com/documentation/routing-apis/params-queries
Source: docs/documentation/routing-apis/params-queries.md
Description: Learn how to retrieve pathname parameters, read search queries, and update search queries.

Params & Queries APIs These functions allow you to read and write parameters or history states programmatically. getPageParams Retrieves an object containing all parameters parsed from the current URL pathname. Example getSearchParams Retrieves parsed URL query parameters as a key-value object. Supports automatic JSON 

## Route Registration APIs - Router by Before Semicolon

URL: https://router.beforesemicolon.com/documentation/routing-apis/registration
Source: docs/documentation/routing-apis/registration.md
Description: Learn how to register pathname patterns and compile paths using JavaScript.

Route Registration APIs These utilities allow you to manage registered route patterns and compile parameterized paths dynamically. registerRoute Manually registers a route pattern with the central matching engine. This is performed automatically by <page-route tags but can be done imperatively in JS. - If a boolean is 

## Route Guards - Router by Before Semicolon

URL: https://router.beforesemicolon.com/documentation/advanced-features/route-guards
Source: docs/documentation/advanced-features/route-guards.md
Description: Learn how to secure paths and perform checks before transitioning using route guards.

Route Guards Route Guards allow you to protect routes with authentication checks, authorization, or other custom logic. Guards can block navigation entirely or redirect the user to a different location. Guard Return Values A guard function can return: - true: Allow the navigation. - false: Block the navigation (remains

## Hash Routing - Router by Before Semicolon

URL: https://router.beforesemicolon.com/documentation/advanced-features/hash-routing
Source: docs/documentation/advanced-features/hash-routing.md
Description: Learn how to set up URL hash-based routing (#/path) for static hosting environments.

Hash Routing The router supports both standard HTML5 History API routing (pathnames) and Hash-based routing (#/path). Hash routing is perfect for static file hosting environments (like GitHub Pages or Netlify static deploys) because it bypasses the need for server-side redirection fallback configurations. setRoutingMod

## Module Registry - Router by Before Semicolon

URL: https://router.beforesemicolon.com/documentation/advanced-features/module-registry
Source: docs/documentation/advanced-features/module-registry.md
Description: Learn how to pre-register page modules for code splitting and bundler integration.

Module Registry When building large-scale applications with modern asset bundlers (like Vite or Webpack), dynamic string imports in the src attribute (e.g. <page-route src="./pages/home.js") are difficult for bundlers to trace during static analysis. The Module Registry allows you to pre-register a map of page paths to

## Route Metadata - Router by Before Semicolon

URL: https://router.beforesemicolon.com/documentation/advanced-features/route-metadata
Source: docs/documentation/advanced-features/route-metadata.md
Description: Learn how to attach permissions, layouts, or custom page properties to routes.

Route Metadata You can attach custom metadata (such as page layouts, breadcrumbs, permissions, or access roles) when registering routes. Metadata is stored by the registered route pattern. Use the same pattern when calling getRouteMeta. Attaching Metadata Pass metadata inside the options configuration of registerRoute:

## Component Prop - Router by Before Semicolon

URL: https://router.beforesemicolon.com/documentation/advanced-features/component-prop
Source: docs/documentation/advanced-features/component-prop.md
Description: Learn how to pass component references directly to routes for type safety and bundler compilation.

Component Prop Instead of using the src attribute with file path strings, <page-route allows you to pass component constructor/class references directly using the component property. This approach is highly recommended when bundling applications, as it provides compile-time type-checking and robust source mapping. Bene