# Web Awesome Components in BetterForms Web Awesome has launched a modern set of web components that you can use directly in BetterForms. This guide shows a minimal, self-contained component you can share so developers can drag-and-drop onto a page without extra setup. References: [Web Awesome Docs](https://webawesome.com/docs/) · [Usage & bundling](https://webawesome.com/docs/usage) ## Approach * Self-contained bfcomponent that: * Loads Web Awesome once (loader + default theme CSS) using `BF.libraryLoadOnce()` * Renders a Web Awesome button (``) with configurable label/variant * Exposes a component-scoped `onClick` named action that forms can override * Default theme (no special theme class required) This avoids global setup and works even if a page hasn’t preloaded Web Awesome. ## Component Definition: `wa_button` Copy this JSON into your components library (site-level is recommended), name it `wa_button`. ```json { "name": "wa_button", "schema": { "label": "Button", "variant": "brand", "size": "medium" }, "html": "{{ schema.label || 'Button' }}", "namedActions": { "onBeforeMount": [{ "action": "function", "function": "try {\n // Load Web Awesome loader (dist-cdn) and default theme CSS once per app session\n await BF.libraryLoadOnce('https://cdn.jsdelivr.net/npm/@awesome.me/webawesome@3/dist-cdn/webawesome.loader.js');\n await BF.libraryLoadOnce('https://cdn.jsdelivr.net/npm/@awesome.me/webawesome@3/dist/styles/themes/default.css', { type: 'stylesheet' });\n} catch (error) {\n console.error('Web Awesome load failed:', error);\n BF.errorThrow(10500, 'Web Awesome load failed', (error && error.message) || String(error));\n}" }], "onClick": [{ "action": "showAlert", "options": { "text": "wa_button clicked", "type": "information" } }] } } ``` Notes: * Uses BetterForms lifecycle `onBeforeMount` so the component waits for the library/style before rendering. * `BF.libraryLoadOnce()` deduplicates loads, so multiple instances/pages remain fast. * Forms can override `onClick` at form scope with their own named action. ## Usage on a Page Add a bfcomponent element that references `wa_button`. ```json { "type": "bfcomponent", "name": "wa_button", "attributes": { "label": "Save", "variant": "brand", "size": "medium" } } ``` Optionally, override the click behavior at form scope by defining an `onClick` named action on the page: ```json { "form": { "namedActions": { "onClick": [ { "action": "showAlert", "options": { "text": "Saving...", "type": "information" } }, { "action": "runUtilityHook", "options": { "type": "save" } } ] } } } ``` ## Alternative: Global Project Script (CDN Kit) Web Awesome “Projects” are like Font Awesome kits: a single script you place in the site’s `` that brings in the library, styles, and assets automatically and updates centrally. * Place the Project script in BetterForms: Site Settings → DOM Header Insertions * Then your components can skip the `onBeforeMount` loader step Docs: [Getting Started – Using a Project](https://webawesome.com/docs/) ## Troubleshooting * Button renders unstyled: Ensure default theme CSS is loaded. This component loads `default.css` automatically via `onBeforeMount`. * Component flashes before styles arrive: We use `onBeforeMount` (blocking) to avoid FOUC. * Conflicts with custom theme: Switch the CSS URL in the loader step to your theme, or load `webawesome.css` if you want the full styles bundle. ## Next Steps * Wrap additional elements (e.g., `wa-input`) using the same pattern: load once in `onBeforeMount`, then render the element. * Provide a small component pack for your team (buttons, inputs, badges, cards). * If you later choose a different theme, swap the CSS URL in one place inside the component. ## See Also * [Creating Components with Third-Party Libraries](/reference/apis-and-services/integrations/creating-components-with-third-party-libraries.md) - Complete guide with FullCalendar, Chart.js, Leaflet, and more examples * [BF.libraryLoadOnce() Reference](/reference/bf-utility-function-ver-0.9.20+/bf-dynamic-library-loading.md) - Library loading utility documentation * [Component Best Practices](/reference/styling/custom-components/component-best-practices.md) - General guidelines for component development --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.klai.studio/reference/apis-and-services/integrations/web-awesome-components.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.