Whatever you're running into with Web Awesome, this is the place to get unstuck. Search the answers below or browse by topic, from installing Core to managing Pro seats. And if you need a human, Get Help reaches us.
What Web Awesome is, how the open source project works, and where Pro fits in.
Web Awesome is an open source library of UI components from the team at Font Awesome. It's built on standard web components, so it works with any framework, and it works in plain HTML with no framework at all. The core of it is free and always will be. Start with the Installation Guide.
Web Awesome comes from the team at Font Awesome, and it's the next major version of Shoelace. If you have a working Shoelace 2.x project, the migration guide walks through the upgrade component by component.
On GitHub, at shoelace-style/webawesome. Core is MIT-licensed, so forking it, patching it, and self-hosting your own build are all fine. We ask that you keep the MIT copyright and permission notice with anything you pass along, and that you don't pass your fork off as Web Awesome itself.
There are plenty of ways to contribute, and most of them aren't code: a well-written bug report, a fix to the documentation, triaging issues, answering someone's question in the community chat. If you do want to send code, open an issue first (unless it's something small like a typo) and point your pull request at the next branch. The contributing guide covers the rest, including what makes a bug report easy to act on.
There's a security policy for exactly this. It names the address to write to and the subject line that flags your report as a security issue. We'll respond as soon as we can and keep you updated while it's being handled.
Core is the free, open source library, and it's the whole foundation: components, themes, color palettes, native styles, and CSS utilities. Pro builds on top of it with:
The side-by-side comparison covers every row.
Web Awesome Core is free, open source, and always will be. You can get started right away. Pro adds the extras: more components, themes, patterns, the Figma Design Kit, and support from our team. And going Pro is what keeps Core free.
Our Browser Support Policy has the details, including how we handle older browsers.
Accessibility isn't binary, so there's no honest yes-or-no here. What we can commit to: everything we build is developed with accessibility in mind, and we test and improve every component as best we can. But accessible building blocks won't make the rest of your page compliant on their own. Our Accessibility Commitment explains the whole position.
Yes, in two machine-readable formats. There's an Agent Skill for tools that support it, which loads only the documentation the task at hand needs, and an llms.txt file with the full API reference in one text file. Both are generated with every build, so they land in your node_modules when you install from npm. The llms.txt format is still experimental, so let us know how it goes. Start at Using Web Awesome with AI.
Installing, frameworks, theming, and everyday questions about building with it.
The CDN is the easiest way to start: paste a couple of lines into your <head> and you can use any component. Install from npm instead if you'd rather import components in your JavaScript, since importing only the ones you use keeps your bundle as small as possible. You can also download the files and self-host them. The Installation Guide walks through all three.
The migration guide is written for exactly this. It starts with the mechanical find-and-replace (@shoelace-style/shoelace to @awesome.me/webawesome, then sl- to wa- across elements, events, and CSS variables), then walks component by component through what actually changed. Track your progress with the interactive checklist, or hand the mechanical passes to a coding agent using the prompt the guide provides. Its Frequent Gotchas section collects the surprises we hear about most.
All four, plus Vue 2, Astro, Express, and 11ty. Web Awesome is built on standard web components, so it works with any framework. The setup differs a little by framework:
Pick yours on the Frameworks page, which links to a guide for each, with the known limitations.
Start with a theme. A theme, a color palette, and variant colors stack into the overall look, and you mix and match them with classes on your <html> element. To go further, override Web Awesome's --wa- design tokens in your own stylesheet. No preprocessor required. For one component at a time, Customizing & Theming covers CSS parts, custom properties, and custom states.
Yes. Provide your Font Awesome kit code with the data-fa-kit-code attribute or the setKitCode() method, then use your Pro and Pro+ icons through <wa-icon>. Both snippets are on the Installation Guide.
It does, but it's experimental, partly because Lit's SSR package is too. The goal today is to reduce layout shifting and show a rough approximation of each component until its JavaScript is ready, not to make components work without JavaScript. The SSR guide covers setup and lists the known issues, which are worth a read before you commit.
Please do. Translations live in src/translations in the GitHub repo, and you can edit them right there in the browser if you'd rather not clone anything. Send it as a pull request when you're done. Regional translations are welcome too, so a German (Switzerland) file is worth submitting even when a German one already exists. One thing worth knowing before you start: this mechanism translates what's inside our components, not the content of your app. Localization has the full picture.
Something looks off or stopped working? Start here.
A blank space means the name didn't resolve to an SVG. Without a library attribute, <wa-icon> looks the name up in the default library, which is Font Awesome's free icons, so a name borrowed from another set won't be found. Check yours against Font Awesome's icon search. The other two usual suspects are a custom library that hasn't registered yet and a URL the browser refused, since icons load over CORS. Whichever it is, the icon fires a wa-error event when a fetch fails, so listen for that to catch any of them. If you're pulling from another set on purpose, register it with registerIconLibrary() and point the icon at it with library.
That's a flash of undefined custom elements: the browser paints your markup before the component definitions have registered. Add class="wa-cloak" to the wrapper you want held back, or to <html> for the whole page, and it stays hidden until the elements inside are ready. The reveal takes care of itself. The autoloader strips the class when it finishes, and without the autoloader a two-second timeout does the revealing instead, so a slow network or a broken script never leaves you staring at a blank screen. If your JavaScript reads properties or calls methods on first load, wait for the elements too: customElements.whenDefined() for one component, allDefined() for every Web Awesome element in the DOM. Reducing FOUCE covers cloaking and a helper for Turbo apps; Usage covers the waiting.
Check for a missing name. Web Awesome's form controls are form-associated custom elements, so they submit with a <form> the way native controls do: new FormData(form) reads them, form.checkValidity() includes them, form.reset() resets them. That also means the native rule applies: a control without a name attribute never lands in the submitted data. Add one to every <wa-input>, <wa-select>, <wa-checkbox>, and friend you expect to read back. Form Controls covers the rest, including validation.
Light mode applies by default, and dark mode is a class you add: class="wa-dark" on <html> for the whole page, or on any section to darken just that part. If you're coming from another library, make sure you swapped its color-scheme class name for this one. Don't put wa-dark (or wa-light, or wa-invert) directly on a component, though. Those classes reset the variant color tokens on whatever element they land on, which stomps the component's own variant styles. Put the class on a wrapper instead. Light and Dark Mode has the snippet for detecting the system preference and toggling.
Most component styles live inside a shadow root, where your page CSS can't select them at all. What your CSS can win is the handful of things that reach across the boundary. Where both can target the same element, the browser ranks the outer page above the shadow tree before specificity even comes up, so a plain rule in your own stylesheet already beats the component's. Most of the !important declarations you're carrying can probably go. For everything sealed inside, Customizing & Theming covers the CSS parts, custom properties, and custom states each component exposes on purpose.
Cascade layers are the other thing worth checking. Some Web Awesome styles ship in cascade layers, and unlayered CSS beats every layer no matter the specificity. If your overrides sit inside a layer of your own, they lose to any unlayered rule on the page. Move them out of the layer.
What you can and can't do with Core and Pro, in plain language.
Just about anything. Core is MIT-licensed: use it, modify it, self-host it, embed it in web, mobile, and desktop apps, in personal or commercial projects. When you distribute copies or substantial portions, include the MIT copyright and permission notice. What you can't do is pass off modified components as the original Web Awesome, or use our name and logos in a way that implies endorsement.
Yes. Core's MIT license covers commercial and open source projects alike, with no additional permissions needed. You can even sell copies. Just include the MIT copyright and permission notice with anything you distribute.
Nothing here matches that.
Pick the channel that fits what you need. Each one reaches us.
Reproducible bugs and ideas belong on GitHub, where we can triage and track them.
Ask questions, share what you're building, and chat live with other developers on Discord.
Account access, billing, or private matters. Email reaches our support team directly.
D'oh! No results for “”