Templates

basecoat-cli is deprecated

Template files now ship with basecoat-css. If you previously copied templates with basecoat-cli, install basecoat-css instead and copy the files from node_modules/basecoat-css/templates.

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

The templates are versioned with basecoat-css, 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 basecoat-css. Templates are meant to be app-owned, so you can edit them after copying.

cp -R node_modules/basecoat-css/templates/nunjucks ./templates/basecoat

cp -R node_modules/basecoat-css/templates/jinja ./templates/basecoat

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.

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

{% from "basecoat/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.

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.

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

Templates

basecoat-cli is deprecated

Macros

Usage

Install Templates

Use a Macro

Macro Reference

`combobox()`

`command()`

`command_dialog()`

`dialog()`

`dropdown_menu()`

`popover()`

`select()`

`sidebar()`

`tabs()`

`toaster()`

`toast()`