verynicegui 1.0.5

A premium component-based SaaS framework built on top of NiceGUI

🌟 verynicegui

A premium, component-based SaaS boilerplate framework built on top of NiceGUI.

verynicegui empowers developers to focus entirely on building business logic and page content. It automates layout structures, dynamic navigation menus, session authentication, role-based access control (RBAC), theme switching, multi-keyword data tables, and seamless i18n localizations.

---

🚀 Key Features

• 🛡️ Out-of-the-Box Session Auth & RBAC: Session-based login/logout guards with category-based page access checks.
• 📱 Premium Responsive Layout (VeryNiceGUI / VeryNiceLayout): Complete SaaS layout including a Header, dynamic Left Navigation Drawer, Footer, and interactive Right Detail Drawer.
• 🌍 Zero-Flash Theme & i18n Switching: Anti-flash dynamic HTML theme classes and quick "TR / EN" segment button toggle in the drawer.
• 🏗️ One-Command CLI Scaffolding: Setup your entire project directory and files instantly using the built-in CLI.
• 📊 Enhanced Data Table (VeryNiceTable): Paging bounds (max_row), custom 12-column spans, row click triggers, and comma/space separated multi-keyword AND-logic search.
• 🎴 Justified Typography Cards (VeryNiceCard): Standalone stat cards or context manager wrapper cards with dynamic border strips and justified block text.
• 📈 Premium Analytics Charts (VeryNiceChart): High-performance charting supporting line, bar, pie, scatter, and area chart types using Apache ECharts or Highcharts engines, automatically styled with contrast coloring in dark mode.

---

📦 Installation

To install verynicegui in your environment, run the following command:

pip install verynicegui

(For local/editable development):

pip install -e . --break-system-packages

---

🏗️ Quick Project Scaffold (CLI)

Get a fully structured, modular SaaS project up and running in seconds. Open an empty folder in your terminal and run:

verynicegui-init

or alternatively:

python -m verynicegui

Generated Project Structure:

my_saas_app/
│
├── main.py             # App settings, Header, Footer, Drawer configuration & Launcher
├── translations.py     # Separate dictionary file for multi-language terms
├── assets/             # Holds static files (e.g. logos, graphics)
│   └── logo.svg        # Default premium SVG logo
├── pages/              # Directory for modular page layouts
│   ├── __init__.py     # Exports all pages
│   ├── home.py         # Home page module
│   └── sales.py        # Sales page module (featuring VeryNiceTable & VeryNiceChart)
└── data/
    └── users.json      # Built-in database file (automatically created on first run)

To run your application after scaffolding, execute:

python main.py

---

📐 12-Column Responsive Grid Layout

verynicegui uses a 12-column grid layout system to structure pages neatly and responsively.

All main components—VeryNiceCard, VeryNiceTable, and VeryNiceChart—include a column parameter which specifies how many columns (out of 12) the component should span.

For best results, wrap your components inside a ui.grid(columns=12) container:

with ui.grid(columns=12).classes("w-full gap-4"):
    # Spans 4 columns (1/3 of the row width)
    VeryNiceCard(title="Active Subscriptions", body="1,420", column=4)
    VeryNiceCard(title="Monthly Revenue", body="$42,500", column=4)
    VeryNiceCard(title="Churn Rate", body="1.8%", column=4)
    
    # Spans 12 columns (Full width of the row)
    VeryNiceTable(table_name="Active Customers", columns=cols, rows=data, column=12)

Common Span Values:

• column=12: Full-width span (100% of row width)
• column=6: Half-width span (50% of row width)
• column=4: One-third span (33.3% of row width)
• column=8: Two-thirds span (66.6% of row width)

---

🛠️ API & Component Reference

1. VeryNiceGUI (App Configuration)

Used in main.py to bootstrap the application drawer, header, footer, static assets, and localization parameters.

# main.py
import sys
# Alias the entrypoint namespace as 'main' to prevent duplicate execution during circular imports
sys.modules['main'] = sys.modules[__name__]

from verynicegui import VeryNiceGUI
from translations import TRANSLATIONS

