UI (lexigram-ui)

HTMX/htpy component library for Lexigram web applications.

Overview

lexigram-ui provides server-rendered UI primitives — components, layouts, HTMX helpers, and rendering utilities — built on htpy for plain Python templates. It ships with atoms (Button, TextInput, Badge), molecules (Card, Modal, Tabs), organisms (Form, SlideOver), and layouts, all integrated via UIModule for DI wiring and config-driven defaults.

Install

uv add lexigram-ui

Quick Start

from lexigram.di.module import Module, module
from lexigram.ui.module import UIModule
from lexigram.ui.config import UIConfig
from lexigram.ui.atoms import Button
from lexigram.ui.core.base import Component, el, render_to_string


@module(imports=[UIModule.configure(UIConfig(default_theme="default", enable_sse=True))])
class AppModule(Module):
    pass


class SavePanel(Component):
    def render(self) -> object:
        return el(
            "section",
            el("h2", "Profile"),
            Button("Save", hx_post="/profile/save"),
            class_="space-y-4",
        )


html = render_to_string(SavePanel())

Configuration

Zero-config usage: Call UIModule.configure() with no arguments to use all defaults.

Option 1 — YAML file

ui:
  default_theme: "default"
  auto_escape: true
  htmx_version: "2.0.4"
  debug_components: false

Option 2 — Profiles + Environment Variables (recommended)

export LEX_UI__DEFAULT_THEME=default
export LEX_UI__DEBUG_COMPONENTS=false

Option 3 — Python

from lexigram.ui.module import UIModule
from lexigram.ui.config import UIConfig

UIModule.configure(
    UIConfig(
        default_theme="default",
        enable_sse=True,
    )
)

Config reference

Field	Default	Env var	Description
`default_theme`	`"default"`	`LEX_UI__DEFAULT_THEME`	CSS theme applied to all components
`auto_escape`	`true`	`LEX_UI__AUTO_ESCAPE`	HTML-escape user-supplied strings by default
`htmx_version`	`"2.0.4"`	`LEX_UI__HTMX_VERSION`	HTMX asset version referenced in layout helpers
`debug_components`	`false`	`LEX_UI__DEBUG_COMPONENTS`	Render `data-component` debug attributes (dev only)
`enable_sse`	`false`	`LEX_UI__ENABLE_SSE`	Enable server-sent event support
`enable_realtime`	`false`	`LEX_UI__ENABLE_REALTIME`	Enable realtime-oriented UI features

Module Factory Methods

Method	Description
`UIModule.configure(config, **kwargs)`	Register `UIProvider` with explicit `UIConfig` values
`UIModule.stub()`	Default no-op module for tests

Key Features

Core rendering primitives — Component, Element, RawHTML, el, raw, render_to_string
HTMX helpers — hx_get, hx_post, hx_target, hx_swap, and higher-level helpers
Server-Sent Events — SSEMessage and SSEStream for realtime UI
Component library — atoms, molecules, organisms, and layouts organized by usage layer
Context and swap zones — UIContext, Zone, Zones, SwapMode
Error and response helpers — validation_error, render_validation_errors, htmx_error_response

Key Source Files

File	What it contains
`src/lexigram/ui/module.py`	`UIModule.configure()`, `.stub()`
`src/lexigram/ui/config.py`	`UIConfig`
`src/lexigram/ui/core/base.py`	`Component`, `Element`, `el`, `render_to_string`
`src/lexigram/ui/protocols.py`	`RenderableProtocol`
`src/lexigram/ui/atoms/__init__.py`	Button, TextInput, Badge, Icon
`src/lexigram/ui/molecules/__init__.py`	Card, Modal, Tabs, Toast
`src/lexigram/ui/organisms/__init__.py`	Form, SlideOver, Chart
`src/lexigram/ui/htmx/htmx.py`	`hx_get`, `hx_post`, `hx_target`, `hx_swap`
`src/lexigram/ui/htmx/sse.py`	`SSEMessage`, `SSEStream`