Templates

A3S UI ships optional Nunjucks and Jinja macros for components with larger HTML structures. They generate the same semantic A3S UI markup shown in the component docs, while keeping repeated server-rendered markup easier to maintain.

The templates are versioned with @a3s-lab/ui, so the generated markup matches the CSS and JavaScript files you installed.

Macros

Component	Macro	Nunjucks	Jinja
Combobox	`combobox()`	combobox.njk	combobox.html.jinja
Command	`command()`	command.njk	command.html.jinja
Command	`command_dialog()`	command.njk	command.html.jinja
Dialog	`dialog()`	dialog.njk	dialog.html.jinja
Dropdown Menu	`dropdown_menu()`	dropdown-menu.njk	dropdown-menu.html.jinja
Popover	`popover()`	popover.njk	popover.html.jinja
Select	`select()`	select.njk	select.html.jinja
Sidebar	`sidebar()`	sidebar.njk	sidebar.html.jinja
Tabs	`tabs()`	tabs.njk	tabs.html.jinja
Toast	`toaster()`	toast.njk	toast.html.jinja
Toast	`toast()`	toast.njk	toast.html.jinja

Some macro files include internal recursive helpers such as render_select_items(). Those helpers are implementation details and are not part of the public API.

Usage

Install Templates

Copy the template folder for your template engine from @a3s-lab/ui. Templates are meant to be app-owned, so you can edit them after copying.

Nunjucks

cp -R node_modules/@a3s-lab/ui/templates/nunjucks ./templates/a3s-ui

Jinja

cp -R node_modules/@a3s-lab/ui/templates/jinja ./templates/a3s-ui

Copy only the files you use if you do not want the full template folder.

You can also copy the Nunjucks templates or Jinja templates from GitHub.

Use a Macro

Import a macro from the copied template file, then call it with the props for that component.

Nunjucks

{% from "a3s-ui/select.njk" import select %}
{{ select(
  name="fruit",
  items=[
    { value: "apple", label: "Apple" },
    { value: "banana", label: "Banana" },
    { value: "blueberry", label: "Blueberry" }
  ]
) }}

Jinja

{% from "a3s-ui/select.html.jinja" import select %}
{{ select(
  name="fruit",
  items=[
    { "value": "apple", "label": "Apple" },
    { "value": "banana", "label": "Banana" },
    { "value": "blueberry", "label": "Blueberry" }
  ]
) }}

Macro Reference

`combobox()`

Prop	Type	Default	Description
`id`	`string`	generated	Unique combobox id.
`selected`	`string \| array \| object`	`None` / `none`	Initial selected value or values. Objects can include `value` and `label`.
`name`	`string`	`None` / `none`	Hidden input name.
`multiple`	`boolean`	`false`	Enables chip-based multiple selection.
`placeholder`	`string`	`None` / `none`	Visible input placeholder.
`close_on_select`	`boolean`	`false`	Closes the popover after each option selection in multiple mode.
`clear`	`boolean`	`false`	Shows a clear button in single-select mode.
`auto_highlight`	`boolean`	`false`	Highlights the first matching option while filtering.
`format`	`"value" \| "object"`	`"value"`	Hidden input serialization format.
`main_attrs`	`object`	`{}`	Extra attributes for the `.combobox` root.
`input_attrs`	`object`	`{}`	Extra attributes for the visible input or chip input wrapper.
`popover_attrs`	`object`	`{}`	Extra attributes for the popover element.
`listbox_attrs`	`object`	`{}`	Extra attributes for the listbox.
`hidden_input_attrs`	`object`	`{}`	Extra attributes for the hidden input.

`command()`

Prop	Type	Default	Description
`id`	`string`	generated	Unique command id.
`items`	`array`	`None` / `none`	Optional structured item data. Use caller content when omitted.
`placeholder`	`string`	`"Type a command or search..."`	Search input placeholder.
`empty_text`	`string`	`"No results found."`	Empty-state text.
`main_attrs`	`object`	`{}`	Extra attributes for the `.command` root.
`input_attrs`	`object`	`{}`	Extra attributes for the search input.
`menu_attrs`	`object`	`{}`	Extra attributes for the command menu.

`command_dialog()`

Prop	Type	Default	Description
`id`	`string`	generated	Unique command dialog id.
`items`	`array`	`None` / `none`	Optional structured item data. Use caller content when omitted.
`placeholder`	`string`	`"Type a command or search..."`	Search input placeholder.
`empty_text`	`string`	`"No results found."`	Empty-state text.
`dialog_attrs`	`object`	`{}`	Extra attributes for the native dialog.
`input_attrs`	`object`	`{}`	Extra attributes for the search input.
`menu_attrs`	`object`	`{}`	Extra attributes for the command menu.
`open`	`boolean`	`false`	Renders the dialog open by default.

`dialog()`

Prop	Type	Default	Description
`id`	`string`	generated	Unique dialog id.
`trigger`	`string`	`None` / `none`	Text or HTML for a generated trigger button.
`title`	`string`	`None` / `none`	Dialog title.
`description`	`string`	`None` / `none`	Dialog description.
`footer`	`string`	`None` / `none`	HTML for the dialog footer.
`dialog_attrs`	`object`	`{}`	Extra attributes for the native dialog.
`trigger_attrs`	`object`	`{}`	Extra attributes for the generated trigger button.
`header_attrs`	`object`	`{}`	Extra attributes for the dialog header.
`body_attrs`	`object`	`{}`	Extra attributes for the dialog body section.
`footer_attrs`	`object`	`{}`	Extra attributes for the dialog footer.
`open`	`boolean`	`false`	Renders the dialog open by default.
`close_button`	`boolean`	`true`	Includes the generated close button.
`close_on_overlay_click`	`boolean`	`true`	Adds backdrop-click close behavior.