app = VeryNiceGUI(
    title="My SaaS App",
    header={
        "logo": "assets/logo.svg",  # SVG/PNG file path or Material Icon name
        "title": "SaaSApp",
        "show_theme_toggle": True
    },
    left_drawer={
        "title": "Navigation Menu",
        "menu": [
            {"category": "home", "title": "Home", "icon": "home", "route": "/"},
            {
                "category": "sales", 
                "title": "Sales", 
                "icon": "payments",
                "subcategories": [
                    {"title": "Daily", "route": "/sales/daily", "icon": "today"},
                    {"title": "Monthly", "route": "/sales/monthly", "icon": "calendar_month"}
                ]
            }
        ]
    },
    footer={
        "left": "© 2026 SaaSApp Inc.",
        "middle": "All Rights Reserved",
        "right": "System Status: Online"
    },
    translations=TRANSLATIONS
)

import pages

if __name__ in {"__main__", "__mp_main__"}:
    app.run(port=8080)

---

2. @app.page (Route & Guard Decorator)

Registers routes and applies RBAC categories to restrict pages to authorized users.

# pages/home.py
from nicegui import ui
from verynicegui import get_current_user, tr
from main import app

# Restricts this page to users having the 'home' category permission
@app.page("/", title="Home Page", allowed_categories=["home"])
def home_page():
    user = get_current_user()
    display_name = user.get("display_name") if user else "Guest"
    
    ui.label(tr("welcome", "Welcome, {name}!").format(name=display_name))

---

3. VeryNiceCard (Justified Content Cards)

A premium card container. Can be instantiated on a single line or as a context manager block.

A) Single-line Statistic Card

from verynicegui import VeryNiceCard

VeryNiceCard(title="Total Revenue", body="$124,500", column=4)

B) Context Manager Block Card

from verynicegui import VeryNiceCard
from nicegui import ui

with VeryNiceCard(title="Important Announcement", column=12, color="var(--mn-brand)"):
    ui.label("This paragraph text inside the card is automatically justified (aligned left and right).")
    ui.button("Read More")

Parameters:

• title (str): Title text. Shows smaller and grey in stats mode, bold and primary in content mode.
• body (str, optional): Value string. Triggers immediate stats card formatting if provided.
• column (int, optional): Width span in 12-column grids (e.g. 4 spans 1/3 of the row).
• color (str, optional): Brand color for the decorative left border strip (e.g. "#3b82f6", "var(--mn-brand)").

---

4. VeryNiceTable (Advanced Paginated Grid)

Features scrollable headers, page pagination, multi-keyword search parsing, and custom action callbacks.

# pages/sales.py
from nicegui import ui
from verynicegui import VeryNiceTable, tr
from main import app

@app.page("/sales/daily", title="Daily Sales", allowed_categories=["sales"])
def daily_sales_page(drawer):
    transactions = [
        {"id": "#1001", "product": "Pro License", "amount": "99 USD", "desc": "Premium subscription key"},
        {"id": "#1002", "product": "Enterprise Setup", "amount": "1200 USD", "desc": "Custom server migration consulting"}
    ]

    with ui.grid(columns=12).classes("w-full gap-4"):
        VeryNiceTable(
            table_name="Transactions",
            columns=[
                {"name": "id", "label": "ID", "field": "id", "align": "left"},
                {"name": "product", "label": "Product", "field": "product", "align": "left"},
                {"name": "amount", "label": "Amount", "field": "amount", "align": "right"}
            ],
            rows=transactions,
            max_row=5,          # Maximum rows per page before paginating
            column=12,          # Span in the 12-column parent layout
            font_size="m",      # Options: 's', 'm', 'l'
            font_family="Outfit", # Options: 'Outfit', 'Inter'
            on_row_click=lambda row: drawer.toggle(row["desc"]) # Drawer action on row click
        )

🔍 Multi-Keyword Search AND Filter

The search box supports multiple keyword arguments separated by spaces ( ) or commas (,). For example, searching for Pro Premium matches records containing both "Pro" and "Premium".

---

5. VeryNiceChart (SaaS Analytics Chart)

Wraps charting engines inside styled containers that coordinate with page layouts and color themes.

A) Side-by-Side ECharts Dashboard

from nicegui import ui
from verynicegui import VeryNiceChart
from main import app

