Dars Framework Documentation

Welcome to the official Dars Framework documentation. Here you will find detailed guides and references to help you build modern web applications with Python.

Main Guides

• Installing Dars
• Getting Started with Dars
• CLI Usage and Commands
• Dars Project Configuration
• Environment Management
• App class
• SPA Routing
• SSR Routing
• Backend HTTP Utilities & API Communication
• State Management
• Components
• Styling System
• Animation System
• Custom Components
• Hooks
• Operations
• Key Events System
• Event Handling
• Exporters
• Scripts System
• CLI Usage and Commands

Installation Guide - Dars Framework

Quick Installation

To install Dars, simply use pip:

pip install dars-framework

This will install Dars and all its dependencies automatically.

VS Code Extension

You can install the official Dars Framework VS Code extension to have the dars dev tools.

• VS Code Marketplace : https://marketplace.visualstudio.com/items?itemName=ZtaMDev.dars-framework
• Open VSX : https://open-vsx.org/extension/ztamdev/dars-framework

CLI Usage

• Dars CLI

Once installed, the dars command will be available in your terminal. You can use it to:

Export Applications

dars export my_app.py --format html --output ./my_app_web

Preview Applications

dars preview ./my_app_web

Initialize a New Project

# Basic project with Hello World
dars init my_new_project

# Project with a specific template
dars init my_project -t basic/Forms

View Application Information

dars info my_app.py

View Supported Formats

dars formats

Post-Installation Verification

To verify that Dars has been installed correctly, open your terminal and run:

dars --help

You should see the help for the dars command, indicating that the installation was successful.

First Steps After Installation

1. Create Your First Application (my_first_app.py)

from dars.core.app import App
from dars.components.basic.text import Text
from dars.components.basic.container import Container

app = App(title="My First App")
container = Container(style={'padding': '20px'}) # Use ' to escape quotes
text = Text(text="Hello Dars!", style={'font-size': '24px'}) # Use ' to escape quotes

container.add_child(text)
app.set_root(container)

if __name__ == "__main__":
    app.rTimeCompile()

2. Export the Application

Save the code above as my_first_app.py and then run:

dars export my_first_app.py --format html --output ./my_app

3. Preview

dars preview ./my_app

Useful Commands

# General help
dars --help

# Application information
dars info my_app.py

# Available formats
dars formats

# Preview application
dars preview ./output_directory

Post-Installation Checklist

• [x] Python 3.8+ installed
• [x] Dars Framework installed via pip install dars-framework
• [x] CLI dars works correctly ( dars --help )
• [x] Basic test run successfully
• [x] Example exported and previewed correctly
• [x] Documentation reviewed

Congratulations! Dars is ready to use.

Desktop (BETA)

You can build native desktop apps from Dars projects. This capability is in BETA and is not recommended for production yet, but it is usable for testing.

Quickstart

# Scaffold or update a desktop-capable project
dars init --type desktop
# or
dars init --update

# Verify optional tooling (Node/Bun and packager)
dars doctor --all --yes

# Ensure your config sets the desktop format and target
# dars.config.json
{
  "entry": "main.py",
  "format": "desktop",
  "outdir": "dist",
  "targetPlatform": "auto"
}

# Build desktop artifacts
dars build

Notes: - Desktop support is under active development; configuration keys and defaults may change. - Some platform targets (like macOS) require building on that OS for signing.

Getting Started with Dars

Welcome to Dars, a modern Python framework for building web applications with reusable UI components.

VS Code Extension

There is an official Dars Framework extension for VS Code to have the dars dev tools.

• VS Code Marketplace : https://marketplace.visualstudio.com/items?itemName=ZtaMDev.dars-framework
• Open VSX : https://open-vsx.org/extension/ztamdev/dars-framework

Quick Start

1. Install Dars
   See INSTALL section for installation instructions.

2. Explore Components
   Discover all available UI components in components.md .

3. Command-Line Usage
   Find CLI commands, options, and workflows in cli.md .

4. App Class Learn how to create an app class in App Documentation .

5. Component Search and Modification All components in Dars now support a powerful search and modification system:

from dars.all import *

app = App(title="Hello World", theme="dark")

# 1. Define State
state = State("app", title_val="Simple Counter", count=0)

# 2. Define Route
@route("/")
def index(): 
    return Page(
        # 3. Use useValue for app text
        Text(
            text=useValue("app.title_val"),
            style="fs-[33px] text-black font-bold mb-[5x] ",
        ),

        # 4. Display reactive count
        Text(
            text=useDynamic("app.count"),
            style="fs-[48px] mt-5 mb-[12px]"
        ),
        # 5. Interactive Button
        Button(
            text="+1",
            on_click=(
                state.count.increment(1)
            ),
            style="bg-[#3498db] text-white p-[15px] px-[30px] rounded-[8px] border-none cursor-pointer fs-[18px]",
        ),

        # 6. Interactive Button
        Button(
            text="-1",
            on_click=(
                state.count.decrement(1)
            ),
            style="bg-[#3498db] text-white p-[15px] px-[30px] rounded-[8px] border-none cursor-pointer fs-[18px] mt-[5px]",
        ),
        # 7. Interactive Button
        Button(
            text="Reset",
            on_click=(
                state.reset()
            ),
            style="bg-[#3498db] text-white p-[15px] px-[30px] rounded-[8px] border-none cursor-pointer fs-[18px] mt-[5px]",
        ),
        style="flex flex-col items-center justify-center h-[100vh] ffam-[Arial] bg-[#f0f2f5]",

    ) 

# 8. Add page
app.add_page("index", index(), title="index")

# 9. Run app with preview
if __name__ == "__main__":
    app.rTimeCompile()

7. Adding Custom File Types

app.rTimeCompile().add_file_types = ".js,.css"

• Include any extension your project uses beyond default Python files.

Need More Help?

• For advanced topics, see the full documentation and examples in the referenced files above.
• If you have questions or need support, check the official repository or community channels.

Start building with Dars...

Dars CLI Reference

The Dars Command Line Interface (CLI) lets you manage your projects, export apps, and preview results quickly from the terminal.

How to Use the CLI

Open your terminal in your project directory and use any of the following commands:

# Show information about your app
 dars info my_app.py

# Export to different formats (web)
 dars export my_app.py --format html --output ./output
 # Skip default Python minifier for this run (does not affect viteMinify)
 dars export my_app.py --format html --output ./output --no-minify

# List supported export formats
 dars formats

# Initialize a new project (Default is SPA)
 dars init my_new_project

# Initialize a Full-Stack SSR project
 dars init my_new_project --type ssr

# Initialize a project with a specific template
 dars init my_new_project -t demo/complete_app

# Preview an exported app
 dars preview ./output_directory

# Build using project config (dars.config.json)
 dars build
 # Build desktop (BETA) when format is desktop in config
 dars build
 # Build without the default Python minifier
 dars build --no-minify

# Help
 dars --help

# Version
 dars -v

Main Commands Table

Using Official Templates

Dars provides official templates to help you start new projects quickly. Templates include ready-to-use apps for forms, layouts, dashboards, multipage, and more.

How to Use a Template

1. Initialize a new project with a template:

   dars init my_new_project -t basic/HelloWorld
   # ...and more (see below)
   

You can see the templates available with

dars init --list-templates
dars init  -L

2. Export the template to HTML/CSS/JS:

   dars export main.py --format html --output ./hello_output
   dars export main.py --format html --output ./dashboard_output
   # ...etc
   

3. Preview the exported app:

   dars preview ./hello_output
   

Tips CLI

• Use dars --help for a full list of commands and options.
• You can preview apps either live (with app.rTimeCompile() ) or from exported files with dars preview .
• Templates are available for quick project setup: use dars init my_project -t <template> .

Desktop (BETA) CLI

• Mark your project with "format": "desktop" in dars.config.json .
• Use dars init --type desktop (or --update ) to scaffold backend files.
• Run dars doctor --all --yes to set up optional tooling.
• Build with dars build . This feature is in BETA: suitable for testing, not yet for production.

Minification labels in output

• Applying minification (default): default Python-side minifier is active.
• Applying minification (vite): Vite/esbuild minification is active (JS/CSS) and default is disabled.
• Applying minification (default + vite): both are active.

For more, see the Getting Started guide and the main documentation index.

SSR Workflow (Full-Stack)

When working with SSR ( dars init --type ssr ), the workflow involves two processes:

1. Frontend ( dars dev ) : Runs the Dars preview server on port 8000 using app.rTimeCompile() .
2. Backend ( dars dev --backend ) : Runs the FastAPI SSR backend on port 3000 using backendEntry from dars.config.json .

Common Commands:

Note: For production, you only need to run the backend (which serves the built assets).

Dars Project Configuration

The file (dars.config.json) configures how Dars exports and builds your project. It is created by dars init <name> for new projects and can be merged/updated in existing projects with dars init --update .

Example

{
  "entry": "main.py",
  "format": "html",
  "outdir": "dist",
  "publicDir": null,
  "include": [],
  "exclude": ["**/__pycache__", ".git", ".venv", "node_modules"],
  "bundle": false,
  "defaultMinify": true,
  "viteMinify": true,
  "markdownHighlight": true,
  "markdownHighlightTheme": "auto",
  "utility_styles": {},
  "backendEntry": "backend.api:app"
}

Fields

• entry Python entry file for your app. Used by dars build and by dars export config .

• format Export format. Supported: html and desktop (BETA). When set to desktop , the build command will produce native desktop artifacts.

• outdir Directory where the exported files are written.

• publicDir Directory whose contents are copied as-is into the output (e.g. public/ or assets/ ). If null , Dars will try to autodetect common locations.

• include / exclude Simple filters (by substring) applied when copying from publicDir .

• bundle Reserved for future use. Current exporters already produce a bundled output.

• defaultMinify Toggle the built-in Python minifier (safe and conservative). Controls HTML minification and provides JS/CSS fallback when advanced tools are unavailable.

  • true (default): run the default Python-side minifier.
  • false : skip the default minifier. You can still use Vite/esbuild via viteMinify .

• viteMinify Toggle the advanced JS minifier.

  • true (default): prefer the advanced minifier; fall back to the secondary minifier; if neither is available, a conservative built-in fallback is used.
  • false : skip the advanced minifier and use the secondary minifier directly; fall back to the conservative built-in if not available.

• utility_styles Dictionary defining custom utility classes. Keys are class names, values are lists of utility strings or raw CSS properties. Example: "btn-primary": ["bg-blue-500", "text-white"]

• markdownHighlight Auto-inject a client-side syntax highlighter for fenced code blocks in Markdown.

  • true (default): injects Prism.js assets once per page and highlights pre code blocks.
  • false : no assets injected; you can include your own highlighter or none at all.

• backendEntry Python import path for your FastAPI/SSR backend application (e.g. "backend.api:app" ).

  • Used by tools like dars dev --backend to start the backend server.
  • When your app defines routes with RouteType.SSR , dars config validate will require this field to be present.

Desktop-specific (BETA)

• targetPlatform Desktop build target. Only effective when format is desktop .
  • Values: auto (default), windows , linux , macos .
  • Note: macOS targets must be built on macOS for signing.

Desktop export is BETA: suitable for testing, not recommended for production yet. Configuration keys and defaults may change.

Behavior and defaults

• dars init --update merges your existing config with Dars defaults and writes the result back, adding any new keys (like defaultMinify , viteMinify ) without removing your current settings.
• During dars export and dars build , Dars reads this file and configures the minification pipeline accordingly.
• If advanced minifiers are not available, builds still complete with a conservative fallback. On dars build , a small notice may appear indicating that a less powerful minifier was used.
• You can force-skip the default Python minifier per run with --no-minify (does not affect viteMinify ).

Tips

• To add or refresh the config in an existing project:

  dars init --update
  

• To review optional tooling that can enhance bundling/minification, run:

  dars doctor
  

• If you want to force using only the secondary minifier, set "viteMinify": false .

  • To disable the default minifier by config, set "defaultMinify": false ; to disable it per-run use --no-minify .

Environment Management (DarsEnv)

Dars provides a simple, built-in way to detect the current running environment (Development vs Production) through the DarsEnv class.

Why use DarsEnv?

It is common to have logic that should only run during development (like showing debug tools, detailed logs, or specific navigation links) or only in production (like analytics scripts).

DarsEnv Class

The DarsEnv class is available directly from dars.env :

from dars.env import DarsEnv

Properties

DarsEnv.dev

A boolean property that indicates if the application is running in development mode.

• Returns True : When running via dars dev (where bundling is disabled by default).
• Returns False : When running via dars build or dars export (production builds).

Examples

Conditional Rendering

You can use DarsEnv.dev to conditionally render components:

from dars.all import *
from dars.env import DarsEnv

def MyPage():
    return Page(
        Container(
            Text("Welcome to My App"),

            # This link only appears in development
            Link("/debug-dashboard", "Debug Tools") if DarsEnv.dev else None,

            # Different footer for environments
            Text("Dev Mode: Active" if DarsEnv.dev else "Production Build")
        )
    )

Conditional Configuration

You can also use it to toggle configuration values:

api_url = "http://localhost:3000" if DarsEnv.dev else "https://api.myapp.com"

Note : DarsEnv is initialized automatically by the Dars CLI tools. You do not need to configure it manually.

App Class and PWA Features in Dars Framework

Overview

