Component API Reference | PraisonAIUI Docs

Component API ReferencePython functions for building dashboard UIs. Each function returns a dict that the frontend renders as a real UI element — 36 components organized into tiers.Essential Components`aiui.metric(label, *, value, delta, delta_color)`A metric card with optional delta indicator.| Parameter | Type | Required | Default | Description ||-----------|------|----------|---------|-------------|| label | str | ✅ | — | Metric label || value | Any | ✅ | — | Main metric value || delta | str | ❌ | None | Change indicator (e.g. "+5%") || delta_color | str | ❌ | "normal" | "normal", "inverse", or "off" |`aiui.progress_bar(label, *, value, max_value)`A progress bar.| Parameter | Type | Required | Default | Description ||-----------|------|----------|---------|-------------|| label | str | ✅ | — | Label above the bar || value | int\|float | ✅ | — | Current value || max_value | int\|float | ❌ | 100 | Maximum value |`aiui.alert(message, *, variant, title)`An alert/notification box.| Parameter | Type | Required | Default | Description ||-----------|------|----------|---------|-------------|| message | str | ✅ | — | Alert body text || variant | str | ❌ | "info" | "info", "success", "warning", "error" || title | str | ❌ | None | Optional bold title |`aiui.badge(text, *, variant)`An inline badge/tag.| Parameter | Type | Required | Default | Description ||-----------|------|----------|---------|-------------|| text | str | ✅ | — | Badge label || variant | str | ❌ | "default" | "default", "secondary", "destructive", "outline" |`aiui.separator()`A horizontal separator line. No parameters.`aiui.tabs(items)`A tabbed container.| Parameter | Type | Required | Description ||-----------|------|----------|-------------|| items | Sequence[dict] | ✅ | List of {"label": str, "children": [comp_dicts]} |`aiui.accordion(items)`A collapsible accordion.| Parameter | Type | Required | Description ||-----------|------|----------|-------------|| items | Sequence[dict] | ✅ | List of {"title": str, "content": str_or_comp} |`aiui.image_display(src, *, alt, caption, width)`An image with optional caption.| Parameter | Type | Required | Default | Description ||-----------|------|----------|---------|-------------|| src | str | ✅ | — | Image URL or path || alt | str | ❌ | "" | Alt text || caption | str | ❌ | None | Caption below image || width | str | ❌ | None | CSS width (e.g. "300px", "50%") |`aiui.code_block(code, *, language)`A code block with syntax highlighting.| Parameter | Type | Required | Default | Description ||-----------|------|----------|---------|-------------|| code | str | ✅ | — | Source code text || language | str | ❌ | "text" | Language for highlighting |`aiui.json_view(data)`A formatted JSON viewer.| Parameter | Type | Required | Description ||-----------|------|----------|-------------|| data | Any | ✅ | Any JSON-serializable data |---Form Input Components`aiui.text_input(label, *, value, placeholder)`| Parameter | Type | Required | Default | Description ||-----------|------|----------|---------|-------------|| label | str | ✅ | — | Input label || value | str | ❌ | "" | Default value || placeholder | str | ❌ | "" | Placeholder text |`aiui.number_input(label, *, value, min_val, max_val, step)`| Parameter | Type | Required | Default | Description ||-----------|------|----------|---------|-------------|| label | str | ✅ | — | Input label || value | int\|float | ❌ | 0 | Default value || min_val | int\|float | ❌ | None | Minimum allowed || max_val | int\|float | ❌ | None | Maximum allowed || step | int\|float | ❌ | 1 | Increment step |`aiui.select_input(label, *, options, value)`| Parameter | Type | Required | Default | Description ||-----------|------|----------|---------|-------------|| label | str | ✅ | — | Input label || options | Sequence[str] | ✅ | — | Option strings || value | str | ❌ | "" | Default selected |`aiui.slider_input(label, *, value, min_val, max_val, step)`| Parameter | Type | Required | Default | Description ||-----------|------|----------|---------|-------------|| label | str | ✅ | — | Input label || value | int\|float | ❌ | 0 | Default value || min_val | int\|float | ❌ | 0 | Minimum || max_val | int\|float | ❌ | 100 | Maximum || step | int\|float | ❌ | 1 | Increment step |`aiui.checkbox_input(label, *, checked)`| Parameter | Type | Required | Default | Description ||-----------|------|----------|---------|-------------|| label | str | ✅ | — | Checkbox label || checked | bool | ❌ | False | Default state |`aiui.switch_input(label, *, checked)`| Parameter | Type | Required | Default | Description ||-----------|------|----------|---------|-------------|| label | str | ✅ | — | Switch label || checked | bool | ❌ | False | Default state |`aiui.radio_input(label, *, options, value)`| Parameter | Type | Required | Default | Description ||-----------|------|----------|---------|-------------|| label | str | ✅ | — | Group label || options | Sequence[str] | ✅ | — | Option strings || value | str | ❌ | "" | Default selected |`aiui.textarea_input(label, *, value, placeholder, rows)`| Parameter | Type | Required | Default | Description ||-----------|------|----------|---------|-------------|| label | str | ✅ | — | Input label || value | str | ❌ | "" | Default value || placeholder | str | ❌ | "" | Placeholder text || rows | int | ❌ | 4 | Visible rows |`aiui.multiselect_input(label, *, options, value)`| Parameter | Type | Required | Default | Description ||-----------|------|----------|---------|-------------|| label | str | ✅ | — | Input label || options | Sequence[str] | ✅ | — | Available choices || value | Sequence[str] | ❌ | () | Default selections |`aiui.date_input(label, *, value)`| Parameter | Type | Required | Default | Description ||-----------|------|----------|---------|-------------|| label | str | ✅ | — | Input label || value | str | ❌ | None | ISO date string |`aiui.time_input(label, *, value)`| Parameter | Type | Required | Default | Description ||-----------|------|----------|---------|-------------|| label | str | ✅ | — | Input label || value | str | ❌ | None | "HH:MM" string |`aiui.color_picker_input(label, *, value)`| Parameter | Type | Required | Default | Description ||-----------|------|----------|---------|-------------|| label | str | ✅ | — | Input label || value | str | ❌ | "#000000" | Default hex color |---Layout & Advanced Components`aiui.container(children, *, title)`A container wrapper with optional title.| Parameter | Type | Required | Default | Description ||-----------|------|----------|---------|-------------|| children | Sequence[dict] | ✅ | — | Child component dicts || title | str | ❌ | None | Optional heading |`aiui.expander(title, *, children, expanded)`A collapsible section.| Parameter | Type | Required | Default | Description ||-----------|------|----------|---------|-------------|| title | str | ✅ | — | Section heading || children | Sequence[dict] | ✅ | — | Content components || expanded | bool | ❌ | False | Initially expanded? |`aiui.divider(text)`A horizontal divider with optional center text.| Parameter | Type | Required | Default | Description ||-----------|------|----------|---------|-------------|| text | str | ❌ | None | Label in the middle of the line |`aiui.header(text, *, level)`A heading element.| Parameter | Type | Required | Default | Description ||-----------|------|----------|---------|-------------|| text | str | ✅ | — | Heading text || level | int | ❌ | 1 | Heading level 1–6 |`aiui.markdown_text(content)`A markdown-rendered text block.| Parameter | Type | Required | Description ||-----------|------|----------|-------------|| content | str | ✅ | Markdown content string |`aiui.link(text, *, href, external)`A hyperlink.| Parameter | Type | Required | Default | Description ||-----------|------|----------|---------|-------------|| text | str | ✅ | — | Link text || href | str | ✅ | — | URL || external | bool | ❌ | False | Open in new tab? |`aiui.button_group(buttons)`A row of buttons.| Parameter | Type | Required | Description ||-----------|------|----------|-------------|| buttons | Sequence[dict] | ✅ | List of {"label": str, "variant": str} |`aiui.stat_group(stats)`A grid of stat/metric cards.| Parameter | Type | Required | Description ||-----------|------|----------|-------------|| stats | Sequence[dict] | ✅ | List of {"label": str, "value": Any, "delta": str} |`aiui.avatar(*, src, name, fallback)`An avatar image or initials.| Parameter | Type | Required | Default | Description ||-----------|------|----------|---------|-------------|| src | str | ❌ | None | Image URL || name | str | ❌ | None | Display name || fallback | str | ❌ | None | Fallback text (e.g. initials) |`aiui.callout(content, *, variant, title)`A callout/highlight box.| Parameter | Type | Required | Default | Description ||-----------|------|----------|---------|-------------|| content | str | ✅ | — | Callout body text || variant | str | ❌ | "info" | "info", "success", "warning", "error" || title | str | ❌ | None | Optional bold title |`aiui.empty(text)`An empty state placeholder.| Parameter | Type | Required | Default | Description ||-----------|------|----------|---------|-------------|| text | str | ❌ | "No data" | Placeholder message |`aiui.spinner(text)`A loading spinner with text.| Parameter | Type | Required | Default | Description ||-----------|------|----------|---------|-------------|| text | str | ❌ | "Loading..." | Loading message |---Media Components`aiui.audio_player(src, *, autoplay)`| Parameter | Type | Required | Default | Description ||-----------|------|----------|---------|-------------|| src | str | ✅ | — | Audio file URL || autoplay | bool | ❌ | False | Auto-play? |`aiui.video_player(src, *, autoplay, poster)`| Parameter | Type | Required | Default | Description ||-----------|------|----------|---------|-------------|| src | str | ✅ | — | Video file URL || autoplay | bool | ❌ | False | Auto-play? || poster | str | ❌ | None | Poster image URL |`aiui.file_download(label, *, href, filename)`| Parameter | Type | Required | Default | Description ||-----------|------|----------|---------|-------------|| label | str | ✅ | — | Button label || href | str | ✅ | — | File URL || filename | str | ❌ | None | Suggested filename |`aiui.gallery(items)`An image/media gallery grid.| Parameter | Type | Required | Description ||-----------|------|----------|-------------|| items | Sequence[dict] | ✅ | List of {"src": str, "alt": str, "caption": str} |---Dashboard Components`aiui.toast(message, *, variant, duration)`A toast notification.| Parameter | Type | Required | Default | Description ||-----------|------|----------|---------|-------------|| message | str | ✅ | — | Notification text || variant | str | ❌ | "info" | "info", "success", "warning", "error" || duration | int | ❌ | 3000 | Auto-dismiss ms |`aiui.dialog(title, *, children, description)`A modal dialog.| Parameter | Type | Required | Default | Description ||-----------|------|----------|---------|-------------|| title | str | ✅ | — | Dialog heading || children | Sequence[dict] | ✅ | — | Content components || description | str | ❌ | None | Subtitle |`aiui.caption(text)`Small muted caption text.| Parameter | Type | Required | Description ||-----------|------|----------|-------------|| text | str | ✅ | Caption content |`aiui.html_embed(content)`Raw HTML embed (trusted content only).| Parameter | Type | Required | Description ||-----------|------|----------|-------------|| content | str | ✅ | HTML string |`aiui.skeleton(*, width, height, variant)`A skeleton loading placeholder.| Parameter | Type | Required | Default | Description ||-----------|------|----------|---------|-------------|| width | str | ❌ | None | CSS width || height | str | ❌ | None | CSS height || variant | str | ❌ | "text" | "text", "card", or "avatar" |`aiui.tooltip_wrap(child, *, content)`Wrap a component with a hover tooltip.| Parameter | Type | Required | Description ||-----------|------|----------|-------------|| child | dict | ✅ | Component to wrap || content | str | ✅ | Tooltip text |---Navigation Components`aiui.breadcrumb(items)`A breadcrumb navigation trail.| Parameter | Type | Required | Description ||-----------|------|----------|-------------|| items | Sequence[dict] | ✅ | List of {"label": str, "href": str\|None} |`aiui.pagination(*, total, page, per_page)`Pagination controls.| Parameter | Type | Required | Default | Description ||-----------|------|----------|---------|-------------|| total | int | ✅ | — | Total items || page | int | ❌ | 1 | Current page (1-based) || per_page | int | ❌ | 10 | Items per page |`aiui.key_value_list(items, *, title)`A key-value display list.| Parameter | Type | Required | Default | Description ||-----------|------|----------|---------|-------------|| items | Sequence[dict] | ✅ | — | List of {"label": str, "value": Any} || title | str | ❌ | None | Optional heading |`aiui.popover(trigger, *, children)`A popover overlay triggered by a component.| Parameter | Type | Required | Description ||-----------|------|----------|-------------|| trigger | dict | ✅ | Component that triggers the popover || children | Sequence[dict] | ✅ | Content inside the popover |---CompositionComponents are designed to compose. Use columns() for horizontal layout within a layout():Component Count Summary| Category | Components | Count ||----------|-----------|-------|| Core | layout, card, columns, table, text, chart | 6 || Essential | metric, progress_bar, alert, badge, separator, tabs, accordion, image_display, code_block, json_view | 10 || Form Inputs | text_input, number_input, select_input, slider_input, checkbox_input, switch_input, radio_input, textarea_input, multiselect_input, date_input, time_input, color_picker_input | 12 || Layout & Advanced | container, expander, divider, header, markdown_text, link, button_group, stat_group, avatar, callout, empty, spinner | 12 || Media | audio_player, video_player, file_download, gallery | 4 || Dashboard | toast, dialog, caption, html_embed, skeleton, tooltip_wrap | 6 || Navigation | breadcrumb, pagination, key_value_list, popover | 4 || Total | | 54 |Custom Component TypesThe dashboard.js renderer supports any dict with a type key. Unknown types render as formatted JSON, making it safe to experiment:---Component Render ProtocolUnderstanding how components flow from Python to the browser.Data FlowStep-by-Step1. Python: Call aiui.card("Revenue", value="$1,500") — returns a dict:2. Server: @aiui.page() handler returns aiui.layout([...]):3. API: GET /api/pages/{id}/data returns the JSON4. Frontend: dashboard.js detects _components key and calls renderComponents():5. Renderer: renderComponent(comp) dispatches on comp.type:6. DOM: Each renderer creates HTML elements with db-* CSS classesThe `_components` KeyThe magic key that triggers structured rendering:aiui.layout(children) automatically wraps children in {"_components": [...]}.Component Dict ProtocolEvery component function returns a dict with:| Key | Required | Description ||-----|----------|-------------|| type | ✅ | Component type name (e.g. "card", "table") || Other keys | Varies | Component-specific properties |CSS ClassesAll components use db-* prefixed CSS classes:| Component | CSS Class ||-----------|-----------|| Card | .db-card, .db-card-title, .db-card-value, .db-card-footer || Table | .db-viewer table || Alert | .db-alert, .db-alert-info, .db-alert-success, etc. || Badge | .db-badge, .db-badge-secondary, .db-badge-destructive || Tabs | .db-tabs, .db-tab-list, .db-tab-btn, .db-tab-panel |Extending with Custom ComponentsTo add a new component type:1. Python: Add function to ui.py:2. Frontend: Add renderer to dashboard.js:3. CSS: Add styles for .db-timelineUntil the frontend renderer is added, unknown types render as formatted JSON.