@app.page("/sales/monthly", title="Monthly Performance", allowed_categories=["sales"])
def monthly_sales_page():
    months = ["Jan", "Feb", "Mar", "Apr", "May", "Jun"]
    revenue = [12000, 15000, 18000, 14000, 22000, 26000]
    conversion = [2.1, 2.5, 2.8, 2.4, 3.2, 3.5]
    
    with ui.grid(columns=12).classes("w-full gap-4"):
        # Monthly Revenue Line Chart (Spans half of the grid)
        VeryNiceChart(
            title="Monthly Revenue (USD)",
            type="line",
            x_data=months,
            y_data=revenue,
            series_name="Revenue",
            column=6
        )
        
        # Monthly Conversion Rate Bar Chart (Spans other half)
        VeryNiceChart(
            title="Conversion Rate (%)",
            type="bar",
            x_data=months,
            y_data=conversion,
            series_name="Conversion %",
            column=6
        )

B) Custom Advanced Configuration (Apache ECharts)

from verynicegui import VeryNiceChart

custom_opts = {
    "tooltip": {"trigger": "item"},
    "series": [{
        "name": "Traffic Sources",
        "type": "pie",
        "radius": ["40%", "70%"], # Donut chart
        "data": [
            {"value": 1048, "name": "Search Engine"},
            {"value": 735, "name": "Direct"},
            {"value": 580, "name": "Email"}
        ]
    }]
}

VeryNiceChart(
    title="Traffic Overview",
    options=custom_opts,
    column=12
)

Parameters:

• options (dict, optional): Complete dictionary configuration for the underlying chart engine. If provided, x_data and y_data helpers are ignored.
• column (int, optional): Width span in the 12-column grid layout (1-12 span).
• engine (str, default 'echart'): Underlying chart library. Supports:
  • 'echart': Uses Apache ECharts (fully open source, recommended).
  • 'highchart': Uses Highcharts (requires a commercial license).
• type (str, default 'line'): Easy helper type option. Supports:
  • 'line': Smooth line chart.
  • 'bar': standard bar columns.
  • 'pie': standard pie chart with flat labels and theme text colors.
  • 'scatter': Scatter plot markers.
  • 'area': Smooth line chart filled with bottom gradient shading.
• title (str, optional): Bold card header title displayed above the chart canvas.
• height (str, default '350px'): Height specification in CSS dimensions.
• x_data (list, optional): List of X-axis categories.
• y_data (list, optional): List of Y-axis numeric values.
• series_name (str, default 'Data'): Label for the default data series.

---

6. RightDrawer (Details sidebar)

To instantiate the interactive right drawer, declare a parameter named drawer or right_drawer in your page function. The decorator will automatically inject the drawer.

# drawer control commands:
drawer.open("Content String or callback")
drawer.close()
drawer.toggle("Details info here...") # Toggles open if closed, or updates current drawer content

---

🌍 Localization & Multi-Language (i18n)

Define translation mappings in translations.py and supply them to VeryNiceGUI.

translations.py Schema:

TRANSLATIONS = {
    "tr": {
        "welcome": "Hoş geldiniz, {name}! 👋",
        "home_title": "Ana Sayfa",
        "btn_save": "Kaydet"
    },
    "en": {
        "welcome": "Welcome, {name}! 👋",
        "home_title": "Home Page",
        "btn_save": "Save"
    }
}

Usage:

Use the tr helper function inside pages to fetch translations for the user's active language choice.

from verynicegui import tr

# Simple translate
ui.label(tr("btn_save", "Save"))

# Formatted dynamic translate
ui.label(tr("welcome", "Welcome, {name}!").format(name=display_name))

---

🔑 Authentication Database (data/users.json)

On the first application launch, the directory data/ and users.json are created automatically. It contains default accounts:

• Admin (username: admin, password: admin123) -> Full access to all categories and /admin user management panels.
• Custom accounts can be registered and configured with page access permissions directly via the Admin panel.

---

🎨 Theme & Styles Override

Style overrides and color schemas are defined inside CSS variables in verynicegui/layout.py:

• --mn-bg: Master app background color.
• --mn-header-bg: Header navbar color.
• --mn-drawer-bg: Navigation sidebar color.
• --mn-card-bg: Card container background.
• --mn-brand: Brand indicator color (defaults to indigo purple).