Skip to content

Page Routes

Overview

Every page in a Bellini application is associated with a URL path. When a user navigates to that URL, Bellini loads the corresponding page. Understanding how routes work helps you structure your application's navigation cleanly and avoid conflicts.

What You Will Learn

  • How Bellini constructs page URLs from the configured path
  • How to handle path parameters in routes
  • The rules around path uniqueness and what happens with route conflicts
  • What Bellini displays when no route matches
  • Best practices for naming and structuring routes
  • How query parameters are preserved across page navigation
  • How nested page paths work and how Bellini enforces the parent-child path relationship

When To Use This

Use this page when planning your application's URL structure, troubleshooting navigation issues, or reviewing route naming conventions.

URL Format

Bellini applications use hash-based routing. The URL of a page takes the following form:

1
https://<your-app-domain>/#!/<path>

The #!/ prefix is added automatically by Bellini. The <path> segment is the value you configure in the Path property of each page. For example, a page with Path set to orders/list is accessible at:

1
https://<your-app-domain>/#!/orders/list

The path is case-sensitive. Orders/List and orders/list are treated as different routes.

Path Parameters in Routes

Route paths can include dynamic segments by prefixing a segment with :. For example:

1
orders/:orderId/details

When a user visits #!/orders/42/details, Bellini extracts 42 and makes it available to the page as the orderId parameter.

Path parameters must be declared in the page's Parameters configuration before they can be used. For details on defining and using path parameters, see Page Configuration.

Path Uniqueness and Route Conflicts

Each page's Path must be unique within the application. Two pages cannot share the same path.

If a conflict exists — for example, two pages with paths that match the same URL — Bellini will route to one of them but the behavior is unpredictable. To avoid this:

  • Ensure every page has a distinct, non-overlapping path.
  • Be careful with parametric paths: orders/:id and orders/new overlap when new could be interpreted as an :id value. Give static segments priority by placing them before parametric ones in your naming scheme.

Note: Directories in the Apps view are for organizational purposes only and have no effect on page paths. A page inside a billing/ directory does not automatically get a billing/ prefix in its URL — the path is always exactly what you configure in the Path property.

Query Parameter Persistence

Query parameters appended to a Bellini application URL are preserved across page navigation within the app. If a user arrives at a page with query parameters in the URL (e.g. #!/orders?ref=email), those parameters remain in the URL when Bellini navigates them to another page.

This is particularly useful for post-authentication redirects. For example:

  1. A user follows a link to a private page with a query parameter: #!/dashboard?report=monthly.
  2. Because the page requires authentication, Bellini redirects them to the login page.
  3. After a successful login, Bellini redirects the user back to the original page — and the query parameter report=monthly is still present in the URL.

This means any logic on the destination page that reads from the URL query can reliably act on those values even after an authentication redirect.

Unmatched Routes and 404 Handling

If a user navigates to a URL that does not match any configured page path, Bellini displays a 404 page with a button to return to the home page.

Nested Page Paths

Bellini supports embedding child pages inside a parent page. When this is used, the child page's path must start with the parent page's path — this is how Bellini determines the parent-child relationship at runtime. When you drop a child page onto a parent in the Page Editor, Bellini automatically updates the child's path to be relative to the parent.

For more on building layouts with nested pages, see Page Layout.

Route Best Practices

Consistent route naming makes an application easier to navigate and maintain.

  • Use kebab-case for all path segments: order-details rather than orderDetails or order_details.
  • Use nouns for resource pages and verbs or qualifiers for action pages: orders, orders/:id, orders/new.
  • Keep paths shallow where possible. Deep nesting (e.g. admin/billing/invoices/details/:id) makes URLs harder to read and share.
  • Be explicit with static segments — prefer orders/new over relying on a parameter to carry the concept of "new".
  • Match the path to the page name where practical, so it is easy to identify which page corresponds to a given URL.

Helpful Resources