Interface Navigator

Service for navigating within the application

The Navigator enables programmatic navigation to different locations (routes) within the Lime platform.

Navigation can include:

Path changes (routing to different components)
Query parameter updates
Hash fragment changes
Custom state attached to history entries

All navigation triggers a NavigationEvent via EventDispatcher, allowing other components to respond to location changes.

Routes must be registered with RouteRegistry before navigation.

import { PlatformServiceName } from '@limetech/lime-web-components';

const navigator = platform.get(PlatformServiceName.Navigator);

navigator.navigate('/settings');

import { PlatformServiceName } from '@limetech/lime-web-components';

const navigator = platform.get(PlatformServiceName.Navigator);

// Results in /users?page=2&filter=active
navigator.navigate('/users', { page: 2, filter: 'active' });

import { PlatformServiceName } from '@limetech/lime-web-components';

const navigator = platform.get(PlatformServiceName.Navigator);

navigator.navigate({
    path: '/products/123',
    query: { tab: 'reviews' },
    hash: '#review-456',
    state: { fromSearch: true },
    method: 'push',
});

import {
    NavigationEvent,
    PlatformServiceName,
} from '@limetech/lime-web-components';

const eventDispatcher = platform.get(PlatformServiceName.EventDispatcher);

const onNavigate = (event: NavigationEvent) => {
    console.log('Navigated to', event.detail.path);
    console.log('Query params', event.detail.query);
    console.log('State', event.detail.state);
};

eventDispatcher.addListener('navigate', onNavigate);

// Remember to remove the listener in `disconnectedCallback()`
eventDispatcher.removeListener('navigate', onNavigate);

interface Navigator {
    addBlocker(blocker: Blocker): void;
    createUrl(location: Partial<Location>): URL;
    getLocation(): Location;
    navigate(path: string, query?: Record<string, unknown>): void;
    navigate(location: LocationChange): void;
    removeBlocker(blocker: Blocker): void;
}

Index

Methods

addBlocker createUrl getLocation navigate removeBlocker

Methods

addBlocker

addBlocker(blocker: Blocker): void

Add a navigation blocker to prevent unwanted navigation

Blockers are useful for preventing users from accidentally navigating away when there is unsaved data or ongoing work that would be lost.

The blocker function is called before navigation occurs. Return true to block navigation, or false to allow it. If blocked, use Transition.retry to resume navigation later (e.g., after user confirmation).

Parameters

blocker: Blocker
Function to evaluate whether navigation should be blocked

Returns void

Note

Blockers are not guaranteed to be executed upon a navigation event, for example a hard page unload cannot be intercepted this way. When they are executed, blockers run in the order they were added until one returns true or all have been called.

Example: Basic unsaved changes blocker

import {
    Blocker,
    PlatformServiceName,
    Transition,
} from '@limetech/lime-web-components';

const navigator = platform.get(PlatformServiceName.Navigator);

let hasUnsavedChanges = false;

const blocker: Blocker = (transition: Transition) => {
    if (!hasUnsavedChanges) {
        return false;
    }

    if (confirm('You have unsaved changes. Leave anyway?')) {
        hasUnsavedChanges = false;
        navigator.removeBlocker(blocker);
        transition.retry();
    }

    return true;
};

navigator.addBlocker(blocker);

// Remember to remove the blocker in `disconnectedCallback()`
navigator.removeBlocker(blocker);

Example: Asynchronous confirmation dialog

import {
    Blocker,
    PlatformServiceName,
    Transition,
} from '@limetech/lime-web-components';

const navigator = platform.get(PlatformServiceName.Navigator);

let hasUnsavedChanges = false;

const blocker: Blocker = (transition: Transition) => {
    if (!hasUnsavedChanges) {
        return false;
    }

    void confirmNavigation(transition);

    // Block for now, `retry()` resumes the navigation if the user confirms
    return true;
};

async function confirmNavigation(transition: Transition) {
    const shouldNavigate = await showConfirmDialog();

    if (!shouldNavigate) {
        return;
    }

    hasUnsavedChanges = false;
    navigator.removeBlocker(blocker);
    transition.retry();
}

// Stands in for the dialog the component would open
async function showConfirmDialog(): Promise<boolean> {
    return confirm('You have unsaved changes. Leave anyway?');
}

navigator.addBlocker(blocker);

createUrl

createUrl(location: Partial<Location>): URL

Create a URL object from location data

Converts location information (path, query, hash) into a full URL object. This is useful for generating links or inspecting what the final URL will be without actually navigating.

Parameters

location: Partial<Location>
Location data to convert to a URL

Returns URL

URL object representing the location

Note

The state property is ignored, as state is not part of the URL.

Example: Inspect the parts of a generated URL

import { PlatformServiceName } from '@limetech/lime-web-components';

const navigator = platform.get(PlatformServiceName.Navigator);

const url = navigator.createUrl({
    path: '/products/123',
    query: { tab: 'reviews' },
    hash: '#review-456',
});

// https://example.com/products/123?tab=reviews#review-456
console.log(url.toString());

console.log(url.pathname); // /products/123
console.log(url.search); // ?tab=reviews
console.log(url.hash); // #review-456