The App class is the core of any Dars Framework application. It represents the complete application and manages all configuration, components, pages, and functionalities, including Progressive Web App (PWA) support.

Basic Structure

class App:
    def __init__(
        self, 
        title: str = "Dars App",
        description: str = "",
        author: str = "",
        keywords: List[str] = None,
        language: str = "en",
        favicon: str = "",
        icon: str = "",
        apple_touch_icon: str = "",
        manifest: str = "",
        theme_color: str = "#000000",
        background_color: str = "#ffffff",
        service_worker_path: str = "",
        service_worker_enabled: bool = False,
        **config
    ):

Compile-Time Component Manipulation (App.create / App.delete)

Dars lets you modify the component tree before export or preview. Use these methods on App to insert or remove components safely at compile time.

App.create(target, root=None, on_top_of=None, on_bottom_of=None)

• Purpose : Insert a component into the tree.
• target can be:
  • A component instance (e.g., Button("OK", id="ok") ).
  • A callable that returns an instance (called lazily).
  • A str id of an existing component in the app tree to move it.
• root : Where to insert. Accepts:
  • A component instance.
  • A component id ( str ).
  • A page name ( str ) in multipage apps.
• on_top_of / on_bottom_of : Reference sibling inside root to place the new node before/after. Can be an id ( str ) or a component instance found within root (deep search). If neither is provided, it appends to root .
• Works with both single-page ( app.root ) and multipage ( app.add_page ) setups.
• If anything can’t be resolved, it fails gracefully without crashing.

Examples

from dars.all import *

app = App(title="Compile-time create/delete")

# Single-page usage
root = Container(Text("A" , id="a"), Text("C", id="c"), id="root")
app.set_root(root)

# Insert new Text before id="c"
app.create(Text("B", id="b"), root="root", on_top_of="c")

# Move existing component by id to bottom
app.create("a", root="root", on_bottom_of="c")

# Multipage usage (root by page name)
home = Page(Container(Text("Home"), id="home_root"))
app.add_page(name="home", root=home, index=True)
app.create(Text("Welcome", id="welcome"), root="home", on_bottom_of="home_root")

App.delete(id)

• Purpose : Remove a component from the tree by its id .
• If the id does not exist, it becomes a no-op (safe warning behavior).

# Remove a component by id before export/preview
app.delete("b")

These operations run before export and affect the generated HTML/VDOM. For dynamic changes at runtime in the browser, see the runtime APIs in the Components documentation.

Global Styles Management

Enhanced add_global_style() Method

The App class now includes an enhanced add_global_style() method that supports both inline style definitions and external CSS file imports.

Usage Examples

1. Inline Style Definition (Traditional)

app.add_global_style(
    selector=".my-button",
    styles={
        "background-color": "#4CAF50",
        "color": "white",
        "padding": "10px 20px",
        "border-radius": "5px"
    }
)

2. External CSS File Import (New in v1.1.2)

app.add_global_style(file_path="styles.css")

3. Combined Usage

# Add inline styles
app.add_global_style(
    selector=".primary-btn",
    styles={
        "background-color": "#007bff",
        "color": "white"
    }
)

# Import external CSS file
app.add_global_style(file_path="components.css")

Practical Example with External CSS

main.py:

from dars.all import *

app = App(title="Dars Styling Test")

index = Page(
    Container(
        Button("Styled Button", class_name="button-styling-test"),
        id="page_sub_container"
    )
)

app.add_page(name="index", root=index, title="index", index=True)
app.add_global_style(file_path="styles.css")

if __name__ == "__main__":
    app.rTimeCompile(add_file_types=".py, .css")

styles.css:

.button-styling-test {
    background-color: rgb(51, 255, 0);
    padding: 15px 30px;
    border-radius: 8px;
    border: none;
    font-weight: bold;
    cursor: pointer;
}

.button-styling-test:hover {
    background-color: rgb(30, 200, 0);
    transform: scale(1.05);
}

#page_sub_container {
    padding: 20px;
    background-color: #f5f5f5;
    min-height: 100vh;
}

Hot Reload for CSS Files

When using app.rTimeCompile() with the add_file_types=".css" parameter, the development server automatically watches for changes in CSS files and reloads the application when modifications are detected.

# Watch for both Python and CSS file changes
app.rTimeCompile(add_file_types=".py, .css")

# Or watch for CSS files only
app.rTimeCompile(add_file_types=".css")

Benefits of External CSS Import

1. Separation of Concerns : Keep styles separate from application logic
2. Better Organization : Maintain complex stylesheets in dedicated files
3. Team Collaboration : Designers and developers can work simultaneously
4. CSS Preprocessors : Use SASS, LESS, or other preprocessors
5. Performance : Browser caching for external CSS files

Backward Compatibility

The enhanced method maintains full backward compatibility - existing code using add_global_style(selector, styles) will continue to work without modification.

PWA Configuration Properties

The App class includes these PWA-specific properties:

# Icons and visual resources
self.favicon = favicon  # Path to traditional favicon
self.icon = icon  # Main icon for PWA (multiple sizes)
self.apple_touch_icon = apple_touch_icon  # Icon for Apple devices
self.manifest = manifest  # Path to manifest.json file

# Colors and theme
self.theme_color = theme_color  # Theme color (#RRGGBB)
self.background_color = background_color  # Background color for splash screens

# Service Worker
self.service_worker_path = service_worker_path  # Path to service worker file
self.service_worker_enabled = service_worker_enabled  # Enable/disable

# Additional PWA configuration
self.pwa_enabled = config.get('pwa_enabled', False)
self.pwa_name = config.get('pwa_name', title)
self.pwa_short_name = config.get('pwa_short_name', title[:12])
self.pwa_display = config.get('pwa_display', 'standalone')
self.pwa_orientation = config.get('pwa_orientation', 'portrait')

Meta Tag Generation for PWA

The App class provides methods to generate PWA meta tags:

def get_meta_tags(self) -> Dict[str, str]:
    """Returns all meta tags as a dictionary"""
    meta_tags = {}

    # Viewport configured for responsiveness
    viewport_parts = []
    for key, value in self.config['viewport'].items():
        if key == 'initial_scale':
            viewport_parts.append(f'initial-scale={value}')
        elif key == 'user_scalable':
            viewport_parts.append(f'user-scalable={value}')
        else:
            viewport_parts.append(f'{key.replace("_", "-")}={value}')
    meta_tags['viewport'] = ', '.join(viewport_parts)

    # Specific tags for PWA
    meta_tags['theme-color'] = self.theme_color
    if self.pwa_enabled:
        meta_tags['mobile-web-app-capable'] = 'yes'
        meta_tags['apple-mobile-web-app-capable'] = 'yes'
        meta_tags['apple-mobile-web-app-status-bar-style'] = 'default'
        meta_tags['apple-mobile-web-app-title'] = self.pwa_short_name

    return meta_tags

