Convenient Route Creation API

The router provides convenient functions for creating routes with all the features you need: async loading, loading components, metadata (title & breadcrumbs), and conditions.

Choose the method that fits your needs:

  • createRoute() - Returns wrapped component (most convenient, no wrap() needed)
  • createRouteDefinition() - Returns definition for use with wrap() (advanced use)

Component Types: Sync vs Async

📦 Understanding Component Loading

The router supports both synchronous (immediate) and asynchronous (lazy-loaded) components. Choosing the right approach impacts your app's performance and user experience.

Synchronous Components (Direct Import)

Use direct component references for routes that should be immediately available. These components are included in the initial bundle.

Synchronous components 
 
 
✅ Best For:
 
  • Home page / landing page
    •  
  • Frequently visited routes
    •  
  • Small components (<10KB)
    •  
  • Routes needing instant navigation
    •  
  • Components with no heavy dependencies
 
⚠️ Drawbacks:
 
  • Increases initial bundle size
    •  
  • Slower initial page load
    •  
  • All code loaded even if never used
    •  
  • Not ideal for admin panels or rare routes
 
Asynchronous Components (Dynamic Import)
 
Use () => import() syntax for routes that should be lazy-loaded. These components are split into separate
        chunks and loaded on-demand.
 
Asynchronous components (code-splitting) 
 
 
 
✅ Best For:
 
  • Admin panels
    •  
  • Rarely visited routes
    •  
  • Large components (>50KB)
    •  
  • Routes with heavy dependencies (charts, editors)
    •  
  • Conditional features (paid tiers)
 
💡 Benefits:
 
  • Smaller initial bundle - Faster first load
    •  
  • On-demand loading - Load only what's needed
    •  
  • Better caching - Chunks cached separately
    •  
  • Parallel loading - Multiple routes can load at
                  once
 
⚡ Performance Tip
 
Hybrid approach works best: Use sync components for common
          routes (home, about) and async components for specialized features (admin,
          reports, settings).
 
Example: If your admin panel is 200KB but only 10% of
          users visit it, lazy-loading saves 180KB for 90% of your users!
 
createRoute() - Recommended
 
The most convenient way to create routes. It returns a ready-to-use
        wrapped component, so you don't need to call wrap() manually.
 
Basic Usage
 
Basic route creation 
 
 
 
With Breadcrumbs
 
Add breadcrumb navigation to your routes:
 
Routes with breadcrumbs 
 
 
 
With Conditions
 
Add route guards to protect routes:
 
Routes with conditions 
 
 
 
With Static Props
 
Pass static props to your route components:
 
Routes with static props 
 
 
 
Accessing Route Metadata
 
There are two ways to access route metadata: via component props or via
        reactive helpers.
 
Method 1: Reactive Helpers (Recommended)
 
The router provides reactive helpers that automatically update when
        routes change. This is perfect for displaying title/breadcrumbs in your
        app layout.
 
Using reactive helpers (recommended) 
 
 
 
Method 2: Component Props
 
Access metadata directly in your route components via userData prop:
 
Using component props 
 
 
 
Reusable Components
 
Create reusable components that automatically display metadata:
 
Reusable metadata components 
 
 
 
createRouteDefinition() - Advanced
 
For more control or when you need to combine with other wrap options,
        use createRouteDefinition() which returns a plain object
        that you pass to wrap().
 
Advanced route configuration 
 
 
 
API Comparison
 
Recommended: createRoute()
 
Best for: Most use cases
 
  • Returns wrapped component
    •  
  • No wrap() needed
    •  
  • Clean, simple syntax
    •  
  • Automatic async detection
    •  
  • Built-in title & breadcrumbs support
 
createRoute() 
 
 
 
Advanced: createRouteDefinition()
 
Best for: Advanced scenarios
 
  • Returns plain object
    •  
  • Requires wrap()
    •  
  • More control over wrapping
    •  
  • Combining with other options
 
createRouteDefinition() 
 
 
 
Complete Example
 
Here's a complete example showing all the features:
 
Complete route configuration 
 
 
 
Data Loading with shouldDisplayLoadingOnRouteLoad
 
For routes that fetch data and need dynamic titles, use the shouldDisplayLoadingOnRouteLoad flag to keep the loading component visible until data loads.
 
Pattern 1: Router-Managed Loading (Zone-specific)
 
Set shouldDisplayLoadingOnRouteLoad: true to let the router
        handle loading state. Component just fetches data and calls hideLoading(). Perfect for multi-zone layouts.
 
Router-managed loading 
 
 
 
Pattern 2: Component-Managed Loading (Default)
 
Default behavior - component handles its own loading state internally.
 
Component-managed loading 
 
 
 
Best Practices
 
Use createRoute() by default
 
Use createRoute() for most cases - it's simpler and
          cleaner. Only use createRouteDefinition() when you need explicit control over
          wrapping.
 
Dynamic Titles
 
For detail pages that load data, use shouldDisplayLoadingOnRouteLoad: true and updateRouteMetadata() to show specific titles like "Invoice.pdf"
          instead of generic "Document".
 
Consistent Breadcrumbs
 
Keep breadcrumb structure consistent across related pages. Include
          paths for all navigable breadcrumb items except the current page.
 
Loading Components
 
Always provide a loading component for async routes to improve user
          experience during route transitions. Use shouldDisplayLoadingOnRouteLoad: true for data-driven routes.
 
Page Titles
 
Set descriptive titles for all routes. Use them in your components
          with <svelte:head> for proper SEO and browser history.
 
Related Features
 
Learn about related routing features: