use_navigate

use_navigate is a hook that returns a function to trigger single page application (SPA) navigation within Deephaven. For declarative navigation, consider using link with the to prop instead.

Note

Deephaven and all custom components share the path. Avoid using routers, the path, path parameters, and navigation in shared components to prevent conflicts. Do not use the route segment /-/ in your application path as it is reserved for internal use by Deephaven.

Example

from deephaven import ui


@ui.component
def app():
    # Navigate to the settings page
    navigate = ui.use_navigate()
    return ui.action_button(
        "Go to settings", on_press=lambda: navigate("/settings")
    )


app = app()

Use use_navigate together with use_path and use_query_params to build a simple navigation system that updates the path and displays query parameters.

from deephaven import ui


@ui.component
def navigation_demo():
    path = ui.use_path()
    query_params = ui.use_query_params()
    navigate = ui.use_navigate()

    def go_dashboard():
        # Navigate to a page with a query parameter
        navigate("/dashboard", query_params={"welcome": "true"})

    def go_settings():
        # Use replace=False to push a new history entry instead of replacing the current one
        navigate("/settings", replace=False)

    def scroll_to_section():
        # Jump to a fragment on the current page
        navigate(fragment="section-2")

    def filter_by_tags():
        # Update query parameters on the current page
        navigate(query_params={"tag": ["python", "java"]})

    return ui.flex(
        ui.text(f"Current path: {path}"),
        ui.text(f"Query params: {query_params}"),
        ui.action_button("Dashboard", on_press=go_dashboard),
        ui.action_button("Settings (push)", on_press=go_settings),
        ui.action_button("Jump to section", on_press=scroll_to_section),
        ui.action_button("Filter by tags", on_press=filter_by_tags),
        direction="column",
    )


app = navigation_demo()

Recommendations

Prefer link with to for user-clickable navigation. Reserve use_navigate for programmatic navigation triggered by events or side effects.
Use replace=True (the default) when navigating in response to a state change to avoid polluting the browser history.
Pair with router and route to define the route structure that use_navigate targets.

API Reference

Get a function to navigate to a new URL within the widget's route space.

Returns: A navigate function navigate(path, query_params, fragment, replace) -> None

use_navigate

Example

Navigation Options

Recommendations

API Reference