Integration with HTML/CSS/JS Exporter

The HTMLCSSJSExporter uses the PWA configuration from the App class to generate:

1. manifest.json file - Progressive web app configuration
2. Meta tags - To indicate PWA capabilities in different browsers
3. Icon references - For multiple devices and sizes
4. Service Worker registration - For offline functionality

Example of Generated Manifest.json

{
  "name": "App Name",
  "short_name": "Short Name",
  "description": "Application description",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#000000",
  "orientation": "portrait",
  "icons": [
    {
      "src": "icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ]
}

Service Worker Registration Script

The exporter automatically generates code to register the service worker:

if ('serviceWorker' in navigator && '{service_worker_path}') {
  window.addEventListener('load', function() {
    navigator.serviceWorker.register('{service_worker_path}')
      .then(function(registration) {
        console.log('ServiceWorker registration successful');
      })
      .catch(function(error) {
        console.log('ServiceWorker registration failed: ', error);
      });
  });
}

Complete PWA App Configuration Example

# Create a complete PWA application
app = App(
    title="My PWA App",
    description="An amazing progressive application",
    author="My Company",
    keywords=["pwa", "webapp", "productivity"],
    language="en",
    favicon="assets/favicon.ico",
    icon="assets/icon-192x192.png",
    apple_touch_icon="assets/apple-touch-icon.png",
    theme_color="#4A90E2",
    background_color="#FFFFFF",
    service_worker_path="sw.js",
    service_worker_enabled=True,
    pwa_enabled=True,
    pwa_name="My App",
    pwa_short_name="MyApp",
    pwa_display="standalone"
)

# Add pages and components
app.add_page("home", HomeComponent(), title="Home", index=True)
app.add_page("about", AboutComponent(), title="About")

Implementation Considerations

Browser Compatibility

Dars Framework's PWA implementation is compatible with: - Chrome/Chromium (full support) - Firefox (basic support) - Safari (limited support on iOS) - Edge (full support)

Dars - Components Documentation

Barrel Import

You can now import all main components and modules with a single line:

from dars.all import *

This simplifies integration and improves the developer experience.

But if you crate your own components it can cause conflicts with names of your components and built in components if they have the same name.

Introduction to Components

Components are the fundamental elements of Dars that represent UI elements. Each component encapsulates its appearance, behavior, and state, allowing you to create complex interfaces by composing simple elements.

To learn how to create your own custom components, refer to the documentation in Custom Components .

Event Handling with dScript

Dars provides a powerful way to handle user interactions through the dScript class. You can attach event handlers to interactive components like Button and Input to create dynamic and responsive user interfaces.

For a complete list of available event types and how to use them, refer to the documentation in Events .

Runtime Component Manipulation (createComp / deleteComp)

You can create or delete components dynamically at runtime in the browser using createComp() and deleteComp() . These functions return dScript so you can attach them to events.

• from dars.all import * exposes createComp and deleteComp .
• The created subtree is serialized to VDOM, mounted into the DOM, and its events are rehydrated automatically.
• Every node that has an id also receives a CSS class dars-id-<id> to help target multiple instances when needed.

API

createComp(target, root, position='append') -> dScript
deleteComp(id) -> dScript

• target : a component instance or a callable returning one.
• root : id (string) of the DOM/container where to insert.
• position : where to place the new element inside root .
  • append (default)
  • prepend
  • before:<id> (insert before a reference sibling id)
  • after:<id> (insert after a reference sibling id)

Examples

from dars.all import *

container = Container(id="root")

# Add a button that creates a new Text inside #root on click
add_btn = Button(
    text="Add",
    id="add",
    on_click=createComp(Text("Hi", id="msg"), root="root", position='append')
)

# Add another button that inserts before a specific sibling
insert_btn = Button(
    text="Insert Before",
    on_click=createComp(Text("Before", id="before"), root="root", position='before:msg')
)

# Button that deletes an element by id
delete_btn = Button(
    text="Delete msg",
    on_click=deleteComp("msg")
)

Component Lifecycle Hooks (onMount, onUpdate, onUnmount)

Dars components (including @FunctionComponent ) support lifecycle hooks that run in the browser:

• onMount : runs once when the component is registered in the runtime and mounted into the DOM.
• onUpdate : runs after dynamic changes that affect the component, for example:
  • Dars.change({ id, dynamic: true, ... }) (used internally by updateComp ).
  • VRef changes that affect its subtree ( updateVRef() + Dars.updateVRef ).
• onUnmount : runs right before the component is removed from the DOM (for example, via deleteComp ).

Hooks accept dScript or inline JS strings and are passed as component props.

Basic Usage

from dars.all import *

@route("/")
def index():
    counter_box = Container(
        Text("Dynamic counter: ", id="dyn_label"),
        Text(setVRef(0, ".dyn_count")),
        id="dyn_box",
        class_name="p-4 border rounded mb-2",
        onMount=dScript("console.log('[Lifecycle] dyn_box mounted');"),
        onUpdate=dScript("console.log('[Lifecycle] dyn_box updated');"),
        onUnmount=dScript("console.log('[Lifecycle] dyn_box unmounted');"),
    )

    host_id = "dyn_host"

    return Page(
        Container(
            Container(id=host_id),

            # Dynamically create the component with lifecycle and VRefs
            Button(
                "Create",
                on_click=createComp(counter_box, host_id, position="append"),
            ),

            # Update the value using V() + updateVRef (triggers onUpdate)
            Button(
                "Increment",
                on_click=updateVRef(
                    ".dyn_count",
                    V(".dyn_count").int() + 1,
                ),
            ),

            # Delete the component (triggers onUnmount)
            Button(
                "Delete",
                on_click=deleteComp("dyn_box"),
            ),
        )
    )

Behavior in different flows

• Initial render / hydration :

  • The VDOM includes a lifecycle block per node with onMount , onUpdate , onUnmount .
  • The runtime registers hooks during DarsHydrate and runs onMount once per id.

• createComp / deleteComp :

  • createComp uses VDomBuilder to include lifecycle and events in the dynamic VDOM.
  • runtime.createComponent registers lifecycle for the subtree and runs onMount after inserting it into the DOM.
  • deleteComp causes runtime.deleteComponent to run onUnmount before removing the node.

• Dynamic changes and VRefs :

  • updateComp() generates calls to Dars.change({ id, dynamic: true, ... }) , which eventually call onUpdate for that id.
  • updateVRef(selector, ...) updates DOM and VRefs, then calls Dars.updateVRef(selector) , which finds the nearest lifecycle-enabled ancestor for each affected element and runs its onUpdate .

This allows you to attach side effects (logs, external integrations, controlled side-effects) to your components' lifecycle, both for static components and those created/removed at runtime.

dScript Basic Usage

from dars.all import *

# Button with click handler
button = Button(
    text="Click me",
    on_click=dScript("""
        function handleClick(event) {
            alert('Button was clicked!');
            // Access the button element
            const button = event.target;
            // Toggle a class on click
            button.classList.toggle('clicked');
        }
    """)
)

# Input with change handler
input_field = Input(
    placeholder="Type something...",
    on_change=dScript("""
        function handleChange(event) {
            console.log('Input value changed to:', event.target.value);
            // Add validation or other logic here
            if (event.target.value.length < 3) {
                event.target.style.borderColor = 'red';
            } else {
                event.target.style.borderColor = 'green';
            }
        }
    """
)

Available Events

Events and dScriptBest Practices

1. Use Named Functions : Makes debugging easier and allows reusing the same function for multiple events.
2. Keep Handlers Small : Move complex logic to separate functions in your JavaScript code.
3. Access Event Object : The event object provides useful properties like target , keyCode , etc.
4. Return false to prevent default behavior when needed.

Quick Access

• Base Component Class
• Component Search
• Page
• Head
• Text
• Button
• Input
• Container
• Section
• Video
• Audio
• FileUpload
• Markdown
• Image
• Link
• Chart
• DataTable
• Textarea
• Checkbox
• RadioButton
• Select
• Slider
• ProgressBar
• Tooltip
• DatePicker
• Card
• Modal
• Navbar
• Accordion
• Tabs
• Table
• Layout Components
  • GridLayout
  • FlexLayout
  • LayoutBase
  • AnchorPoint

Base Component Class

All components in Dars inherit from the base Component class, which provides common functionality:

from dars.core.component import Component

class Component(ABC):
    def __init__(self, **props):
        self.props = props
        self.children: List[Component] = []
        self.parent: Optional[Component] = None
        self.id: Optional[str] = props.get('id')
        self.class_name: str = props.get("class_name", self.__class__.__name__)
        self.style: Dict[str, Any] = props.get('style', {})
        self.hover_style: Dict[str, Any] = props.get('hover_style', {})
        self.active_style: Dict[str, Any] = props.get('active_style', {})
        self.events: Dict[str, Callable] = {}
        self.key: Optional[str] = props.get('key')

Global Properties

All components support these basic properties:

• id : Unique component identifier
• class_name : CSS class for additional styles
• style : Dictionary of CSS styles
• hover_style : Dictionary of CSS styles on hover
• active_style : Dictionary of CSS styles when active
• set_event(event_name, handler) : Attach event handlers
• on_click event handler receives a dScript object or a comp.state() function
• on_double_click event handler receives a dScript object or a comp.state() function
• on_mouse_down event handler receives a dScript object or a comp.state() function
• on_mouse_up event handler receives a dScript object or a comp.state() function
• on_mouse_enter event handler receives a dScript object or a comp.state() function
• on_mouse_leave event handler receives a dScript object or a comp.state() function
• on_mouse_move event handler receives a dScript object or a comp.state() function
• on_key_press event handler receives a dScript object or a comp.state() function
• on_key_up event handler receives a dScript object or a comp.state() function
• on_key_press event handler receives a dScript object or a comp.state() function
• on_change event handler receives a dScript object or a comp.state() function
• on_input event handler receives a dScript object or a comp.state() function
• on_submit event handler receives a dScript object or a comp.state() function
• on_focus event handler receives a dScript object or a comp.state() function
• on_blur event handler receives a dScript object or a comp.state() function
• on_load event handler receives a dScript object or a comp.state() function
• on_error event handler receives a dScript object or a comp.state() function

• on_resize event handler receives a dScript object or a comp.state() function

• children : List of child components (for containers)

Component-Search-and-Modification

All components include a powerful search and modification system through the find() method. This allows you to search for components in the component tree and modify their attributes using a fluent interface.

Basic Search

# Find by ID
component.find(id="search-button")

# Find by CSS class
component.find(class_name="primary-button")

# Find by component type
component.find(type="Button")  # or type=Button

# Find using a custom predicate
component.find(predicate=lambda c: "welcome" in c.text.lower())

Chained Searches

You can chain multiple find() calls to search within the results of previous searches:

# Find a container and then search within it
component.find(id="main-container")\
        .find(type="Text")\
        .attr(text="New text")

# Multiple levels of search
component.find(class_name="section")\
        .find(type="Container")\
        .find(id="special-text")\
        .attr(text="Modified text")

Modifying Components

Use the attr() method to modify the found components:

# Modify styles
component.find(type="Button").attr(
    style={"background-color": "red", "color": "white"}
)

# Modify class names
component.find(class_name="btn").attr(
    class_name="btn primary"
)

# Modify component-specific attributes
component.find(type="Text").attr(
    text="New content"
)

# Multiple modifications at once
component.find(type="Input").attr(
    placeholder="Type here...",
    style={"padding": "10px"},
    class_name="modern-input"
)

Getting Results

# Get all matched components
components = component.find(type="Button").get()

# Get only the first match
first_button = component.find(type="Button").first()

Search Parameters

Page

The Page component represents the root of a multipage app. It can contain other components and scripts specific to that page.

Page Syntax

from dars.components.basic import Page, Text, Button
from dars.scripts.script import InlineScript
page = Page(
    Text("Bienvenido!"),
    Button("Click aquí", id="btn-demo")
)
# Añadir script JS solo a esta página
page.add_script(InlineScript("""
document.addEventListener('DOMContentLoaded', function() {
    var btn = document.getElementById('btn-demo');
    if (btn) btn.onclick = () => alert('¡Botón de esta página!');
});
"""))

Use Page as the root of each page in the multipage system. Allows passing children directly as arguments and JS scripts per page.

Page Properties

Page Scripts System

The new page scripts system allows assigning scripts to specific pages instead of globally:

• Adding Scripts : Use the add_script() method on a page instance.

from dars.scripts.dscript import dScript

index.add_script(
    dScript(code="console.log('Hello world')")
)

Head

The Head component allows you to manage the <head> section of your page, including the title, meta tags, and links. It supports SEO metadata like Open Graph and Twitter Cards.

Head Syntax

from dars.components.advanced.head import Head

head = Head(
    title="My Page Title",
    description="This is a description for SEO.",
    keywords="dars, framework, python",
    og_title="My Open Graph Title",
    twitter_card="summary_large_image"
)

Head Properties

Text

The Text component displays static or dynamic text.

Text Syntax

from dars.components.basic.text import Text

text = Text(
    text="Contenido del text",
    id="mi-text",
    class_name="text-principal",
    style={
        "font-size": "16px",
        "color": "#333",
        "font-weight": "bold"
    }
)

Text Properties

Text Common Styles

# Título principal
title = Text(
    text="Título Principal",
    style={
        "font-size": "32px",
        "font-weight": "bold",
        "color": "#2c3e50",
        "margin-bottom": "20px",
        "text-align": "center"
    }
)

# Párrafo de contenido
paragraph = Text(
    text="Este es un párrafo de ejemplo con contenido descriptivo.",
    style={
        "font-size": "16px",
        "line-height": "1.6",
        "color": "#34495e",
        "margin-bottom": "15px"
    }
)

# Texto pequeño
note = Text(
    text="Nota: Esta información es importante.",
    style={
        "font-size": "12px",
        "color": "#7f8c8d",
        "font-style": "italic"
    }
)

Button

The Button component creates interactive buttons that can execute actions.

Button Syntax

from dars.components.basic.button import Button

boton = Button(
    text="Hacer clic",
    button_type="button",  # "button", "submit", "reset"
    disabled=False,
    on_click=dScript("""
        function handleClick() {
            alert('Button clicked!');
        }
    """)
    style={
        "background-color": "#3498db",
        "color": "white",
        "padding": "10px 20px",
        "border": "none",
        "border-radius": "4px"
    }
)

Button Properties

Button Examples

# Primary Button
primary_button = Button(
    text="Acción Principal",
    style={
        "background-color": "#007bff",
        "color": "white",
        "padding": "12px 24px",
        "border": "none",
        "border-radius": "6px",
        "font-size": "16px",
        "font-weight": "500",
        "cursor": "pointer",
        "transition": "background-color 0.3s"
    }
)

# Secondary Button
secondary_button = Button(
    text="Cancelar",
    style={
        "background-color": "transparent",
        "color": "#6c757d",
        "padding": "12px 24px",
        "border": "1px solid #6c757d",
        "border-radius": "6px",
        "font-size": "16px",
        "cursor": "pointer"
    }
)

# Danger Button
delete_button = Button(
    text="Eliminar",
    style={
        "background-color": "#dc3545",
        "color": "white",
        "padding": "8px 16px",
        "border": "none",
        "border-radius": "4px",
        "font-size": "14px"
    }
)

# Disabled Button
disabled_button = Button(
    text="No disponible",
    disabled=True,
    style={
        "background-color": "#e9ecef",
        "color": "#6c757d",
        "padding": "10px 20px",
        "border": "none",
        "border-radius": "4px",
        "cursor": "not-allowed"
    }
)

Input

The Input component allows user data entry.

Input Syntax

from dars.components.basic.input import Input

entrada = Input(
    value="Valor inicial",
    placeholder="Escribe aquí...",
    input_type="text",  # "text", "password", "email", "number", etc.
    disabled=False,
    readonly=False,
    required=False,
    max_length=100,
    on_change=dScript("""
        function handleChange(event) {
            console.log('Input changed:', event.target.value);
        }
    """)
    style={
        "width": "300px",
        "padding": "10px",
        "border": "1px solid #ddd",
        "border-radius": "4px"
    }
)

Input Properties

Input Types

# Basic text input
name = Input(
    placeholder="Ingresa tu name",
    input_type="text",
    required=True,
    style={
        "width": "100%",
        "padding": "12px",
        "border": "2px solid #e1e5e9",
        "border-radius": "8px",
        "font-size": "16px"
    }
)

# Email input
email = Input(
    placeholder="tu@email.com",
    input_type="email",
    required=True,
    style={
        "width": "100%",
        "padding": "12px",
        "border": "2px solid #e1e5e9",
        "border-radius": "8px"
    }
)

# Password input
password = Input(
    placeholder="Contraseña",
    input_type="password",
    required=True,
    min_length=8,
    style={
        "width": "100%",
        "padding": "12px",
        "border": "2px solid #e1e5e9",
        "border-radius": "8px"
    }
)

# Numeric input
edad = Input(
    placeholder="Edad",
    input_type="number",
    style={
        "width": "100px",
        "padding": "8px",
        "border": "1px solid #ccc",
        "border-radius": "4px",
        "text-align": "center"
    }
)

# Search input
busqueda = Input(
    placeholder="Buscar...",
    input_type="search",
    style={
        "width": "300px",
        "padding": "10px 15px",
        "border": "1px solid #ddd",
        "border-radius": "20px",
        "background-color": "#f8f9fa"
    }
)

Container

The Container component is a container that can hold other components. It supports multiple ways to add child components.

Container Syntax

from dars.components.basic.container import Container

# Method 1: Pass components as arguments
container = Container(
    Text("Hello"),
    Button("Click me"),
    style={
        "display": "flex",
        "flex-direction": "column",
        "padding": "20px",
        "background-color": "#f8f9fa"
    }
)

# Method 2: Use additional_children parameter
components = [Text("Hello"), Button("Click me")]
container = Container(
    additional_children=components,
    style={
        "display": "flex",
        "flex-direction": "column",
        "padding": "20px",
        "background-color": "#f8f9fa"
    }
)

# Method 3: Add children after creation
container = Container(style={
    "display": "flex",
    "flex-direction": "column",
    "padding": "20px",
    "background-color": "#f8f9fa"
})
container.add_child(Text("Hello"))
container.add_child(Button("Click me"))

Container Properties

Container Layouts

# Vertical layout (column)
columna = Container(
    style={
        "display": "flex",
        "flex-direction": "column",
        "gap": "15px",
        "padding": "20px"
    }
)

# Horizontal layout (row)
fila = Container(
    style={
        "display": "flex",
        "flex-direction": "row",
        "gap": "20px",
        "align-items": "center"
    }
)

# Layout centrado
centrado = Container(
    style={
        "display": "flex",
        "justify-content": "center",
        "align-items": "center",
        "min-height": "100vh",
        "background-color": "#f0f2f5"
    }
)

# Card/Tarjeta
tarjeta = Container(
    style={
        "background-color": "white",
        "border-radius": "12px",
        "padding": "24px",
        "box-shadow": "0 2px 10px rgba(0,0,0,0.1)",
        "max-width": "400px",
        "margin": "20px auto"
    }
)

# Sidebar
sidebar = Container(
    style={
        "width": "250px",
        "height": "100vh",
        "background-color": "#2c3e50",
        "padding": "20px",
        "position": "fixed",
        "left": "0",
        "top": "0"
    }
)

Section

The Section component is a container that can hold other components. It supports multiple ways to add child components. And also its like the Container component but instead of export a <div> to render it exports and <section> .

Section Syntax

from dars.all import *
# Method 1: Pass components as arguments
container = Section(
    Text("Hello"),
    Button("Click me"),
    style={
        "display": "flex",
        "flex-direction": "column",
        "padding": "20px",
        "background-color": "#f8f9fa"
    }
)

# Method 2: Use additional_children parameter
components = [Text("Hello"), Button("Click me")]
container = Section(
    additional_children=components,
    style={
        "display": "flex",
        "flex-direction": "column",
        "padding": "20px",
        "background-color": "#f8f9fa"
    }
)

# Method 3: Add children after creation
container = Section(style={
    "display": "flex",
    "flex-direction": "column",
    "padding": "20px",
    "background-color": "#f8f9fa"
})
container.add_child(Text("Hello"))
container.add_child(Button("Click me"))

Section Properties

Video

The Video component is an advanced wrapper over the HTML5 <video> element. It supports static usage and full reactivity via State + useDynamic .

from dars.all import *
from dars.hooks.value_helpers import V

media_state = State(
    "media",
    current_video="/media/intro.mp4",
    autoplay_video=False,
    muted_video=True,
)

Video(
    src=useDynamic("media.current_video"),
    poster="/media/poster.jpg",
    width="720",
    controls=True,
    autoplay=useDynamic("media.autoplay_video"),
    muted=useDynamic("media.muted_video"),
    preload="metadata",
    class_name="rounded-[8px] shadow-[0_0_20px_rgba(0,0,0,0.4)] mb-[16px]",
    attrs={
        "controlsList": "nodownload",
    },
)

Video Properties

Video Reactivity Notes

• src , autoplay , muted , loop , controls and plays_inline support useDynamic .
• When the associated State changes, the exporter generates bindings that:
  • Update the src attribute directly.
  • For booleans ( autoplay , muted , loop , controls ), add/remove the HTML attribute and sync the DOM property.
• Defaults:
  • controls=True , plays_inline=True by default.
  • autoplay , loop , muted are off by default unless you pass True or a state value.

Video Example with Toggles

from dars.all import *
from dars.hooks.value_helpers import V

media_state = State(
    "media",
    current_video="/media/intro.mp4",
    autoplay_video=False,
    muted_video=True,
)

@route("/", index=True)
def index():
    return Page(
        Container(
            Video(
                src=useDynamic("media.current_video"),
                poster="/media/poster.jpg",
                width="720",
                controls=True,
                autoplay=useDynamic("media.autoplay_video"),
                muted=useDynamic("media.muted_video"),
                preload="metadata",
            ),
            Button(
                "Toggle Mute",
                on_click=media_state.muted_video.set(
                    (V("media.muted_video").bool() == True).then(False, True)
                ),
            ),
            Button(
                "Toggle Autoplay",
                on_click=media_state.autoplay_video.set(
                    (V("media.autoplay_video").bool() == True).then(False, True)
                ),
            ),
        )
    )

Audio

The Audio component wraps the HTML5 <audio> element and supports the same reactive model.

from dars.all import *
from dars.hooks.value_helpers import V

media_state = State(
    "media",
    current_audio="/media/theme1.mp3",
    loop_audio=True,
)

Audio(
    src=useDynamic("media.current_audio"),
    controls=True,
    autoplay=False,
    loop=useDynamic("media.loop_audio"),
    preload="auto",
    class_name="w-[100%] mb-[12px]",
    attrs={"controlsList": "nodownload"},
)

Audio Properties

Audio Reactivity Notes

• src , loop , autoplay , muted , controls support useDynamic .
• Boolean props are wired to the same reactive mechanism que otros componentes built-in:
  • El runtime añade/quita los atributos HTML y sincroniza las propiedades JS ( el.loop , el.muted , etc.).
• Es recomendable ubicar los ficheros dentro de media/ en el root del proyecto y referenciarlos como /media/... . El exporter copiará automáticamente esa carpeta al directorio de export.

Audio Example with Track Switch

@route("/audio-demo")
def audio_demo():
    return Page(
        Container(
            Text("Audio actual:"),
            Text(useDynamic("media.current_audio")),
            Audio(
                src=useDynamic("media.current_audio"),
                controls=True,
                loop=useDynamic("media.loop_audio"),
                preload="auto",
            ),
            Container(
                Button(
                    "Track 1",
                    on_click=media_state.current_audio.set("/media/theme1.mp3"),
                ),
                Button(
                    "Track 2",
                    on_click=media_state.current_audio.set("/media/theme2.mp3"),
                ),
                Button(
                    "Toggle Loop",
                    on_click=media_state.loop_audio.set(
                        (V("media.loop_audio").bool() == True).then(False, True)
                    ),
                ),
            ),
        )
    )

Markdown

The Markdown component allows you to render markdown content directly in your Dars applications, converting markdown syntax to beautiful HTML with proper styling.

Markdown Syntax

from dars.components.basic.markdown import Markdown

# From string content
markdown_component = Markdown(
    content="# Welcome\nThis is **markdown** content",
    id="my-markdown",
    class_name="custom-markdown",
    style={"padding": "20px"}
)

# From file
markdown_from_file = Markdown(
    file_path="README.md",
    id="documentation",
    dark_theme=True
)

Markdown Properties

Markdown Methods

Markdown Examples

# Simple markdown from string
simple_md = Markdown(
    content="# Hello\nThis is a **markdown** example",
    style={"maxWidth": "800px", "margin": "0 auto"}
)

# Load from file with dark theme
docs_md = Markdown(
    file_path="documentation.md",
    dark_theme=True,
    class_name="docs-content"
)

# Update content dynamically
simple_md.update_content(new_content="# Updated\nNew content here")

The Markdown renderer supports fenced code blocks and emits standard language-<lang> classes, e.g. language-python .

By default, the exporter auto-injects a client-side highlighter (highlight.js) once per page and highlights all pre code blocks. This is controlled by markdownHighlight in dars.config.json .

Config example:

{
  "markdownHighlight": true
}

• When true (default), highlight.js CSS/JS + init are added automatically.
• When false , no assets are injected; include your own highlighter if you want colored code.

Fenced code example:

```python
import time
def hello():
    print("hi")
```

Markdown Dependencies

The Markdown component requires the markdown2 library. Included with the framework.

Supported Markdown Features

• Headers ( # , ## , ### )
• Bold and italic text
• Lists (ordered and unordered)
• Links
• Inline code and code blocks
• Tables
• Blockquotes
• Images
• Horizontal rules

Markdown Styling

The Markdown component includes comprehensive default styling for both light and dark themes:

# Light theme (default)
markdown_light = Markdown(content="# Light theme")

# Dark theme
markdown_dark = Markdown(
    content="# Dark theme", 
    dark_theme=True,
    style={"padding": "20px", "borderRadius": "8px"}
)

Markdown Best Practices

1. Use file paths for large documentation content
2. Enable dark theme for better readability in low-light environments
3. Combine with layout components for responsive designs
4. Use the update methods for dynamic content changes

Markdown Integration Example

from dars.core.app import App
from dars.components.basic.markdown import Markdown
from dars.components.basic.container import Container

app = App(title="Documentation Viewer")

# Load documentation from file
docs = Markdown(
    file_path="README.md",
    dark_theme=True,
    class_name="documentation",
    style={
        "maxWidth": "800px",
        "margin": "0 auto",
        "padding": "40px",
        "lineHeight": "1.6"
    }
)

app.set_root(Container(children=[docs]))

This component is perfect for creating documentation pages, blog posts, content management systems, and any application that needs to display formatted text content.

Image

The Image component displays images.

Image Syntax

from dars.components.basic.image import Image

image = Image(
    src="path/to/your/image.jpg",
    alt="Descripción de la image",
    width="300px",
    height="200px",
    class_name="responsive-img",
    style={
        "border-radius": "8px",
        "box-shadow": "0 4px 8px rgba(0,0,0,0.1)"
    }
)

Image Properties

Link

The Link component creates navigation links.

Link Syntax

from dars.components.basic.link import Link

link = Link(
    text="Visitar Google",
    href="https://www.google.com",
    target="_blank", # Abre en una nueva pestaña
    class_name="external-link",
    style={
        "color": "#007bff",
        "text-decoration": "none",
        "font-weight": "bold"
    }
)

Link Properties

Textarea

The Textarea component allows for multi-line text input.

Textarea Syntax

from dars.components.basic.textarea import Textarea

area_text = Textarea(
    value="Texto inicial",
    placeholder="Escribe tu mensaje aquí...",
    rows=5,
    cols=40,
    disabled=False,
    readonly=False,
    required=True,
    max_length=500,
    class_name="comment-box",
    style={
        "width": "100%",
        "padding": "10px",
        "border": "1px solid #ccc",
        "border-radius": "5px"
    }
)

Textarea Properties

FileUpload

The FileUpload component allows users to select files for uploading. It wraps a standard file input with a custom, styleable interface.

FileUpload Syntax

from dars.components.advanced.file_upload import FileUpload

upload = FileUpload(
    id="doc-upload",
    label="Choose a file...",
    accept=".pdf,.doc,.docx",
    multiple=False,
    disabled=False,
    required=True,
    on_change=log("File uploaded"),
    style="m-0"
)

FileUpload Properties

Chart

The Chart component renders interactive charts using Plotly.js.

Chart Syntax

from dars.components.visualization.chart import Chart
import plotly.graph_objects as go

fig = go.Figure(data=[go.Bar(x=['A', 'B', 'C'], y=[10, 20, 15])])

chart = Chart(
    figure=fig,
    width=800,
    height=400,
    style={"margin": "20px auto"}
)

Chart Properties

DataTable

The DataTable component displays tabular data with optional Pandas DataFrame support.

DataTable Syntax

from dars.components.visualization.table import DataTable

# Using list of dicts (recommended)
data = [
    {'Name': 'Alice', 'Age': 30, 'City': 'New York'},
    {'Name': 'Bob', 'Age': 25, 'City': 'London'}
]
table = DataTable(data, theme='dark')

# With custom columns and formatters
data = [{'price': 99.99, 'qty': 5}, {'price': 149.99, 'qty': 3}]
table = DataTable(
    data,
    columns=[
        {'key': 'price', 'label': 'Price', 'formatter': lambda x: f'${x:.2f}'},
        {'key': 'qty', 'label': 'Quantity', 'align': 'center'}
    ],
    striped=True,
    hover=True
)

DataTable Properties

ProgressBar

The ProgressBar component visually displays progress for a task, such as loading or completion percentage.

ProgressBar Syntax

from dars.components.basic.progressbar import ProgressBar

progress = ProgressBar(value=40, max_value=100)

ProgressBar Properties

ProgressBar Example

progress = ProgressBar(value=75, max_value=100)

Tooltip

The Tooltip component displays a tooltip when hovering over a child component.

Tooltip Syntax

from dars.components.basic.tooltip import Tooltip
from dars.components.basic.button import Button

tooltip = Tooltip(
    text="More info",
    child=Button(text="Hover me")
)

Tooltip Properties

Tooltip Example

tooltip = Tooltip(text="Help", child=Button(text="?"))

Accordion

The Accordion component creates a vertically stacked set of expandable/collapsible panels for organizing content.

Accordion Syntax

from dars.components.advanced.accordion import Accordion

accordion = Accordion(
    items=[
        {"title": "Section 1", "content": "Content for section 1"},
        {"title": "Section 2", "content": "Content for section 2"}
    ],
    allow_multiple=False
)

Accordion Properties

Accordion Example

accordion = Accordion(
    items=[
        {"title": "FAQ 1", "content": "Answer 1"},
        {"title": "FAQ 2", "content": "Answer 2"}
    ]
)

Tabs

The Tabs component allows navigation between different views or content panels.

New in 1.0.5: The exporter now recursively detects Tabs at any nesting level (including inside containers, panels, or multipage apps) for minimum_logic and JS injection. You can safely nest Tabs in any structure and the export will work as expected.

Tabs Syntax

from dars.components.advanced.tabs import Tabs

tabs = Tabs(
    tabs=[
        {"label": "Tab 1", "content": "Content 1"},
        {"label": "Tab 2", "content": "Content 2"}
    ],
    default_index=0
)

Tabs Properties

Tabs Example

tabs = Tabs(
    tabs=[
        {"label": "Overview", "content": "Main content"},
        {"label": "Details", "content": "Detailed info"}
    ],
    default_index=0
)

Table

The Table component displays tabular data with rows and columns.

Table Syntax

from dars.components.advanced.table import Table

table = Table(
    columns=["Name", "Age", "Country"],
    data=[
        ["Alice", 30, "USA"],
        ["Bob", 25, "UK"]
    ]
)

Table Properties

Table Example

table = Table(
    columns=["Product", "Price"],
    data=[
        ["Book", "$10"],
        ["Pen", "$2"]
    ]
)

Layout Components

GridLayout

The GridLayout component provides a responsive grid-based layout with customizable rows, columns, gaps, and anchor points for precise positioning of children.

GridLayout Syntax

from dars.components.layout.grid import GridLayout
from dars.components.basic.text import Text

grid = GridLayout(
    rows=2,
    cols=2,
    gap="24px",
    children=[
        Text("Top Left"),
        Text("Top Right"),
        Text("Bottom Left"),
        Text("Bottom Right")
    ]
)

GridLayout Properties

GridLayout Example

grid = GridLayout(
    rows=3,
    cols=2,
    gap="16px",
    children=[Text(f"Cell {i}") for i in range(6)]
)

FlexLayout

The FlexLayout component provides a responsive flexbox layout, supporting direction, wrap, alignment, and gap between children. Useful for row/column layouts.

FlexLayout Syntax

from dars.components.layout.flex import FlexLayout
from dars.components.basic.button import Button

flex = FlexLayout(
    direction="row",
    justify="space-between",
    align="center",
    gap="12px",
    children=[Button("A"), Button("B"), Button("C")]
)