We are focused on developing custom software solutions for different purposes. This template is the result of the learning curve we had developing many applications. We want to share it with the community - to help NiceGUI becomming bigger. A big thank you to @zauberzeug/niceGUI for this amazing framework.

A modern, component-based NiceGUI application boilerplate with a responsive sidebar, header wrapper, and modular architecture. Built with uv for fast dependency management and featuring smooth animations, optimized performance, and a clean UI.

• Responsive Collapsible Sidebar with smooth animations
• Modern Header with account dropdown menu
• Component-based Architecture for maintainable code
• Print System with Base64 support for documents/images
• Custom Styling with Google-inspired button

• Modular Component System - Each page is a separate component
• Service Layer - Helper functions organized in services directory
• Configuration-driven - Centralized config management
• Route Wrapper System - Consistent layout across all pages
• Asset Management - Organized CSS, images, and static files

• Logo Preloading - Prevents flickering on page loads
• Global CSS Injection - Optimized styling delivery
• Favicon Support - Professional branding
• Static File Serving - Efficient asset delivery

nicegui-base-main/ ├── main.py # Main application entry point ├── header.py # Header component with sidebar ├── footer.py # Footer component (optional) ├── pyproject.toml # UV/Python project configuration ├── uv.lock # UV lock file for reproducible builds ├── ico.ico # Application favicon ├── config.json # Application configuration │ ├── assets/ │ ├── css/ │ │ ├── global-css.css # Global application styles │ │ └── icons.css # Tabler icons CSS │ └── images/ │ ├── logo.png # Application logo │ ├── extension_icon.png │ └── salzit.png │ ├── components/ # Page components │ ├── dashboard_content.py │ ├── shipping_content.py │ ├── production_content.py │ ├── orders_content.py │ ├── pallets_content.py │ ├── packings_content.py │ ├── data_content.py │ ├── settings_content.py │ └── print_component.py # Special print functionality │ └── services/ # Helper functions and utilities ├── __init__.py └── helpers.py 

• Python 3.11+
• UV Package Manager

1. Clone the repository

   git clone "https://github.com/frycodelab/nicegui-component-based" cd nicegui-base-main

2. Install dependencies with UV

   uv sync

3. Create your configuration file

   { "appName": "Your App Name", "appVersion": "1.0.0", "appPort": 8080 }

4. Run the application

   uv run python main.py

The main application file sets up the core functionality:

• Base Layout Wrapper: with_base_layout decorator that applies consistent styling and layout
• Route Definitions: All application routes with their respective components
• Global Configurations: Colors, CSS injection, and asset management
• Logo Optimization: Global logo instance to prevent reloading

# Logo optimization with global instance logo_image = None def get_logo_image(): global logo_image if logo_image is None: logo_image = ui.image('assets/images/logo.png').style('width: 5rem; height: auto;') return logo_image

Features a sophisticated sidebar with smooth animations:

• Collapsible Sidebar with width transitions (300px ↔ 100px)
• Label Animations with fade-in/fade-out effects
• Active Route Highlighting with visual indicators
• Account Dropdown with modern styling

Animation System:

async def toggle_sidebar(): if app.storage.user['sidebar-collapsed']: # Expanding: Width first, then labels left_drawer.props("width=300") await ui.run_javascript('new Promise(resolve => setTimeout(resolve, 50))') for label in sidebar_labels: label.classes(remove='collapsed', add='expanded') else: # Collapsing: Labels first, then width for label in sidebar_labels: label.classes(remove='expanded', add='collapsed') await ui.run_javascript('new Promise(resolve => setTimeout(resolve, 50))') left_drawer.props("width=100")

Advanced printing functionality supporting various content types:

• Base64 Decoding for encoded content
• Non-blocking Print using invisible iframes
• Automatic Window Management

Comprehensive styling system featuring:

.account-dropdown { font-family: 'Roboto', sans-serif; min-width: 200px; background: #ffffff; border-radius: 12px; box-shadow: 0 6px 24px rgba(0, 0, 0, 0.12); padding: 24px 0 16px 0; }

.google-like-button { padding: 8px 30px !important; border-radius: 34px !important; font-weight: bold !important; transition: background-color 0.2s ease-in-out !important; }

.sidebar-label { transition: opacity 0.3s ease-in-out, transform 0.3s ease-in-out !important; transform-origin: left center; } .sidebar-label.collapsed { opacity: 0; transform: translateX(-10px); }

{ "appName": "Your Application Name", "appVersion": "1.0.0", "appPort": 8080 }

[project] name = "nicegui-component-based" version = "0.1.0" requires-python = ">=3.11" dependencies = [ "nicegui", "nicegui[highcharts]", "pyinstaller>=6.13.0", "pywebview>=5.4", ]

1. Create a new file in components/
2. Implement a content() function
3. Add route in main.py
4. Update sidebar navigation in header.py

Example Component:

# components/new_component.py from nicegui import ui def content() -> None: ui.label('New Component').style('font-size: 1.5rem;') # Your component content here

• Colors: Modify in main.py ui.colors() call
• CSS: Add custom styles to global-css.css
• Icons: Uses Tabler Icons via icons.css

Add new menu items in header.py:

with ui.link('', '/your-route').classes(f'w-full no-underline text-black {"bg-light-blue-3" if current_route.startswith("/your-route") else ""}'): with ui.row().classes('items-center mb-2 mt-2 cursor-pointer w-full no-wrap'): ui.icon('your_icon').classes('ml-5 text-2xl flex-shrink-0') your_label = ui.label('Your Page').classes('text-lg sidebar-label ml-3 flex-shrink-0') sidebar_labels.append(your_label)

uv run python main.py

ui.run(host='0.0.0.0', storage_secret="your-secret", title=appName, port=appPort, favicon='ico.ico', reconnect_timeout=20, reload=False)

ui.run(storage_secret="your-secret", title=appName, port=appPort, favicon='🧿', reload=False, native=True, window_size=(1600,900))

ui.run(storage_secret=os.environ['STORAGE_SECRET'], host=os.environ['HOST'], title=appName, port=appPort, favicon='ico.ico', reconnect_timeout=20, reload=False)

• For Docker adjust main.py and use:

   #For Docker ui.run(storage_secret=os.environ['STORAGE_SECRET'])

  Go one folder back in terminal where the docker-compose.yaml is located:

   cd .. docker compose up

Your container should build an image template:latest and run the container on http://localhost:8080.

python -m PyInstaller --name 'YourApp' --onedir main.py --add-data 'venv/Lib/site-packages/nicegui;nicegui' --noconfirm --clean

• Static File Serving: Efficient delivery via app.add_static_files('/assets', "assets")
• CSS Injection: Inline styles for optimal loading
• Icon Fonts: Tabler Icons for scalable iconography

The services/ directory contains reusable helper functions:

# services/helpers.py async def dummy_function(): return "Helper function called successfully!"

Import and use in components:

import services.helpers as helpers result = await helpers.dummy_function()

The print component supports Base64 encoded content:

# Generate a print URL import base64 content = "<h1>Hello World</h1>" encoded = base64.b64encode(content.encode()).decode() print_url = f"/print/{encoded}" # Navigate to print ui.navigate.to(print_url)

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

• NiceGUI - The amazing Python web framework
• UV - Fast Python package manager
• Quasar Framework - UI components underlying NiceGUI

If you find this boilerplate helpful, please ⭐ star the repository!

For questions and support, please open an issue on GitHub.

Happy coding with NiceGUI! 🚀

• @frycodelab