Dars Framework Documentation

Dars Framework is a full-stack Python UI framework for building web applications. It provides a declarative component-based architecture where developers define UIs in Python, which are then compiled to optimized HTML, CSS, and JavaScript. The framework supports multiple deployment targets from a single codebase: Single-Page Applications (SPA), Multi-Page Applications (MPA), and Server-Side Rendered (SSR) applications with FastAPI.

Why use Dars Framework?

• Python-Native : Write your entire application, from UI to backend logic, using 100% Python. No need to switch between multiple languages.
• Modern Styling System : Built-in Tailwind-like utility system that compiles directly to optimized CSS without external build tools like Node.js or PostCSS.
• Full-Stack by Design : Seamlessly transition from static SPAs to complex SSR applications with FastAPI integration.
• Declarative & Reactive : Build complex UIs with ease using a component-based architecture and a powerful reactive state management system (Hooks).
• Multi-Target Deployment : One codebase for Web (SPA/SSR).
• SEO Ready : Advanced SSR and Metadata (Head) management ensure your application is fully discoverable by search engines.
• Developer Experience : Fast feedback loop with a powerful CLI, hot reloading, and zero-config deployment options.

Getting Started

If you are new to Dars, we recommend following the learning path in this order:

1. Installation & Setup

• Installation Guide : Get Dars running on your machine and set up the VS Code extension.
• Quick Start : Create your first "Hello World" application in minutes.
• CLI Reference : Learn how to use the dars command to init, build, and export projects.

2. Core Concepts

• Components : Explore the library of built-in components like Containers, Buttons, and Inputs.
• Styling System : Master the utility-class styling system to create stunning UIs.
• State Management : Understand how to manage application state and reactivity.
• Hooks System : Learn about V() , setVRef() , useVRef() , and updateVRef() for modern component-level behavior.
• Global Application State & App-level Hooks : Learn about useDynamic , useValue , and other hooks for modern component behavior.

3. Advanced Features

• SPA Routing : Build fast, interactive single-page applications.
• SSR & FastAPI : Implement server-side rendering for better performance and SEO.
• Authentication & Security : Learn how to secure your application with Dars.
• Operations (DAP) : Use the Dars Action Protocol to perform client-side logic without writing JavaScript.
• Custom Components : Learn how to extend the framework with your own reusable components.

4. Specialized Topics

• Animations : Add smooth transitions and interactive animations to your UI.
• Key Events : Handle global and component-level keyboard shortcuts.
• Exporters : Understand how your code is compiled for different platforms.
• Project Config : Deep dive into dars.config.json and environmental variables.

Community & Support

• GitHub : Dars Framework Repository

Installation Guide

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="p-5") # Use ' to escape quotes
text = Text(text="Hello Dars!", style="text-2xl") # 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.

Web Export

Dars exports web applications as optimized HTML, CSS, and JavaScript. Run dars build to generate production-ready web assets in your configured output directory.

dars build

Notes:

• Ensure your dars.config.json is configured correctly for web export.
• Use dars preview to inspect the generated output locally.

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")

if __name__ == "__main__":
    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

# 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
 # New in v1.9.6: Path is optional (defaults to config outdir or ./dist)
 dars preview
 # New in v1.9.6: Custom port support
 dars preview -p 9000

# Build using project config (dars.config.json)
 dars build
 # Build without the default Python minifier
 dars build --no-minify

# Help
 dars --help

# Version
 dars -v

Code Generation (New in v1.9.6)

Scaffold new components and pages instantly with automatic project integration.

# Generate a new FunctionComponent
 dars generate component MyComponent
 dars g component MyComponent

# Generate a new Page
 dars generate page About
 # Specify page type directly
 dars generate page About --page-type spa
 dars generate page Home --page-type static
 dars generate page Profile --page-type ssr