Example: Generate a link element

import { h } from '@stencil/core';
import { PlatformServiceName } from '@limetech/lime-web-components';

class ProductLink {
    public render() {
        const navigator = platform.get(PlatformServiceName.Navigator);
        const url = navigator.createUrl({
            path: '/products/123',
            query: { source: 'list' },
        });

        return <a href={url.toString()}>View Product</a>;
    }
}

getLocation

getLocation(): Location

Get the current location information

Returns the complete current location including path, query parameters, hash, and state.

Returns Location

Current location object

Example: Read the current location

import { PlatformServiceName } from '@limetech/lime-web-components';

const navigator = platform.get(PlatformServiceName.Navigator);
const location = navigator.getLocation();

console.log('Current path', location.path);
console.log('Query params', location.query);
console.log('Hash', location.hash);
console.log('State', location.state);

navigate

navigate(path: string, query?: Record<string, unknown>): void
Navigate to a new path with optional query parameters

This is a convenience overload for simple navigation scenarios. For more control over navigation (including hash, state, or method), use the LocationChange overload.
Parameters
- path: string
  The path to navigate to (e.g., '/users/123')
- Optionalquery: Record<string, unknown>
  Optional query parameters to append to the URL
Returns void
Emits
navigate - Triggers a NavigationEvent via EventDispatcher
Example: Simple path navigation
```
import { PlatformServiceName } from '@limetech/lime-web-components';

const navigator = platform.get(PlatformServiceName.Navigator);

navigator.navigate('/settings');
```
Example: Navigation with query parameters
```
import { PlatformServiceName } from '@limetech/lime-web-components';

const navigator = platform.get(PlatformServiceName.Navigator);

// Results in /users?page=2&filter=active
navigator.navigate('/users', { page: 2, filter: 'active' });
```

navigate(location: LocationChange): void

Navigate to a new location or update the current location

This overload provides full control over all aspects of navigation, including path, query parameters, hash, state, and history management.

History Management

By default, the navigation method is automatically determined:

If the path is unchanged (only query/hash/state changes), the current history entry is replaced
If the path changes, a new history entry is pushed

Override this behavior by setting location.method to 'push' or 'replace'.

State Handling

When pushing, state defaults to null if not provided
When replacing, the existing state is preserved unless a new value is provided

Parameters

location: LocationChange
Location data to navigate to or update

Returns void

Emits

navigate - Triggers a NavigationEvent via EventDispatcher

Example: Update only query parameters (replaces current entry)

import { PlatformServiceName } from '@limetech/lime-web-components';

const navigator = platform.get(PlatformServiceName.Navigator);

navigator.navigate({ query: { page: 3 } });

Example: Navigate with custom state

import { PlatformServiceName } from '@limetech/lime-web-components';

const navigator = platform.get(PlatformServiceName.Navigator);

navigator.navigate({
    path: '/products/123',
    state: { fromSearch: true, previousPath: '/search' },
});

Example: Override the automatic push or replace choice

import { PlatformServiceName } from '@limetech/lime-web-components';

const navigator = platform.get(PlatformServiceName.Navigator);

// Replace even though the path changes
navigator.navigate({
    path: '/products/456',
    method: 'replace',
});

// Push even though the path is unchanged
navigator.navigate({
    query: { page: 2 },
    method: 'push',
});

Example: Navigate with hash and query parameters

import { PlatformServiceName } from '@limetech/lime-web-components';

const navigator = platform.get(PlatformServiceName.Navigator);

// Results in /docs/api?version=latest#parameters
navigator.navigate({
    path: '/docs/api',
    query: { version: 'latest' },
    hash: '#parameters',
});

removeBlocker

removeBlocker(blocker: Blocker): void
Remove a previously registered navigation blocker

Always remove blockers in disconnectedCallback() to prevent memory leaks and unintended blocking behavior.

The blocker reference must be the exact same function instance that was passed to addBlocker.
Parameters
- blocker: Blocker
  The blocker function to remove
Returns void
Example: Remove a blocker
```
import { Blocker, PlatformServiceName } from '@limetech/lime-web-components';

const navigator = platform.get(PlatformServiceName.Navigator);

const blocker: Blocker = () => false;

navigator.addBlocker(blocker);

// The same function instance has to be passed back in
navigator.removeBlocker(blocker);
```

Interface Navigator

Example: Basic navigation

Example: Navigation with query parameters

Example: Advanced navigation with all options

Example: Listening to navigation events

Index

Methods

Methods

addBlocker

Parameters

Returns void

Note

Example: Basic unsaved changes blocker

Example: Asynchronous confirmation dialog

createUrl

Parameters

Returns URL

Note

Example: Inspect the parts of a generated URL

Example: Generate a link element

getLocation

Returns Location

Example: Read the current location

navigate

Parameters

Returns void

Emits

Example: Simple path navigation

Example: Navigation with query parameters

History Management

State Handling

Parameters

Returns void

Emits

Example: Update only query parameters (replaces current entry)

Example: Navigate with custom state

Example: Override the automatic push or replace choice

Example: Navigate with hash and query parameters

removeBlocker

Parameters

Returns void

Example: Remove a blocker

Settings

On This Page