`dropdown_menu()`

Prop	Type	Default	Description
`trigger`	`string`	required	HTML for the trigger button.
`id`	`string`	generated	Unique dropdown menu id.
`items`	`array`	`None` / `none`	Optional structured menu item data. Use caller content when omitted.
`main_attrs`	`object`	`{}`	Extra attributes for the `.dropdown-menu` root.
`trigger_attrs`	`object`	`{}`	Extra attributes for the trigger button.
`popover_attrs`	`object`	`{}`	Extra attributes for the popover element.
`menu_attrs`	`object`	`{}`	Extra attributes for the menu element.

`popover()`

Prop	Type	Default	Description
`trigger`	`string`	required	HTML for the trigger button.
`id`	`string`	generated	Unique popover id.
`main_attrs`	`object`	`{}`	Extra attributes for the `.popover` root.
`trigger_attrs`	`object`	`{}`	Extra attributes for the trigger button.
`popover_attrs`	`object`	`{}`	Extra attributes for the popover element.

`select()`

Prop	Type	Default	Description
`id`	`string`	generated	Unique select id.
`selected`	`string \| array`	`None` / `none`	Initial selected value or values.
`name`	`string`	generated from `id`	Hidden input name.
`items`	`array`	`None` / `none`	Optional structured item data. Use caller content when omitted.
`multiple`	`boolean`	`false`	Enables multiple selection.
`placeholder`	`string`	`None` / `none`	Placeholder text for multiple mode with no selection.
`close_on_select`	`boolean`	`false`	Closes the popover after each option selection in multiple mode.
`format`	`"value" \| "object"`	`"value"`	Hidden input serialization format.
`main_attrs`	`object`	`{}`	Extra attributes for the `.select` root.
`trigger_attrs`	`object`	`{}`	Extra attributes for the trigger button.
`popover_attrs`	`object`	`{}`	Extra attributes for the popover element.
`listbox_attrs`	`object`	`{}`	Extra attributes for the listbox.
`input_attrs`	`object`	`{}`	Extra attributes for the hidden input.

`sidebar()`

Prop	Type	Default	Description
`id`	`string`	`None` / `none`	Optional sidebar id. Use one when multiple sidebars exist.
`label`	`string`	`"Sidebar navigation"`	Navigation landmark label.
`open`	`boolean`	`true`	Initial open state.
`side`	`"left" \| "right"`	`"left"`	Side of the viewport.
`header`	`string`	`None` / `none`	HTML for the sidebar header.
`footer`	`string`	`None` / `none`	HTML for the sidebar footer.
`menu`	`array`	`None` / `none`	Optional structured menu data. Use caller content when omitted.
`main_attrs`	`object`	`{}`	Extra attributes for the `.sidebar` root.
`header_attrs`	`object`	`{}`	Extra attributes for the header.
`content_attrs`	`object`	`{}`	Extra attributes for the scrollable content section.
`footer_attrs`	`object`	`{}`	Extra attributes for the footer.

`tabs()`

Prop	Type	Default	Description
`id`	`string`	generated	Unique tabs id.
`tabsets`	`array`	`[]`	Tab definitions. Each item can include `tab`, `panel`, `tab_attrs`, and `panel_attrs`.
`main_attrs`	`object`	`{}`	Extra attributes for the `.tabs` root.
`tablist_attrs`	`object`	`{}`	Extra attributes for the tablist. Use `aria-orientation="vertical"` or `data-variant="line"` here.
`default_tab_index`	`number`	`1`	One-based index of the initially selected tab.

`toaster()`

Prop	Type	Default	Description
`id`	`string`	`"toaster"`	Toaster container id.
`toasts`	`array`	`[]`	Initial toast objects rendered inside the toaster.
`attrs`	`object`	`{}`	Extra attributes for the `.toaster` container.

`toast()`

Prop	Type	Default	Description
`category`	`"success" \| "error" \| "info" \| "warning"`	`"success"`	Toast category. Controls icon and ARIA role.
`title`	`string`	`""`	Toast title.
`description`	`string`	`""`	Toast description.
`duration`	`number`	default timeout	Timeout in milliseconds. Use `-1` to keep the toast open.
`icon`	`string`	category icon	Custom icon HTML.
`action`	`object`	`None` / `none`	Action button/link config. Supports `label`, `onclick`, and `href`.
`cancel`	`object`	`None` / `none`	Cancel button/link config. Supports `label`, `onclick`, and `href`.
`attrs`	`object`	`{}`	Extra attributes for the `.toast` element.

#Templates

#Macros

#Usage

#Install Templates

#Use a Macro

#Macro Reference

#combobox()

#command()

#command_dialog()

#dialog()

#dropdown_menu()

#popover()

#select()

#sidebar()

#tabs()

#toaster()

#toast()

Templates

Macros

Usage

Install Templates

Use a Macro

Macro Reference

`combobox()`

`command()`

`command_dialog()`

`dialog()`

`dropdown_menu()`

`popover()`

`select()`

`sidebar()`

`tabs()`

`toaster()`

`toast()`