Skip to content

AppShell

Bases: App

A top-level application window with built-in navigation.

AppShell extends App and wires together a Toolbar, SideNav, and PageStack into the common toolbar + sidebar + content layout. Each component is optional and exposed as a property for customization.

Example 
import bootstack as bs

shell = bs.AppShell(title='My App', size=(1000, 650))

home = shell.add_page('home', text='Home', icon='house')
bs.Label(home, text='Welcome!').pack(padx=20, pady=20)

docs = shell.add_page('docs', text='Documents', icon='file-earmark-text')
bs.Label(docs, text='Your documents.').pack(padx=20, pady=20)

shell.mainloop()

toolbar property 

toolbar: Toolbar | None

The Toolbar widget, or None if show_toolbar=False.

nav property 

nav: SideNav | None

The SideNav widget, or None if show_nav=False.

pages property 

pages: PageStack

The PageStack widget (always present).

current_page property 

current_page: str | None

The key of the currently displayed page, or None.

__init__ 

__init__(
    title: str = "",
    theme: str | None = None,
    size: tuple[int, int] | None = None,
    position: tuple[int, int] | None = None,
    minsize: tuple[int, int] | None = None,
    maxsize: tuple[int, int] | None = None,
    resizable: tuple[bool, bool] | None = None,
    frameless: bool = False,
    show_toolbar: bool = True,
    show_window_controls: bool = False,
    draggable: bool = False,
    toolbar_density: Literal[
        "default", "compact"
    ] = "default",
    show_nav: bool = True,
    nav_display_mode: Literal[
        "expanded", "compact", "minimal"
    ] = "expanded",
    nav_accent: str = "primary",
    **kwargs: Unpack[AppShellKwargs],
)

Initialize an AppShell.

Parameters:

Name Type Description Default
title str

Title displayed in the toolbar and window title bar.

 ''
theme str | None

Theme name. If None, uses the default theme.

 None
size tuple[int, int] | None

Initial window size as (width, height).

 None
position tuple[int, int] | None

Initial window position as (x, y).

 None
minsize tuple[int, int] | None

Minimum window size as (width, height).

 None
maxsize tuple[int, int] | None

Maximum window size as (width, height).

 None
resizable tuple[bool, bool] | None

Whether the window is resizable as (width, height).

 None
frameless bool

If True, remove OS window chrome (title bar, borders) and rely on the toolbar for window controls and dragging. Automatically enables show_window_controls and draggable when True. Default False.

 False
show_toolbar bool

Include the toolbar at the top. Default True.

 True
show_window_controls bool

Show minimize/maximize/close buttons in the toolbar. Default False.

 False
draggable bool

Enable window dragging via the toolbar. Default False.

 False
toolbar_density Literal['default', 'compact']

Toolbar button density ('default' or 'compact').

 'default'
show_nav bool

Include the sidebar navigation. Default True.

 True
nav_display_mode Literal['expanded', 'compact', 'minimal']

Initial SideNav display mode ('expanded', 'compact', or 'minimal'). Default 'expanded'.

 'expanded'
nav_accent str

Accent color for navigation selection. Default 'primary'.

 'primary'
**kwargs Unpack[AppShellKwargs]

Additional arguments passed to App.

 {}

add_page 

add_page(
    key: str,
    text: str = "",
    icon: str | dict = None,
    page=None,
    group: str = None,
    is_footer: bool = False,
    scrollable: bool = False,
    **nav_kwargs,
)

Add a navigation item and its corresponding page in one call.

Parameters:

Name Type Description Default
key str

Unique identifier for both the nav item and the page.

 required
text str

Display text for the nav item.

 ''
icon str | dict

Icon name or configuration for the nav item.

 None
page

An existing widget to use as the page. If None, a Frame is created automatically.

 None
group str

Key of the nav group to add this item to.

 None
is_footer bool

If True, add the nav item to the footer section.

 False
scrollable bool

If True, the page is wrapped in a ScrollView with vertical scrolling. The returned widget is the ScrollView content frame, so widgets can be packed into it as usual.

 False
**nav_kwargs

Additional arguments passed to the nav item.

 {}

Returns:

Type Description

The page widget (passed or auto-created Frame). When

scrollable=True, returns the ScrollView so that children

are packed into the scrollable area.

Raises:

Type Description
RuntimeError

If show_nav=False was set. Use shell.pages.add() directly instead.

add_group 

add_group(
    key: str,
    text: str = "",
    icon: str | dict = None,
    is_expanded: bool = False,
    **kwargs,
)

Add a navigation group.

Passthrough to nav.add_group().

Parameters:

Name Type Description Default
key str

Unique identifier for the group.

 required
text str

Display text.

 ''
icon str | dict

Icon name or configuration.

 None
is_expanded bool

Initial expansion state.

 False
**kwargs

Additional arguments passed to SideNavGroup.

 {}

Returns:

Name Type Description
SideNavGroup

The created group.

add_header 

add_header(text: str, **kwargs)

Add a section header to the navigation.

Passthrough to nav.add_header().

Parameters:

Name Type Description Default
text str

Header text.

 required
**kwargs

Additional arguments passed to SideNavHeader.

 {}

Returns:

Name Type Description
SideNavHeader

The created header.

add_separator 

add_separator(**kwargs)

Add a separator to the navigation.

Passthrough to nav.add_separator().

Parameters:

Name Type Description Default
**kwargs

Additional arguments passed to SideNavSeparator.

 {}

Returns:

Name Type Description
SideNavSeparator

The created separator.

navigate 

navigate(key: str, data: dict = None)

Programmatic navigation: updates nav selection and navigates PageStack.

Parameters:

Name Type Description Default
key str

The page key to navigate to.

 required
data dict

Optional data to pass to the page.

 None

select 

select(key: str, data: dict = None)

Alias for navigate().

Parameters:

Name Type Description Default
key str

The page key to navigate to.

 required
data dict

Optional data to pass to the page.

 None

on_page_changed 

on_page_changed(callback: Callable) -> str

Bind to page change events on the PageStack.

Parameters:

Name Type Description Default
callback Callable

Function to call when the page changes.

 required

Returns:

Type Description
str

Binding identifier for use with off_page_changed().

off_page_changed 

off_page_changed(bind_id: str = None)

Unbind from page change events.

Parameters:

Name Type Description Default
bind_id str

The binding identifier returned by on_page_changed().

 None