# Generate with auto-injection to main.py
 dars generate page Contact -y

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 {file.py} --format html --output ./hello_output
   dars export {file.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> .

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 (or the one set in dars.config.json ) using app.rTimeCompile() .
2. Backend ( dars dev --backend ) : Deprecated. Use dars dev instead when backendEntry is configured; it starts frontend and backend together.

Common Commands:

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

Dars Project Configuration

The dars.config.json file is the central nervous system of your Dars project. It defines how your application is compiled, optimized, and prepared for deployment.

Configuration Overview

A standard configuration file looks like this:

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

Core Fields

1. Build & Path Configuration

• entry (string): The Python entry point of your application. Defaults to main.py .
• format (string): Target deployment format.
  • html : Standard web application (SPA/MPA/SSR).
• outdir (string): The directory where compiled assets will be saved. Defaults to dist . This directory is also the default path used by dars preview .
• publicDir (string): Directory for static assets (images, fonts, etc.) that will be copied directly to the output.

2. File Filtering

• include (list): List of glob patterns or substrings to include from the public directory.
• exclude (list): List of patterns to ignore during the build process.

3. Optimization & Minification

Dars now uses dars-bundler — a standalone, high-performance Rust binary — as its sole minification engine. It replaces the previous Python-based rjsmin/rcssmin pipeline and the optional Vite/esbuild dependency.

• minify (boolean, default true ): Enables or disables JS and CSS minification via dars-bundler . When enabled, the bundler runs SWC (Rust) for AST-level JS minification with dead-code elimination, and LightningCSS for CSS minification. No Node.js, npm, or Vite installation is required.
• bundle (boolean): Ensures all internal dependencies are bundled into the final distribution.

Note: The old viteMinify and defaultMinify keys are still accepted for backwards compatibility but are ignored — minify is the single control point.

4. Features & Integrations

• markdownHighlight (boolean): Automatically injects Prism.js for syntax highlighting in Markdown components.
• backendEntry (string): Import path for your FastAPI backend (e.g., "backend.api:app" ). Required for SSR projects.
• port (number): The port for the development preview server. Defaults to 8000 . This port is respected by both dars dev and dars preview .

The dars-bundler

dars-bundler is a standalone Rust binary that Dars ships alongside its runtime. It is automatically detected and invoked during dars build / dars export — no manual configuration is needed .

How it works

1. After Dars generates your HTML/CSS/JS output, dars-bundler is called on the output directory.
2. It walks all JS files and runs SWC minification (variable renaming, dead-code elimination, constant folding).
3. It walks all CSS files and runs LightningCSS minification (vendor-prefix removal, color optimization, unused selector pruning).
4. Files in lib/ (the Dars runtime: dars.min.js , dap.js , etc.) are processed with the same pipeline.
5. HTML files are not touched by dars-bundler; they are already optimized by BeautifulSoup during export.

Discovery order

The bundler is resolved in this order:

1. DARS_BUNDLER_PATH env variable (user override)
2. Same directory as the Python executable
3. System PATH
4. dars/bundler/ subdirectory shipped with the framework
5. DarsBundler dev repo target/debug or target/release (development mode)

Disabling minification

Set "minify": false in dars.config.json or pass --no-minify to the CLI:

dars build --no-minify
dars export --no-minify

Custom Utility Styles

One of Dars' most powerful features is the ability to define custom utility classes directly in the configuration. This allows you to create reusable design tokens.

{
  "utility_styles": {
    "btn-primary": [
      "bg-blue-600",
      "text-white",
      "px-4",
      "py-2",
      "rounded-lg",
      "hover:bg-blue-700",
      "transition-all"
    ],
    "card-glass": [
      "bg-white/30",
      "backdrop-blur-md",
      "border",
      "border-white/20",
      "rounded-2xl",
      "shadow-xl"
    ]
  }
}

Usage in Python:

Button("Click Me", style="btn-primary")
Container(style="card-glass")

Deployment Targets

Web (HTML)

The standard format for deploying to the web. When format is html , Dars generates optimized HTML, CSS, and JS files compatible with any static host or FastAPI server.

Best Practices

1. Keep it minimal : Only include necessary files in your publicDir to speed up build times.
2. Environment Variables : Use the dars env system to manage different configurations for development and production.
3. Validate often : Use dars config validate to ensure your configuration matches the requirements of your chosen route types (especially for SSR).

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 import all main components and modules with a single line:

from dars.all import *

This simplifies integration and improves developer experience by exposing components like Text , Button , Container , State , and DAP functions like log , alert , showModal , etc.

Note : Be careful if you create custom components with the same names as built-in components to avoid conflicts.

Introduction to Components

Components are the fundamental UI elements in Dars. Each component encapsulates its appearance, behavior, and state. In modern Dars, you should heavily rely on Utility Classes (Tailwind-like classes) using the class_name property instead of the old style dictionary, and use DAP Functions ( show() , hide() , log() , alert() , updateVRef() ) instead of writing raw inline JavaScript for events.

For custom components, refer to Custom Components .

Base Component Class

All UI elements inherit from the Component base class, which provides standard attributes and DOM manipulation methods.

Global Properties

• id : Unique identifier for the component.
• class_name : String containing CSS utility classes (e.g., "flex flex-col bg-slate-100 p-4 rounded-lg" ).
• style : Optional dictionary or string for direct inline styles (prefer class_name ).
• children : List of child components.
• Events : Handlers like on_click , on_change , on_mouse_enter , etc. Accept DAP utility functions or state setters.

Core Components

Container

The Container acts as a generic <div> to group components.

from dars.all import *

layout = Container(
    Text("Welcome to Dars", style="text-4xl font-black text-slate-900 mb-4"),
    Button("Get Started", style="bg-indigo-600 text-white px-6 py-3 rounded-xl shadow-lg hover:bg-indigo-700 transition-all scale-105 active:scale-95"),
    style="flex flex-col items-center justify-center min-h-screen bg-slate-50"
)

Section

Similar to Container , but renders as a semantic <section> HTML tag.

main_section = Section(
    Text("About Us", style="text-xl font-semibold"),
    style="p-8 border-t border-slate-200"
)

Text

Displays static or reactive text.

title = Text(
    "Dars Framework",
    style="text-6xl font-black text-transparent bg-clip-text bg-gradient-to-r from-indigo-500 via-purple-500 to-pink-500"
)

# Reactive text using useDynamic
user_name = Text(useDynamic("user.name"), style="text-lg font-medium")

Interactive Components

Button

Creates interactive clickable buttons. Use DAP functions for events instead of inline JavaScript.

submit_btn = Button(
    "Save Changes",
    style="bg-emerald-500 text-white font-semibold py-3 px-6 rounded-lg transition-all hover:bg-emerald-600 hover:shadow-xl active:scale-95",
    on_click=log("Changes saved successfully!")
)

Input

Allows text or numeric user input.

email_input = Input(
    placeholder="Enter your email",
    input_type="email",
    required=True,
    style="w-full p-3 border border-slate-300 rounded-lg focus:outline-none focus:ring-2 focus:ring-blue-500",
    on_change=log("Email updated")
)

Checkbox & RadioButton

For boolean selections or single-choice groups.

terms = Checkbox(
    label="I accept the terms",
    checked=False,
    style="accent-blue-500"
)

theme_radio = RadioButton(
    label="Dark Mode",
    name="theme_group",
    checked=True
)

Select

Dropdown menu for options.

dropdown = Select(
    options=["Option 1", "Option 2", "Option 3"],
    value="Option 1",
    style="p-2 border rounded bg-white text-slate-700"
)

Textarea

For multi-line inputs.

comment = Textarea(
    placeholder="Write your comment...",
    rows=4,
    style="w-full p-2 border border-slate-300 rounded resize-y"
)

Slider

Range selection slider.

volume = Slider(
    min_value=0, max_value=100, value=50,
    style="w-[200px] accent-blue-500"
)

FileUpload

upload = FileUpload(
    label="Upload Document",
    accept=".pdf",
    style="cursor-pointer bg-slate-100 p-2 rounded border-dashed border-2"
)

DatePicker

date = DatePicker(value="2025-01-01", style="p-2 rounded border")

Visual & Media Components

Image

logo = Image(
    src="/assets/logo.png",
    alt="Logo",
    style="w-[120px] h-auto object-contain drop-shadow-md"
)

Video & Audio

Wrappers over HTML5 media tags with reactivity support.

video_player = Video(
    src="/media/promo.mp4",
    controls=True,
    autoplay=False,
    style="w-full rounded-xl shadow-lg"
)

audio_player = Audio(
    src="/media/soundtrack.mp3",
    controls=True
)

Link

nav_link = Link(
    "Go to Dashboard",
    href="/dashboard",
    style="text-blue-500 hover:text-blue-700 underline"
)

Advanced UI Components

Card

A structured container for displaying related info.

user_card = Card(
    title="Profile Info",
    children=[Text("Username: ZtaDev"), Button("Edit")],
    style="bg-white rounded-xl shadow-md p-6 max-w-sm border border-slate-100"
)

Modal

An overlay dialog. Modals are hidden by default to prevent flicker on load. Use showModal() and hideModal() DAP utilities to control them.

from dars.all import *

info_modal = Modal(
    id="info-modal",
    title="Information",
    is_open=False,
    children=[Text("Here are some details.")],
    style="bg-white rounded-lg p-6 w-[400px]",
    overlay_class="bg-black/50 backdrop-blur-sm"
)

# Open modal using the utility function
open_btn = Button("Show Info", on_click=showModal("info-modal"))

Navbar

Top navigation bar structure.

nav = Navbar(
    brand=Text("MyApp", style="text-xl font-bold"),
    children=[Link("Home", "/"), Link("Settings", "/settings")],
    style="flex justify-between items-center bg-slate-900 text-white p-4 sticky top-0 z-50"
)

Accordion & Tabs

For collapsing content or switching between views.

faq = Accordion(
    items=[
        {"title": "What is Dars?", "content": "A reactive Python web framework."},
        {"title": "Is it fast?", "content": "Yes!"}
    ],
    style="border rounded"
)

dashboard_tabs = Tabs(
    tabs=[
        {"label": "Overview", "content": Text("Overview data")},
        {"label": "Metrics", "content": Text("Metrics data")}
    ]
)

Markdown

Renders Markdown as HTML. Built-in support for highlight.js code highlighting.

doc = Markdown(
    content="## Hello\nThis is **Markdown**",
    style="prose prose-slate max-w-none p-4"
)

ProgressBar & Tooltip

prog = ProgressBar(value=75, max_value=100, style="w-full h-2 bg-slate-200 rounded-full [&::-webkit-progress-value]:bg-blue-500")

tip = Tooltip(text="Click to save", child=Button("Save"))

Data Visualization

DataTable

Render tabular data from lists or Pandas DataFrames.

data = [
    {'Name': 'Alice', 'Role': 'Admin'},
    {'Name': 'Bob', 'Role': 'User'}
]
table = DataTable(data, striped=True, hover=True, theme="light", style="w-full text-left")

Chart

Renders Plotly.js charts.

import plotly.graph_objects as go
fig = go.Figure(data=[go.Bar(x=['A', 'B'], y=[10, 20])])

chart = Chart(figure=fig, style="w-full h-[400px]")

Layout Components

While you can use Container with CSS classes ( style="flex gap-4" ), Dars provides dedicated layout components for convenience.

FlexLayout

row = FlexLayout(
    direction="row",
    justify="space-between",
    align="center",
    gap="16px",
    children=[Button("Cancel"), Button("Confirm")],
    style="w-full p-4"
)

GridLayout

grid = GridLayout(
    rows=2, cols=2, gap="24px",
    children=[Text("1"), Text("2"), Text("3"), Text("4")],
    style="w-full max-w-4xl mx-auto"
)

Dynamic Creation & Lifecycle

Dars allows you to create and delete components dynamically at runtime, with full support for lifecycle hooks.

Runtime Component Manipulation

from dars.all import *

# Component to be generated
msg = Text("Dynamic Message", id="msg", style="text-emerald-600 font-medium")

# Creates the component inside the container with ID 'root'
create_btn = Button("Add Message", on_click=createComp(msg, root="root", position="append"))

# Deletes the component with ID 'msg'
delete_btn = Button("Remove Message", on_click=deleteComp("msg"))

Lifecycle Hooks (onMount, onUpdate, onUnmount)

Components can trigger DAP operations or callbacks when they are created, updated, or destroyed.

dynamic_box = Container(
    id="dyn_box",
    class_name="p-4 border rounded",
    onMount=log("dyn_box was added to DOM"),
    onUpdate=log("dyn_box was updated"),
    onUnmount=log("dyn_box was removed from DOM")
)

• onMount : Runs once when the component is inserted into the DOM.
• onUpdate : Runs after dynamic updates (e.g., via updateComp or reactive V() updates).
• onUnmount : Runs right before the component is deleted from the DOM.

Control Flow Components

Dars provides three dedicated components for conditional rendering and list rendering. They work at both compile time (Python booleans and lists) and runtime (VRef expressions from setVRef / useFetch ).

Show — Runtime Visibility Toggle

Show always renders its children into the DOM. A falsy condition hides the wrapper with display:none . When the condition is a VRef expression, the browser runtime shows or hides the wrapper automatically whenever the VRef value changes.

Use Show for loading spinners, error banners, and any UI that toggles based on runtime state.

from dars.all import *

is_loading = setVRef(True, ".tasks-loading")
has_error  = setVRef(False, ".tasks-error")

# Loading spinner — visible while is_loading is True
Show(
    is_loading,
    Container(
        Spinner(),
        Text("Loading tasks…", style="text-gray-500 ml-2"),
        style="flex items-center gap-2 mb-4",
    ),
)

# Error banner — hidden by default, shown when has_error becomes True
Show(
    has_error,
    Container(
        Text("Could not load tasks. Is the backend running?", style="text-red-600"),
        style="bg-red-50 border border-red-200 rounded p-3 mb-4",
    ),
)

Compile-time bool (static hide/show):

Show(condition=False, Text("Hidden at build time"))
# → renders with style="display:none"

Props:

Each — List Rendering

Each renders a list of items using a template function. It supports two modes:

• Compile-time list — a plain Python list is unrolled at export time, one element per item.
• Runtime VRef list — a VRefValue (from setVRef or useFetch ) emits a data-dap-each attribute; the browser re-renders the container whenever the VRef value changes.

Compile-Time List

from dars.all import *

users = [
    {"name": "Alice", "role": "Admin"},
    {"name": "Bob",   "role": "User"},
]

Each(
    items=users,
    render=lambda u: Container(
        Text(u["name"], style="font-semibold"),
        Text(u["role"], style="text-sm text-gray-500"),
        style="flex justify-between p-2 border-b",
    ),
)

Runtime VRef List (from API)

When items is a VRefValue , the render function is called at export time with a sentinel dict containing __item_<field>__ placeholder strings. The resulting HTML template is stored in data-each-template . At runtime, dom_each_render substitutes real item values for each element in the list.

from dars.all import *

tasks_vref = setVRef([], ".tasks-data")  # starts empty, filled by useFetch

def task_item(t):
    # t is the sentinel dict at export time → placeholders like "__item_title__"
    # t is a real task dict at runtime → actual values
    title   = t.get("title", "__item_title__") if isinstance(t, dict) else "__item_title__"
    item_id = t.get("id",    "__item_id__")    if isinstance(t, dict) else "__item_id__"
    return Container(
        Text(title,         style="flex: 1 1 0%", class_name="__item_done_class__"),
        Text(f"#{item_id}", style="text-xs text-gray-400 ml-2"),
        style="flex items-center gap-2 p-2 border rounded mb-1 bg-white shadow-sm",
    )

Each(
    items=tasks_vref,
    render=task_item,
    class_name="space-y-1 mb-6 min-h-[40px]",
)

Special placeholders:

Supported API response shapes (automatically unwrapped by dom_each_render ):

Props:

Styling System in Dars

Dars Framework introduces a powerful, Python-native utility class system inspired by Tailwind CSS. This system allows you to style your components using concise string utilities directly in your Python code, without needing Node.js, PostCSS, or any external build tools.

Tip: The official Dars Framework VS Code extension provides Tailwind-like utility style completions while editing style="..." strings in Python.

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

Overview

Instead of writing raw CSS dictionaries or separate CSS files, you can now use the style , hover_style , and active_style arguments with utility strings. These strings are parsed at runtime (and export time) into standard CSS dictionaries.

Example

from dars.all import *

def MyComponent():
    return Container(
        Text("Hello, Dars!"),
        style="bg-blue-500 p-4 rounded-lg shadow-md",
        hover_style="bg-blue-600 scale-105",
        active_style="scale-95"
    )

Supported Utilities

The system supports a comprehensive range of utilities covering layout, spacing, typography, colors, borders, effects, transforms, and more.

Arbitrary Properties (Tailwind-like)

You can set any CSS property using the prop-[value] syntax.

• Property names use standard CSS (with - ). If you prefer, you can also write underscores ( _ ) and Dars will convert them to dashes.
• Inside [value] , underscores ( _ ) are converted to spaces. This makes it easy to write complex CSS values inside a single class token.

Examples:

style="background-image-[linear-gradient(90deg,_rgba(0,0,0,.35),_#00ffcc)]"
style="background-color-[rgba(10,20,30,.6)]"
style="padding-[calc(1rem_+_2vw)]"
style="color-[var(--brand-color)]"
style="--brand-color-[#00ffcc]"

Composable properties

Some properties are composable, meaning multiple utilities will be appended (instead of overwriting the previous value):

• filter
• backdrop-filter
• transform

style="filter-[blur(6px)] filter-[brightness(120%)]"

This produces:

filter: blur(6px) brightness(120%);

Layout & Display

• Display : flex , inline-flex , grid , inline-grid , block , inline-block , inline , table , table-row , table-cell , hidden , contents , flow-root
• Flex Direction : flex-row , flex-row-reverse , flex-col , flex-col-reverse
• Flex Wrap : flex-wrap , flex-wrap-reverse , flex-nowrap
• Justify Content : justify-start , justify-end , justify-center , justify-between , justify-around , justify-evenly
• Justify Items : justify-items-start , justify-items-end , justify-items-center , justify-items-stretch
• Align Items : items-start , items-end , items-center , items-baseline , items-stretch
• Align Content : content-start , content-end , content-center , content-between , content-around , content-evenly
• Align Self : self-auto , self-start , self-end , self-center , self-stretch , self-baseline
• Flex Grow/Shrink : grow , grow-0 , shrink , shrink-0
• Flex : flex-1 , flex-auto , flex-initial , flex-none
• Order : order-{n}
• Basis : basis-{value}

Grid

• Grid Template Columns : grid-cols-{n} (e.g., grid-cols-3 , grid-cols-12 )
• Grid Template Rows : grid-rows-{n}
• Grid Column Span : col-span-{n} , col-start-{n} , col-end-{n}
• Grid Row Span : row-span-{n} , row-start-{n} , row-end-{n}
• Grid Auto Flow : grid-flow-row , grid-flow-col , grid-flow-dense , grid-flow-row-dense , grid-flow-col-dense
• Grid Auto Columns : auto-cols-auto , auto-cols-min , auto-cols-max , auto-cols-fr
• Grid Auto Rows : auto-rows-auto , auto-rows-min , auto-rows-max , auto-rows-fr
• Gap : gap-{n} , gap-x-{n} , gap-y-{n}
• Divide : divide-x-{n} , divide-y-{n} , divide-{color} (adds borders between children)

Spacing (Padding & Margin)

• Padding : p-{n} (all sides), px-{n} (horizontal), py-{n} (vertical), pt-{n} (top), pr-{n} (right), pb-{n} (bottom), pl-{n} (left), ps-{n} (inline-start), pe-{n} (inline-end)
• Margin : m-{n} , mx-{n} , my-{n} , mt-{n} , mr-{n} , mb-{n} , ml-{n} , ms-{n} , me-{n}
• Margin Auto : mx-auto , my-auto
• Values :
  • Numbers correspond to 0.25rem units (e.g., 4 = 1rem , 8 = 2rem )
  • Arbitrary values: p-[20px] , m-[5%]

Sizing

• Width : w-{n} , w-full , w-screen , w-auto , w-min , w-max , w-fit , w-1/2 , w-1/3 , w-[300px]
• Height : h-{n} , h-full , h-screen , h-auto , h-min , h-max , h-fit , h-[50vh]
• Min Width : min-w-{n} , min-w-full , min-w-min , min-w-max , min-w-fit
• Min Height : min-h-{n} , min-h-full , min-h-screen , min-h-min , min-h-max , min-h-fit
• Max Width : max-w-{size} (xs, sm, md, lg, xl, 2xl-7xl, full, min, max, fit, prose, screen-{size})
• Max Height : max-h-{n} , max-h-full , max-h-screen , max-h-min , max-h-max , max-h-fit , max-h-none
• Size : size-{n} (sets both width and height)

Typography

• Font Size : text-xs , text-sm , text-base , text-lg , text-xl , text-2xl , text-3xl , text-4xl , text-5xl , text-6xl , text-7xl , text-8xl , text-9xl
• Font Size (Direct) : fs-[32px] , fs-[2rem] Direct font-size specification
• Font Family : ffam-sans , ffam-serif , ffam-mono , ffam-[Open_Sans] , ffam-[Times+New+Roman]
• Font Weight : font-thin , font-extralight , font-light , font-normal , font-medium , font-semibold , font-bold , font-extrabold , font-black
• Font Style : italic , not-italic
• Text Align : text-left , text-center , text-right , text-justify , text-start , text-end
• Text Color : text-{color}-{shade} , text-[#123456]
• Text Decoration : underline , overline , line-through , no-underline
• Text Transform : uppercase , lowercase , capitalize , normal-case
• Text Overflow : truncate , text-ellipsis , text-clip
• Vertical Align : align-baseline , align-top , align-middle , align-bottom , align-text-top , align-text-bottom , align-sub , align-super
• Whitespace : whitespace-normal , whitespace-nowrap , whitespace-pre , whitespace-pre-line , whitespace-pre-wrap , whitespace-break-spaces
• Word Break : break-normal , break-words , break-all , break-keep
• Line Height : leading-none , leading-tight , leading-snug , leading-normal , leading-relaxed , leading-loose , leading-{n}
• Letter Spacing : tracking-tighter , tracking-tight , tracking-normal , tracking-wide , tracking-wider , tracking-widest
• Text Indent : indent-{n}

Smart Property Switching: The text- prefix is smart. If you provide a size (e.g., text-xl ), it sets font-size . If you provide a color (e.g., text-white ), it automatically switches to set the color property.

Colors

Complete Palette (50-950 shades for each):

• Neutrals : slate , gray , zinc , neutral , stone
• Reds : red , rose
• Oranges : orange , amber
• Yellows : yellow , lime
• Greens : green , emerald , teal
• Blues : cyan , sky , blue , indigo
• Purples : violet , purple , fuchsia
• Pinks : pink
• Special : black , white , transparent , current

Opacities: You can set opacity for background, text, border, and rings: - bg-opacity-{n} (0-100) - text-opacity-{n} (0-100) - border-opacity-{n} (0-100) - ring-opacity-{n} (0-100)

Usage Examples:

style="bg-cyan-500 text-white"        # Cyan background
style="bg-emerald-600 text-slate-50"  # Emerald background with light slate text
style="bg-fuchsia-500 text-rose-100"  # Fuchsia background with light rose text
style="bg-amber-400 text-zinc-900"    # Amber background with dark zinc text

Backgrounds

• Background Color : bg-{color}-{shade} , bg-[#f0f0f0]
• Background Images & Gradients :
  • bg-[linear-gradient(...)] (automatically maps to background-image )
  • bg-[radial-gradient(...)]
  • bg-[url(...)]
  • bgimg-[...] (direct background-image utility)
• Background Position : bg-bottom , bg-center , bg-left , bg-left-bottom , bg-left-top , bg-right , bg-right-bottom , bg-right-top , bg-top
• Background Repeat : bg-repeat , bg-no-repeat , bg-repeat-x , bg-repeat-y , bg-repeat-round , bg-repeat-space
• Background Size : bg-auto , bg-cover , bg-contain
• Background Attachment : bg-fixed , bg-local , bg-scroll
• Background Clip : bg-clip-border , bg-clip-padding , bg-clip-content , bg-clip-text
• Background Origin : bg-origin-border , bg-origin-padding , bg-origin-content
• Gradients :
  • bg-gradient-to-{t|tr|r|br|b|bl|l|tl} : Sets the gradient direction.
  • from-{color} : Sets the start color.
  • via-{color} : Sets an intermediate color.
  • to-{color} : Sets the end color.

Gradient Example:

style="bg-gradient-to-r from-indigo-500 via-purple-500 to-pink-500"

Dars uses a modern CSS variable architecture for gradients ( --tw-gradient-stops ), ensuring they are performant and easy to manipulate. - Background Blend Mode : bg-blend-normal , bg-blend-multiply , bg-blend-screen , bg-blend-overlay , bg-blend-darken , bg-blend-lighten , bg-blend-color-dodge , bg-blend-color-burn , bg-blend-hard-light , bg-blend-soft-light , bg-blend-difference , bg-blend-exclusion , bg-blend-hue , bg-blend-saturation , bg-blend-color , bg-blend-luminosity

Borders & Radius

• Border Width : border , border-0 , border-2 , border-4 , border-8
• Border Width (Sides) : border-t-{n} , border-r-{n} , border-b-{n} , border-l-{n} , border-x-{n} , border-y-{n}
• Border Color : border-{color}-{shade} , border-[#123456]
• Border Color (Sides) : border-t-{color} , border-r-{color} , border-b-{color} , border-l-{color} , border-x-{color} , border-y-{color}
• Border Style : border-solid , border-dashed , border-dotted , border-double , border-hidden , border-none
• Border Radius : rounded , rounded-none , rounded-sm , rounded-md , rounded-lg , rounded-xl , rounded-2xl , rounded-3xl , rounded-full , rounded-[10px]
• Border Radius (Corners) : rounded-t-{size} , rounded-r-{size} , rounded-b-{size} , rounded-l-{size} , rounded-tl-{size} , rounded-tr-{size} , rounded-br-{size} , rounded-bl-{size}

Effects

• Box Shadow : shadow-sm , shadow , shadow-md , shadow-lg , shadow-xl , shadow-2xl , shadow-inner , shadow-none
• Opacity : opacity-0 , opacity-25 , opacity-50 , opacity-75 , opacity-100
• Rings :
  • ring , ring-{n} : Adds an outer ring (box-shadow) with a specific width (e.g., ring-4 ).
  • ring-{color} : Sets the color of the ring (e.g., ring-blue-500 ).
  • ring-offset-{n} : Adds a white offset between the element and the ring.
  • ring-opacity-{n} : Sets the transparency of the ring.

Ring Example:

style="ring-4 ring-indigo-500 ring-opacity-50 ring-offset-2"

• Mix Blend Mode : mix-blend-normal , mix-blend-multiply , mix-blend-screen , mix-blend-overlay , mix-blend-darken , mix-blend-lighten , mix-blend-color-dodge , mix-blend-color-burn , mix-blend-hard-light , mix-blend-soft-light , mix-blend-difference , mix-blend-exclusion , mix-blend-hue , mix-blend-saturation , mix-blend-color , mix-blend-luminosity

Filters

• Blur : blur-none , blur-sm , blur , blur-md , blur-lg , blur-xl , blur-2xl , blur-3xl
• Brightness : brightness-{n} (0-200)
• Contrast : contrast-{n} (0-200)
• Grayscale : grayscale-{n} (0-100)
• Hue Rotate : hue-rotate-{n} (degrees)
• Invert : invert-{n} (0-100)
• Saturate : saturate-{n} (0-200)
• Sepia : sepia-{n} (0-100)
• Drop Shadow : drop-shadow-sm , drop-shadow , drop-shadow-md , drop-shadow-lg , drop-shadow-xl , drop-shadow-2xl , drop-shadow-none

Backdrop Filters

• Backdrop Blur : backdrop-blur-{size}
• Backdrop Brightness : backdrop-brightness-{n}
• Backdrop Contrast : backdrop-contrast-{n}
• Backdrop Grayscale : backdrop-grayscale-{n}
• Backdrop Hue Rotate : backdrop-hue-rotate-{n}
• Backdrop Invert : backdrop-invert-{n}
• Backdrop Opacity : backdrop-opacity-{n}
• Backdrop Saturate : backdrop-saturate-{n}
• Backdrop Sepia : backdrop-sepia-{n}

Transforms

• Scale : scale-{n} , scale-x-{n} , scale-y-{n} (e.g., scale-110 = 110%)
• Rotate : rotate-{n} (degrees)
• Translate : translate-x-{n} , translate-y-{n}
• Skew : skew-x-{n} , skew-y-{n} (degrees)
• Transform Origin : origin-center , origin-top , origin-top-right , origin-right , origin-bottom-right , origin-bottom , origin-bottom-left , origin-left , origin-top-left

Transitions

• Transition Property : transition-none , transition-all , transition-colors , transition-opacity , transition-shadow , transition-transform
• Transition Duration : duration-{ms} (e.g., duration-300 , duration-500 )
• Transition Delay : delay-{ms}
• Transition Timing : ease-linear , ease-in , ease-out , ease-in-out

Positioning

• Position : static , fixed , absolute , relative , sticky
• Top/Right/Bottom/Left : top-{n} , right-{n} , bottom-{n} , left-{n}
• Inset : inset-{n} , inset-x-{n} , inset-y-{n}
• Z-Index : z-{n} (e.g., z-10 , z-50 )
• Outline : outline-{n} , outline-{color} , outline-offset-{n} , outline-dashed , outline-dotted
• Accent & Caret : accent-{color} , caret-{color}

Overflow

• Overflow : overflow-auto , overflow-hidden , overflow-clip , overflow-visible , overflow-scroll
• Overflow X : overflow-x-auto , overflow-x-hidden , overflow-x-clip , overflow-x-visible , overflow-x-scroll
• Overflow Y : overflow-y-auto , overflow-y-hidden , overflow-y-clip , overflow-y-visible , overflow-y-scroll

Visibility

• Visibility : visible , invisible , collapse

Cursor

• Cursor Types : cursor-auto , cursor-default , cursor-pointer , cursor-wait , cursor-text , cursor-move , cursor-help , cursor-not-allowed , cursor-none , cursor-context-menu , cursor-progress , cursor-cell , cursor-crosshair , cursor-vertical-text , cursor-alias , cursor-copy , cursor-no-drop , cursor-grab , cursor-grabbing , cursor-all-scroll , cursor-col-resize , cursor-row-resize , cursor-n-resize , cursor-e-resize , cursor-s-resize , cursor-w-resize , cursor-ne-resize , cursor-nw-resize , cursor-se-resize , cursor-sw-resize , cursor-ew-resize , cursor-ns-resize , cursor-nesw-resize , cursor-nwse-resize , cursor-zoom-in , cursor-zoom-out

Pointer Events & User Select

• Pointer Events : pointer-events-none , pointer-events-auto
• User Select : select-none , select-text , select-all , select-auto

Object Fit & Position

• Object Fit : object-contain , object-cover , object-fill , object-none , object-scale-down
• Object Position : object-bottom , object-center , object-left , object-left-bottom , object-left-top , object-right , object-right-bottom , object-right-top , object-top

Aspect Ratio

• Aspect Ratio : aspect-auto , aspect-square , aspect-video , aspect-{w}-{h} (e.g., aspect-16-9 )

Float & Clear

• Float : float-right , float-left , float-none
• Clear : clear-left , clear-right , clear-both , clear-none

Box Sizing

• Box Sizing : box-border , box-content

Isolation

• Isolation : isolate , isolation-auto

List Styles

• List Style Type : list-none , list-disc , list-decimal
• List Style Position : list-inside , list-outside

Appearance

• Appearance : appearance-none , appearance-auto

Resize

• Resize : resize-none , resize-y , resize-x , resize

Scroll Behavior

• Scroll Behavior : scroll-auto , scroll-smooth
• Scroll Snap Align : snap-start , snap-end , snap-center , snap-align-none
• Scroll Snap Stop : snap-normal , snap-always
• Scroll Snap Type : snap-none , snap-x , snap-y , snap-both , snap-mandatory , snap-proximity

Scroll Margin & Padding

• Scroll Margin : scroll-m-{n} , scroll-mx-{n} , scroll-my-{n} , scroll-mt-{n} , scroll-mr-{n} , scroll-mb-{n} , scroll-ml-{n}
• Scroll Padding : scroll-p-{n} , scroll-px-{n} , scroll-py-{n} , scroll-pt-{n} , scroll-pr-{n} , scroll-pb-{n} , scroll-pl-{n}

Touch Action

• Touch Action : touch-auto , touch-none , touch-pan-x , touch-pan-left , touch-pan-right , touch-pan-y , touch-pan-up , touch-pan-down , touch-pinch-zoom , touch-manipulation

Will Change

• Will Change : will-change-auto , will-change-scroll , will-change-contents , will-change-transform

Columns

• Columns : columns-{n}

Break After/Before/Inside

• Break After : break-after-{value}
• Break Before : break-before-{value}
• Break Inside : break-inside-{value}

Arbitrary Values

For values not covered by the standard scale, use square brackets [] :

Container(
    style="w-[350px] bg-[#1a2b3c] z-[100] top-[50px] fs-[24px]"
)

Arbitrary value features: - Use underscores for spaces: bg-[url('image.jpg')] → bg-[url('image.jpg')] - Works with any property: p-[20px] , m-[5%] , w-[calc(100%-50px)]

State Variants

You can define styles for specific states using hover_style and active_style arguments.

Button(
    "Click Me",
    style="bg-blue-500 text-white px-4 py-2 rounded transition-all duration-300",
    hover_style="bg-blue-600 shadow-lg scale-105",
    active_style="bg-blue-700 scale-95"
)

Complete Example Styling

from dars.all import *

app = App("Styling Demo")

@route("/")
def index():
    return Page(
        Container(
            # Header with gradient text
            Text(
                "Welcome to Dars",
                style="fs-[48px] font-black text-center mb-8"
            ),

            # Card with new colors
            Container(
                Text("Cyan Card", style="text-xl font-bold mb-2"),
                Text("Using the new cyan color palette", style="text-cyan-100"),
                style="bg-cyan-600 p-6 rounded-xl shadow-xl mb-4"
            ),

            Container(
                Text("Emerald Card", style="text-xl font-bold mb-2"),
                Text("With emerald green background", style="text-emerald-100"),
                style="bg-emerald-600 p-6 rounded-xl shadow-xl mb-4"
            ),

            # Interactive button
            Button(
                "Hover Me",
                style="bg-fuchsia-500 text-white px-6 py-3 rounded-lg transition-all duration-300",
                hover_style="bg-fuchsia-600 scale-110 shadow-2xl",
                active_style="scale-95"
            ),

            style="max-w-4xl mx-auto p-8"
        ),
        style="min-h-screen bg-gradient-to-br from-slate-50 to-zinc-100"
    )

app.add_page("index", index())

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

Performance

The parsing happens in Python before the HTML/CSS is generated. This means:

1. Zero Runtime Overhead : The browser receives standard CSS
2. No JavaScript Dependency : No need to load a large utility CSS library or run JS parsers in the browser
3. Optimized Output : Only the styles you use are generated (as inline styles or extracted CSS)
4. Python-Native : No Node.js, PostCSS, or build tools required

Best Practices

1. Use semantic spacing : Stick to the 0.25rem scale (4, 8, 12, 16, etc.) for consistency
2. Leverage the color palette : Use the predefined color shades for a cohesive design
3. Combine with transitions : Add transition-all duration-300 for smooth hover effects
4. Use arbitrary values sparingly : Prefer standard utilities when possible
5. Keep it readable : Break long utility strings into multiple lines if needed

style="""
    bg-gradient-to-r from-purple-600 to-pink-600
    text-white px-8 py-4 rounded-xl shadow-2xl
    transition-all duration-300
"""

For animations, see the Animation System documentation.

Custom Utilities

You can define your own utility classes in dars.config.json under the utility_styles key. This allows you to create reusable style combinations, use raw CSS properties, and even compose other custom utilities.

Configuration ( dars.config.json ):

{
  "utility_styles": {
    "btn-primary": [
      "bg-blue-600", 
      "text-white", 
      "p-3", 
      "rounded-lg", 
      "hover:bg-blue-700", 
      "transition-all"
    ],
    "card-fancy": [
      "bg-white", 
      "p-8", 
      "rounded-xl", 
      "shadow-lg", 
      "border: 1px solid #e5e7eb"  // Raw CSS property
    ],
    "text-gradient": [
      "font-bold",
      "text-4xl",
      "background: linear-gradient(to right, #4f46e5, #ec4899)",
      "-webkit-background-clip: text",
      "-webkit-text-fill-color: transparent",
      "display: inline-block"
    ]
  }
}

Usage in Python:

Button(text="Click Me", style="btn-primary")
Container(style="card-fancy text-gradient")

Features: - Composition : Combine multiple existing utilities into one class. - Raw CSS : Use standard CSS syntax (e.g., border: 1px solid red ) directly in the list.

Custom Components in Dars Framework

Dars offers two ways to create custom components: Function Components (Recommended) and Class Components (Legacy).

Function Components (Recommended)

Function Components are the modern way to create reusable UI elements. They use simple functions with f-string templates and automatically handle framework features like IDs, styling, and events.

Basic Syntax

Use the @FunctionComponent decorator. You can access framework properties ( id , class_name , style , children ) using the Props helper object or by declaring them as arguments.

Option 1: Using Props Object (Cleanest)

from dars.all import *

@FunctionComponent
def UserCard(name, email, **props):
    return f"""
    <div {Props.id} {Props.class_name} {Props.style}>
        <h3>{name}</h3>
        <p>{email}</p>
        <div class="card-body">
            {Props.children}
        </div>
    </div>
    """

# Usage
card = UserCard("John Doe", "john@example.com", id="user-1", style="p-5")

Option 2: Explicit Arguments

@FunctionComponent
def UserCard(name, email, id, class_name, style, children, **props):
    return f"""
    <div {id} {class_name} {style}>
        <h3>{name}</h3>
        <p>{email}</p>
        <div class="card-body">
            {children}
        </div>
    </div>
    """

Key Features

1. Automatic Property Injection : The framework automatically injects the correct HTML attributes for {id} , {class_name} , and {style} .
2. State V2 Compatible : Function components work seamlessly with State() and reactive updates.
3. Event Handling : Events like on_click are handled automatically by the framework (passed via **props ).
4. Children Support : Use {Props.children} or {children} to render nested content.

Example with State and Events

@FunctionComponent
def Counter(**props):
    return f"""
    <div {Props.id} {Props.class_name} {Props.style}>
        0 {Props.children}
    </div>
    """

# Create component with initial value "0"
counter = Counter(id="my-counter", children="0")

# Make it reactive controlling the 'text' property (textContent)
# Note: This replaces the entire content of the div with the new text
state = State(counter, text="0")

# Update it
Button("Increment", on_click=state.text.set("5"))

Using Hooks in FunctionComponents

FunctionComponents work seamlessly with all Dars hooks, enabling reactive and interactive behavior.

useDynamic() - Reactive Bindings

Use useDynamic() to create reactive text that updates automatically when state changes:

from dars.all import *

userState = State("user", name="John Doe", status="Active")

@FunctionComponent
def UserCard(**props):
    return f'''
    <div {Props.id} {Props.class_name} {Props.style}>
        <h3>Name: {useDynamic("user.name")}</h3>
        <p>Status: {useDynamic("user.status")}</p>
        {Props.children}
    </div>
    '''

# The name and status will update automatically when state changes
card = UserCard(id="user-card")
Button("Update", on_click=userState.name.set("Jane Doe"))

useValue() - Initial Values with Selectors

Use useValue() with selectors to set initial values and enable value extraction:

from dars.all import *

app = App("Example of hooks")

userState = State("user", name="Jane Doe", email="jane@example.com", display="None")

@FunctionComponent
def UserForm(**props):
    return f'''
    <div {Props.id} {Props.class_name} {Props.style}>
        <input value="{useValue("user.name", ".name-input")}" />
        <input value="{useValue("user.email", "#email-field")}" />
        <span>{useValue("user.age", ".age-display")}</span>
        <span>{useDynamic("user.display")}</span>
    </div>
    '''


@route("/")
def index():
    return Page(
        UserForm(id="user-form"),
        # Extract values using V() helper with the selectors
        Button(
            "Get Name",
            on_click=userState.display.set(
                "Name: " + V(".name-input")  # Extract current value
            )
        ),

        Button(
            "Combine Values",
            on_click=userState.display.set(
                V(".name-input") + " (" + V("#email-field") + ")"
            )
        )
    )

app.add_page("index", index(), title="hooks", index=True)

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

useWatch() - Side Effects

Use useWatch() to monitor state changes and execute side effects:

from dars.all import *

app = App("Example of hooks")

cartState = State("cart", total=0.0)

@FunctionComponent
def CartSummary(total=0,**props):
    return f'''
    <div {Props.id} {Props.class_name} {Props.style}>
        <h3>Cart Total: ${useDynamic("cart.total")}</h3>
        {Props.children}
    </div>
    '''

# Watch for cart changes and log
app.useWatch("cart.total", log("Cart total changed!"))

@route("/")
def index():
    return Page(
        CartSummary(id="cart-summary", total=0),
        # Button to add $10 to cart total using V() with state path
        Button("Add $10", on_click=cartState.total.set(
            V("cart.total").float() + 10
        ))
    )

app.add_page("index", index(), title="hooks", index=True)

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

Combining Multiple Hooks

You can combine multiple hooks for complex interactive components:

from dars.all import *

app = App("Example of hooks")

productState = State("product", 
    name="Widget", 
    price=19.99, 
    quantity=1,
    total=19.99
)

@FunctionComponent
def ProductCard(**props):
    return f'''
    <div {Props.id} {Props.class_name} {Props.style}>
        <!-- useDynamic for reactive display -->
        <h3>{useDynamic("product.name")}</h3>
        <p>Price: ${useDynamic("product.price")}</p>
        <!-- useValue for editable quantity -->
        <h3>Number to multiply with price</h3>
        <input type="number" 
               value="{useValue("product.quantity", ".qty-input")}"
               min="1" />


        <!-- useDynamic for calculated total -->
        <p>Total: ${useDynamic("product.total")}</p>

        {Props.children}
    </div>
    '''

# Watch for total changes and show alert
app.useWatch("product.total", log("Total updated!"))

@route("/")
def index():
    return Page(
        ProductCard(id="product-card",name="Milk", price=100, quantity=0, total=0 ),
        Button(
            "Calculate Total",
            on_click=productState.total.set(
                V(".qty-input").int() * V("product.price").float()
            )
        )

    )

app.add_page("index", index(), title="hooks", index=True)

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

Class Components (Legacy)

This is the older method of creating components by inheriting from the Component class. It is more verbose and requires manual handling of rendering logic.

from dars.all import *
from dars.core.component import Component

class CustomComponent(Component):
    def __init__(self, title: str, id: str = None, **props):
        super().__init__(**props)
        self.title = title
        self.id = id
        # Manual event attachment
        self.set_event(EventTypes.CLICK, log('click'))

    def render(self, exporter: 'Exporter') -> str:
        # Manual children rendering
        children_html = self.render_children(exporter)

        return f'''
        <div class="my-component" id="{self.id}" style="{self.style}">
            <h2>{self.title}</h2>
            <div class="content">
                {children_html}
            </div>
        </div>
        '''

Dars Animation System

Dars provides a powerful and easy-to-use animation system built on top of the Web Animations API. It allows you to add professional-grade animations to your components with simple Python function calls.

Animation Overview

All animations in Dars are dScript objects. This means they: - Run entirely on the client side (zero latency) - Can be assigned to any event handler ( on_click , on_mouseover , etc.) - Can be chained together using .then() or the sequence() helper - Return Promises, allowing for complex orchestration

Animation Quick Start

from dars.all import *

# Simple fade in
button.on_click = fadeIn(id="my-element")

# Chain animations
button.on_click = sequence(
    fadeOut(id="old-panel"),
    fadeIn(id="new-panel")
)

Animation Reference

Fade Animations

Control visibility with opacity transitions.

fadeIn(id, duration=300, easing="ease")

Fades an element in from opacity 0 to 1. Sets display: block automatically.

fadeIn(id="modal", duration=500)

fadeOut(id, duration=300, easing="ease", hide=True)

Fades an element out from current opacity to 0. - hide : If True (default), sets display: none after animation completes.

fadeOut(id="notification", duration=2000, hide=True)

Slide Animations

Move elements into or out of view.

slideIn(id, direction="down", duration=300, easing="ease")

Slides an element into its final position. - direction : "up" , "down" , "left" , "right" (from where it enters)

slideIn(id="sidebar", direction="left", duration=400)

slideOut(id, direction="up", duration=300, easing="ease", hide=True)

Slides an element out of view. - direction : "up" , "down" , "left" , "right" (to where it exits)

slideOut(id="sidebar", direction="left", duration=400)

Scale Animations

Zoom elements in and out.

scaleIn(id, duration=300, easing="ease", from_scale=0.0)

Scales an element up to its natural size (scale 1). - from_scale : Starting scale factor (0.0 to 1.0)

scaleIn(id="popup", from_scale=0.5)

scaleOut(id, duration=300, easing="ease", to_scale=0.0, hide=True)

Scales an element down. - to_scale : Ending scale factor (0.0 to 1.0)

scaleOut(id="popup", to_scale=0.0)

Attention Seekers

Draw user attention to elements.

shake(id, intensity=5, duration=500)

Shakes an element horizontally. Great for error feedback. - intensity : Shake distance in pixels.

shake(id="login-form", intensity=10)

bounce(id, distance=20, duration=600)

Bounces an element vertically. - distance : Bounce height in pixels.

bounce(id="notification-icon", distance=15)

pulse(id, scale=1.1, duration=400, iterations=1)

Pulses an element (scales up and down). - scale : Max scale during pulse. - iterations : Number of pulses. Use "infinite" for continuous pulsing.

# Single pulse
pulse(id="heart-icon")

# Continuous heartbeat
pulse(id="status-dot", iterations="infinite", duration=1000)

Transformations

Rotate and flip elements.

rotate(id, degrees=360, duration=500, easing="ease")

Rotates an element.

rotate(id="refresh-icon", degrees=180)

flip(id, axis="y", duration=600)

Flips an element 180 degrees around an axis. - axis : "x" (horizontal flip) or "y" (vertical flip).

flip(id="card", axis="y")

Property Transitions

Animate specific CSS properties.

colorChange(id, from_color, to_color, duration=500, property="background-color")

Smoothly transitions a color property.

colorChange(id="btn", from_color="#fff", to_color="#f00", property="background-color")

morphSize(id, to_width, to_height, duration=500, easing="ease")

Changes the dimensions of an element.

morphSize(id="panel", to_width="100%", to_height="500px")

Scroll & Viewport Animations

Dars provides a powerful, highly optimized Web Animations API-based engine for scroll and viewport-triggered animations. These run autonomously on the client, without eval() or string-execution vulnerabilities.

animateOnView(id, keyframes, duration=300, easing="ease", threshold=0.1, ...)

Triggers an animation as soon as an element enters the viewport. - keyframes : A list of dictionaries representing CSS properties (e.g., [{"opacity": "0"}, {"opacity": "1"}] ). - threshold : How much of the element must be visible (0.0 to 1.0) before triggering. - once : If True , the animation only runs the first time it enters the viewport.

# Fade and slide up when scrolled into view
index.add_script(animateOnView("my-card", [
    {"opacity": "0", "transform": "translateY(50px)"},
    {"opacity": "1", "transform": "translateY(0)"}
], duration=800, threshold=0.2))

staggerOnView(ids, keyframes, duration=300, stagger_delay=100, threshold=0.1, ...)

Animates a list of elements sequentially with a delay as soon as the first element enters the viewport. - ids : List of element IDs. - stagger_delay : Milliseconds to wait between starting each element's animation.

index.add_script(staggerOnView(
    ["card-1", "card-2", "card-3"],
    [{"opacity": "0", "transform": "scale(0.9)"},
     {"opacity": "1", "transform": "scale(1)"}],
    duration=500, stagger_delay=150
))

scrollProgress(id, property, from_val, to_val, unit="", start=0, end=1)

Ties a CSS property directly to the page's scroll progress (0.0 = top of page, 1.0 = bottom). - property : CSS property to animate (e.g., "opacity" , "translateY" ). - start / end : The scroll progress range where the animation occurs.

# Fades out the hero section as the user scrolls down
index.add_script(scrollProgress("hero-section", "opacity", 1.0, 0.0, start=0, end=0.2))

runOnView(id, code, threshold=0.1, once=True)

Executes arbitrary JavaScript code (via a secure callback mechanism) when an element enters the viewport.

index.add_script(runOnView("trigger-zone", "console.log('User reached the bottom!');"))

Chaining & Sequencing

You can run animations in sequence using the sequence() helper or the .then() method.

Using sequence()

The easiest way to run animations one after another.

from dars.all import sequence, fadeIn, slideIn

button.on_click = sequence(
    fadeIn(id="header"),
    slideIn(id="content", direction="up"),
    fadeIn(id="footer")
)

Using .then()

For more granular control or branching logic.

anim1 = fadeIn(id="box1")
anim2 = slideIn(id="box2")

# Run anim1, then anim2
button.on_click = anim1.then(anim2)

Parallel Animations

To run animations simultaneously, simply trigger them in the same event handler (or use a list of handlers).

# Both start at the same time
button.on_click = [
    fadeIn(id="box1"),
    slideIn(id="box2")
]

SPA Routing in Dars Framework

Dars Framework 1.4.5 introduces a powerful SPA (Single Page Application) routing system that supports nested routes, layouts, and automatic 404 handling.

Basic Routing

To create a basic SPA, you define pages and add them to your app. One page must be designated as the index.

from dars.all import *

app = App(title="My SPA App")

# Create pages
home = Page(Container(Text("Home Page")))
about = Page(Container(Text("About Us")))

# Add pages to app
app.add_page(name="home", root=home, route="/", title="Home", index=True)
app.add_page(name="about", root=about, route="/about", title="About")

you can also use the @route decorator to add pages to your app.

from dars.all import *

app = App(title="My SPA App")

# Create pages
home = Page(Container(Text("Home Page")))
about = Page(Container(Text("About Us")))

# Add pages to app
@app.route("/")
def home():
    return Page(Container(Text("Home Page")))

@app.route("/about")
def about():
    return Page(Container(Text("About Us")))

app.add_page("home", home, title="Home", index=True)
app.add_page("about", about, title="About")

Note: If you use the @route decorator, you can't add the route of the page in app.add_page() .

Nested Routes & Layouts

Nested routes allow you to create layouts that persist while child content changes. This is achieved using the parent parameter and the Outlet component.

The Outlet Component

The Outlet component serves as a placeholder where child routes will be rendered within a parent layout.

from dars.components.advanced.outlet import Outlet

# Parent Layout (Dashboard)
dashboard_layout = Page(
    Container(
        Text("Dashboard Header"),
        # Child routes will render here:
        Outlet(),
        Text("Dashboard Footer")
    )
)

# Child Page (Settings)
settings_page = Page(
    Container(Text("Settings Content"))
)

The Outlet can also render an optional placeholder while the child route is still loading (SSR lazy-load or SPA navigation). If placeholder is not provided, nothing is rendered.

from dars.components.advanced.outlet import Outlet

dashboard_layout = Page(
    Container(
        Text("Dashboard Header"),
        Outlet(
            placeholder=Container(Text("Loading section..."))
        ),
        Text("Dashboard Footer")
    )
)