router.sub_pages Not Supported – Difficult to Implement Nested Page Layouts

[BakaDream]

Currently, NiceGUI does not support router.sub_pages, which makes it inconvenient to implement nested page layouts or multi-page dashboards with consistent sidebar and top navigation.

For example, in a typical admin system setup:

from nicegui import ui

router = APIRouter(prefix="/dashboard", tags=["dashboard"])

def home_page():
    with ui.card().tight().classes('m-6 p-6 shadow-lg'):
        ui.label('Home Page').classes('text-3xl font-bold mb-2 text-gray-800')
        ui.label('Welcome to the admin system!').classes('text-gray-700 mb-4')
        ui.button('Go to Settings', on_click=lambda: ui.navigate.to('/dashboard/settings'))

def settings_page():
    with ui.card().tight().classes('m-6 p-6 shadow-lg'):
        ui.label('Settings').classes('text-3xl font-bold mb-2 text-gray-800')
        ui.label('Configure your system here.').classes('text-gray-700 mb-4')
        ui.button('Back to Home', on_click=lambda: ui.navigate.to('/dashboard'))

@router.page('/')
@router.page('/{_:path}')
def index():
    with ui.column().classes('h-screen w-screen'):
        # Top navbar and sidebar are static
        top_navbar()
        with ui.row().classes('flex-1 w-full'):
            sidebar_menu()
            # Main content area
            with ui.column().classes('flex-1 h-full overflow-auto border-l border-gray-300'):
                ui.sub_pages({
                    '/dashboard': home_page,
                    '/dashboard/settings': settings_page
                }).classes('h-full')

In this layout:

• top_navbar() and sidebar_menu() are shared across pages.
• ui.sub_pages is used to dynamically render nested content.

Problems:

1. NiceGUI currently does not support router.sub_pages.
2. Developers cannot easily implement a multi-page dashboard with a shared layout.
3. Workarounds require duplicating layout code across multiple routes, reducing maintainability.

Request / Feature Suggestion:

• Support router.sub_pages or a similar mechanism to allow nested pages with shared layouts.
• Allow dynamic switching of sub-pages while keeping sidebars, navbars, and other common elements intact.
• Ideally, provide a declarative API for sub-page registration similar to Vue’s router or React Router.

Example Expected Behavior:
Navigating to /dashboard/settings should render the settings_page inside the main content area without duplicating the sidebar and navbar code.

This feature would greatly simplify building admin dashboards and multi-page applications in NiceGUI.

[BakaDream]

I tried using ui.sub_pages with the root_path parameter, e.g.:

ui.sub_pages({
    '/': home_page,
    '/settings': settings_page
}, root_path='/dashboard').classes('h-full')

While this works, it requires manually setting root_path. If someone forgets to update it when changing routes, it can easily lead to bugs or unexpected behavior. It would be safer if nested page routing could automatically handle the base path, reducing the chance of errors.

[rodja]

For me it works when applying the modularization example:

from nicegui import APIRouter, app, ui

router = APIRouter(prefix='/dashboard', tags=['dashboard'])

def home_page():
    with ui.card().tight().classes('m-6 p-6 shadow-lg'):
        ui.label('Home Page').classes('text-3xl font-bold mb-2 text-gray-800')
        ui.label('Welcome to the admin system!').classes('text-gray-700 mb-4')
        ui.button('Go to Settings', on_click=lambda: ui.navigate.to('/dashboard/settings'))

def settings_page():
    with ui.card().tight().classes('m-6 p-6 shadow-lg'):
        ui.label('Settings').classes('text-3xl font-bold mb-2 text-gray-800')
        ui.label('Configure your system here.').classes('text-gray-700 mb-4')
        ui.button('Back to Home', on_click=lambda: ui.navigate.to('/dashboard'))

@router.page('/')
@router.page('/{_:path}')
def index():
    ui.label('Hello World')
    ui.sub_pages({
        '/dashboard': home_page,
        '/dashboard/settings': settings_page
    }).classes('h-full')

app.include_router(router)

ui.run()

[BakaDream]

Thanks for sharing the modularization example! 🙌
It indeed works, but my main concern is about maintainability and potential pitfalls:

• In the current approach, we have to manually repeat the full path (/dashboard, /dashboard/settings) inside ui.sub_pages.
• If the router prefix changes (e.g., from /dashboard to /admin), we also need to manually update all the sub-page paths. It’s easy to forget, which could introduce subtle bugs.
• Ideally, the router (or ui.sub_pages) should be able to automatically prepend the router prefix so that we only declare relative sub-routes ('/', '/settings') once.

That way, the layout code would be more resilient and less error-prone, especially in larger applications with many nested routes.

Do you think it would make sense to extend ui.sub_pages (or router.sub_pages) to handle the base path automatically, similar to how Vue Router or React Router manage nested routes?

[rodja]

Ah sorry, I missed the optimization by using root_path:

ui.sub_pages({
    '/': home_page,
    '/settings': settings_page
}, root_path=router.prefix)