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.
No. One subscription covers unlimited projects. Seats count people, not websites, so ship as much as you like.
Absolutely. Client work, commercial products, anything you build for someone else. The only wrinkle: if your client's own team wants to keep building with Pro after you hand off, they need seats of their own.
That's the one place Pro can't go. No redistributing Pro components, no selling templates that are mostly Web Awesome. Use Web Awesome Core for that instead. It's MIT-licensed and made for exactly this. Full details in the Pro License.
Seats, subscriptions, payments, invoices, and refunds.
As many seats as you buy. One seat, one person. Pick any number from 1 to 99 at checkout and invite your team from your workspace.
Anyone who designs or builds with Pro: dropping components into pages, editing themes, working from the Figma Design Kit. People who just use what you ship (clients, stakeholders, end users) don't need one.
Yep. Start small, add seats from your workspace settings whenever you need to, and put people in them right away.
Seats belong to the subscription, not to any one person. When someone leaves, free up their seat and hand it to the next hire. Here's how that works in your workspace.
You pay per seat, once a year. The monthly prices you see are just there to make comparing easier. Your subscription renews annually until you cancel.
Credit and debit cards, bank debits and redirects, and digital wallets like Apple Pay, Google Pay, and Alipay, all through Stripe at checkout.
Your workspace's Billing & Subscription tab shows it before it lands: the amount, how many seats, the price per seat, and the renewal date. Any discount you have is already worked in, and account credit shows on its own line. Your subscription renews once a year until you cancel. Owners and anyone with the billing role can see that tab.
They're in Stripe, and the way in is your workspace's Billing & Subscription tab: open the Stripe billing portal from there and your invoice history sits next to your payment method. Only the workspace owner and anyone with the billing role can see that tab, so if that's not you, ask one of them for a copy. Even after your subscription ends, that tab still gets you to your old invoices.
Within 30 days of purchase, as long as you haven't downloaded any Pro components or software yet. After that, purchases are final. The Limited Refund Policy has the specifics.
Canceling doesn't cut you off right away. Your subscription runs to the end of the period you've already paid for, and the billing tab shows a Canceling badge with the date it ends. After that, you keep the last Pro version you had access to. If any of it looks wrong, get in touch and we'll walk you through it.
Everything you shipped stays shipped. The perpetual license is yours to keep: the last Pro version released while you were subscribed stays yours to use, on as many projects as you like, forever. What stops is new components and updates.
For 5 or more seats we'll build a plan around your team: custom pricing, tailored Pro assets and services, and An Actual Human™ to help. Tell us a bit about your team and we'll take it from there: get in touch.
Signing in, workspaces, and managing your team's seats.
Start with a password reset. If your address hasn't been verified yet, an account exists but nobody has claimed it, so head to Claim Your Account. If you get past your password and land on a one-time code prompt, that's two-factor authentication, and it has its own way out. If none of that works, get in touch and we'll get you back in.
Use the recovery code you saved when you turned two-factor authentication on. It's the only way back in on your own. Log in as usual, then choose "using your recovery code" at the one-time code prompt to reach the recovery form. A valid code logs you in and switches two-factor authentication off completely, so turn it back on from Account Settings once your new device is ready.
Pro follows the workspace you're working in, not your login, so a Pro page stops you whenever the active workspace isn't the one holding your seat. The page that stops you names the right workspace and gives you a Switch button that carries you on to where you were headed. If the message instead says the workspace has Pro but you aren't in one of its seats, an owner needs to move you to a role that uses a seat. And if you're an owner who handed your own seat back, get in touch to reclaim it.
Seats belong to the subscription, not to any one person, so it's two moves: remove the person in the seat, then invite their replacement. Owners and admins do both from the Workspace tab. Removing someone ends their access right away and frees the seat, and their projects stay in the workspace. The invitation holds the seat from the moment it goes out, and the role you pick decides whether it uses one: Member and Admin do, Billing doesn't.
There's no self-serve transfer yet, so get in touch and we'll do it for you. Tell us the workspace name, who should take it over, and whether the billing email in Stripe should change too.
Deleting your account is self-serve: from Account Settings, the Delete Account button opens a dialog and you confirm with your current password. There's no undo, so ask for your export first if you want one. Exports aren't self-serve, and the Personal Data section on that same page has a Contact Us button that reaches our support team. Our Privacy Policy covers what we do collect and where to send privacy questions and complaints.
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 “”
We use cookies to make webawesome.com work better by storing limited information about your usage.
We value your privacy, so we won't use them for evil or ask you to join the dark side.