Proa UI

API Reference

Public Proa UI component contracts, common props, variants, feature gates, and data attributes.

Open Markdown

Every public struct, enum, and feature flag. If you are starting out, the quickstart gets you rendering first.

Components render through WebRenderSync, compose inside html_sync!, and write stable data-* attributes that CSS, tests, and client handlers can target.

Feature flags

FeaturePublic exports
rsjsControlledCalendar, ControlledCheckbox, ControlledInput, ControlledRadioGroup, ControlledSelect, ControlledTabs, and related option types. Enabled by default.
markdownMarkdown and PROSE_CSS.
syntax-highlightCodeBlock, CodeBlockLang, and SYNTAX_THEME_CSS.
metadata-exportComponent metadata helpers used by code generation.

Common Contract

Most components follow the same shape:

ContractMeaning
children: Option<C>Generic child content where C: WebRenderSync<_, _>.
class: Option<&'static str>Route-specific class extension appended with ClassList::add_opt.
id: Option<&'static str>Stable DOM ID for components that expose an ID.
typed enumsVariant dimensions such as ButtonSize, BadgeVariant, or TabsOrientation.
data-* attributesPublic hooks for styling, tests, and hydration.
Default or new()Constructors that choose documented defaults.

Use struct literals when you need clarity:

use proa::html_sync;
use crate::components::{Button, ButtonColor, ButtonSize, ButtonVariant};

html_sync! {
    {Button {
        color: Some(ButtonColor::Primary),
        variant: Some(ButtonVariant::Solid),
        size: Some(ButtonSize::Lg),
        children: Some("Create project"),
        ..Button::default()
    }}
}

Use constructor helpers when a component exposes them:

use crate::components::Button;

Button::text("Save")

Markdown and page metadata

Components with Markdown representations implement MdRenderSync<L, B> and render into the same WebContext<L, B> used for HTML. Compose them with md_sync!; use MdRender and md! when rendering awaits data. The markdown feature enables the Markdown component, rather than gating every component's Markdown representation.

Each template takes one string literal. A physically multiline raw literal selects block mode, regardless of its number of # delimiters; an ordinary string or single-line raw literal selects inline mode. Templates restore the previous mode automatically on errors and unwinding. Block templates establish paragraph boundaries and reject inline-only positions such as link labels and table cells. In UI 0.5, the Markdown component also treats authored source as a block document and rejects inline parents. Passthrough wrappers such as Card continue to allow inline children. Heading levels are explicit and do not change with wrapper nesting.

Each template slot is Rust, including nested control flow. Re-enter Markdown with a nested template when a branch or loop emits markup:

use proa::md_sync;
use crate::components::Badge;

md_sync! { r###"
    ## Statuses

    {for label in ["Available", "Pending"] {
        md_sync! { "- {Badge { children: Some(label), ..Default::default() }}\n" }
    }}
    "###
}

UI components keep Proa's default ComponentRole::COMPONENT. In a managed HTML document, your selected page declares ComponentRole::PAGE; ancestors that provide metadata declare ComponentRole::LAYOUT. Set page metadata in render_head using cx.head_mut() setters or HeadMetadata, configure HeadConfig with a trusted URL policy, and place {cx.head()} in the document head. Compose providers through templates so their hooks run. Existing manual document heads remain supported. See Proa's metadata guide for setup and inheritance. The metadata-export feature describes component recipes for code generation; it is independent of document head metadata.

Foundation

ComponentPrimary API
Button<C = ()>size, color, variant, radius, disabled, loading, button_type, id, class, children, and optional action bindings.
ButtonGroup<C = ()>Group wrapper with orientation, separators, and text parts.
Badge<C = ()>variant, class, and children.
Card<C = ()>Card, CardHeader, CardTitle, CardDescription, CardContent, and CardFooter.
Separatororientation, decorative, and class.
Skeleton, Spinner, Kbd, Icon, ImageSmall display primitives for loading, shortcuts, SVG icons, and media.
Link<'a, R = ()>Router-aware anchor with prefetch, scroll, replace, active-class, and fallback rendering controls.
ScriptScript tag rendering with ScriptStrategy.

Button variants:

EnumValues
ButtonSizeSm, Md, Lg, Icon, IconSm, IconLg
ButtonColorPrimary, Secondary, Destructive
ButtonVariantSolid, Outline, Ghost, Link
ButtonRadiusNone, Sm, Md, Lg, Full
ButtonTypeButton, Submit, Reset

Badge variants:

EnumValues
BadgeVariantDefault, Secondary, Destructive, Outline, Success, Warning

Forms

ComponentPrimary API
Inputsize, input_type, name, value, placeholder, disabled, validation attributes, class, and id.
Textareasize, name, value, placeholder, disabled/required/readonly state, rows/cols, wrap, validation attributes, class, and id.
Selectoptions, size, name, value, disabled/required state, validation attributes, class, and id.
Checkbox, RadioGroup, Switch, ToggleTyped boolean or single-choice controls with state, size, disabled, and accessibility attributes.
InputOTPGrouped one-time-code slots with grouped separators.
Field familyFieldSet, FieldLegend, FieldGroup, Field, FieldLabel, FieldContent, FieldTitle, FieldDescription, FieldError, and FieldSeparator.
CalendarServer-rendered calendar with mode and week-start configuration.
ColorPicker, EmojiPickerConstrained option pickers with hidden input output and optional rsjs behavior.

