Async Items
+ +The command component supports dynamically loading items from async sources like APIs, databases, or search engines like Pagefind.
+Setup
+ +Add data-command-async="true" to your command element and register a search handler:
API Reference
+ +-
+
window.basecoat.commandAsync.register(id, config)
+ - Register an async search handler for a command element.
+
-
+
idstring
+ - The
idordata-command-idof the command element. When usingcommand_dialogmacro, the dialog gets theidand the inner command getsdata-command-id.
+ config.onSearchfunction required
+ - Async function that receives
(query, signal)and returns an array of items. Each item should havelabel(required),url(optional),icon(optional HTML), andkeywords(optional).
+ config.minLengthnumber
+ - Minimum characters to trigger search. Default:
1
+ config.debouncenumber
+ - Debounce delay in milliseconds. Default:
150
+ config.maxResultsnumber
+ - Maximum results to display. Default:
8
+ config.renderItemfunction
+ - Optional custom renderer. Receives
(item, id)and returns HTML string. Usewindow.basecoat.utils.escapeHtml()to sanitize user content.
+
+
Utilities
+ +Basecoat exposes utility functions for use in custom renderItem implementations:
-
+
window.basecoat.utils.escapeHtml(str)
+ - Escapes HTML special characters to prevent XSS. Use when rendering user-provided content. +
window.basecoat.utils.isValidUrl(url)
+ - Validates URLs to prevent
javascript:protocol attacks. Returnstruefor http, https, relative paths, and hash links.
+
States
+ +The command element uses data-state to indicate the current state:
-
+
data-state="idle"
+ - Initial state, no search active. +
data-state="loading"
+ - Search in progress. Shows "Searching..." message. +
data-state="results"
+ - Results are displayed. +
data-state="empty"
+ - No results found. Shows the
data-emptymessage from the menu element.
+ data-state="error"
+ - Search failed. Shows the error message via
data-erroron the menu.
+
You can style these states using CSS:
+Examples
Dialog
@@ -258,4 +379,55 @@ toc: {% endset %} -{{ code_preview("command-dialog", code_dialog | prettyHtml) }} \ No newline at end of file +{{ code_preview("command-dialog", code_dialog | prettyHtml) }} + +Async Search
+ +This example shows how to integrate with Pagefind for full-text search. The search dialog in this documentation site uses this pattern.
+The signal parameter is an AbortSignal that can be used to cancel in-flight requests when a new search is triggered.