Common form enums:

EnumValues
InputSizeSm, Default, Lg
InputTypeText, Email, Password, Number, Tel, Url, Search, Date, Time, DatetimeLocal, File, Hidden
TextareaSizeSm, Default, Lg
TextareaWrapSoft, Hard, Off
SelectSizeSm, Default, Lg
CheckboxStateUnchecked, Checked, Indeterminate
RadioGroupOrientationVertical, Horizontal
SwitchSizeSm, Default

Use native name, required, and constraint attributes on form controls. Use controlled RSJS variants for reactive values and application validation for errors. In UI 0.5, the retired Proa form-registration API is no longer exposed by UI controls: replace registration with explicit control names and native constraints.

use crate::components::{Input, InputType};

Input {
    input_type: InputType::Email,
    name: Some("email"),
    placeholder: Some("[email protected]"),
    required: true,
    ..Input::new()
}

data-field identifies the Field root; it is independent of the removed form-registration attributes.

ComponentPrimary API
Accordion, AccordionCSSOnlyDisclosure roots, items, triggers, and content. Use CSS-only when no client state is required.
CollapsibleRoot, trigger, and content parts with data-state.
TabsTabs, TabsList, TabsTrigger, and TabsContent with orientation and activation mode.
BreadcrumbBreadcrumb, BreadcrumbList, BreadcrumbItem, BreadcrumbLink, BreadcrumbPage, BreadcrumbSeparator, and BreadcrumbEllipsis.
DropdownMenu, MenubarTrigger, content, group, item, label, separator, shortcut, sub-menu, checkbox item, and radio item parts.
Dialog, AlertDialogRoot, trigger, content, title, description, footer, action, cancel, close, and overlay parts.
Popover, TooltipTrigger/content overlays with side, align, and delay options.
Sheet, DrawerDialog-backed and drawer-backed edge overlays with side/direction and size variants.
CarouselContent, item, previous, and next controls.
SidebarProvider, sidebar, rail, inset, header, content, footer, groups, menu items, menu buttons, actions, badges, skeletons, and nested menu parts.

Common overlay enums:

EnumValues
DialogSizedialog content size variants.
SheetSideTop, Right, Bottom, Left
DrawerDirectiondrawer edge direction variants.
DrawerSizedrawer size variants.
DropdownMenuSide, PopoverSide, TooltipSideside placement variants.
DropdownMenuAlign, PopoverAlign, TooltipAlignalignment variants.
TabsOrientationHorizontal, Vertical
TabsActivationModeautomatic or manual tab activation.

Dialog-like components render SSR-safe markup first. Client handlers hydrate behavior from attributes such as data-dialog-root, data-dialog-trigger, data-dialog-portal, data-dialog-overlay, and close attributes.

Data, Media, And Application Shells

ComponentPrimary API
Table familyTable, TableHeader, TableBody, TableFooter, TableRow, TableHead, TableCell, and TableCaption.
DataTable familyDataTable, sortable DataTableColumnHeader, and DataTablePagination.
ProgressAccessible progressbar with value, label, and indicator output.
ScrollAreaRoot viewport and optional scrollbar orientation.
ResizablePanelGroupPanel group, panels, and keyboard-focusable resize handle.
chartsAreaChart, BarChart, LineChart, DonutChart, StackedBarChart, Boxplot, and SankeyChart.
LeafletMapServer-rendered map shell with JSON-backed point and client payload attributes.
chatChatContainer, ChatBubble, ChatInput, and ChatTypingIndicator.
ToasterToast container configured with ToastPosition and ToastVariant.

Data Attributes

Treat data-* names as part of the public component contract:

Component familyStable hooks
Button and badgedata-button, data-badge, data-variant, data-bind-disabled, data-bind-loading
Formsdata-input, data-textarea, data-select, data-field, data-bind-aria-invalid
Cards and tablesdata-card, data-card-header, data-card-title, data-table, data-table-row, data-table-cell
Disclosuredata-accordion-root, data-accordion-item, data-accordion-trigger, data-accordion-content, data-collapsible-root, data-collapsible-trigger, data-collapsible-content, data-state
Menusdata-dropdown-menu, data-dropdown-root, data-dropdown-trigger, data-dropdown-content, data-dropdown-item, data-menubar-*, data-value, data-checked, data-disabled
Overlaysdata-dialog-root, data-dialog-trigger, data-dialog-portal, data-dialog-overlay, data-dialog-content, data-dialog-close
Sheet and drawerdata-sheet-content, data-side, data-drawer-*, data-direction
Layout/datadata-scroll-area, data-scroll-area-viewport, data-progress, data-progress-indicator, data-data-table

Prefer data attributes for tests and behavior. Prefer class for route-local styling. Do not parse Tailwind class strings as application state.

Performance Rules

Search

Type at least 2 characters