Installation
Welcome to Web Awesome! Learn more about this project and how to contribute to it.
You can load Web Awesome via CDN or by installing it locally. If you’re using a framework, make sure to check out the pages for React, Vue, Angular, and Svelte for additional information.
CDN (Easiest)
The CDN is the fastest way to get started with Web Awesome. Just copy and paste the following into the <head> of your HTML to get started!
<link rel="stylesheet" href="https://ka-f.webawesome.com/webawesome@0.17.0/styles/webawesome.css" /> <script type="module" src="https://ka-f.webawesome.com/webawesome@0.17.0/webawesome.loader.js"></script>
Now you can use any Web Awesome component! Try putting a button on the page:
<wa-button variant="brand">Click me!</wa-button>
Get personalized installation instructions from your workspaces instead.
Installing with npm
Start by installing the Web Awesome package:
npm install @awesome.me/webawesome
Then, in your JavaScript files, import the default theme and any components you want to use.
// Web Awesome styles import '@awesome.me/webawesome/dist/styles/webawesome.css'; // Import the components you want to use import '@awesome.me/webawesome/dist/components/button/button.js'; import '@awesome.me/webawesome/dist/components/input/input.js';
Once a component has been imported, you can use it in your HTML normally. Components are cherry picked to ensure you're getting the smallest possible bundle. You can find each component import in the "Importing" section of its documentation.
Get personalized installation instructions from your workspaces instead.
Get the Download (Advanced)
You can download Web Awesome from npm and self-host it.
npm pack @awesome.me/webawesome
This will download a .tgz archive containing all Web Awesome files. Extract it and host the files on your own server.
Additional Setup
The Difference Between /dist & /dist-cdn
If you have Web Awesome installed locally via npm, you'll notice the following directories in the project's root:
dist/ dist-cdn/
The dist-cdn files come with everything bundled together, so you can use them directly without a build tool. The dist files keep dependencies separate, which lets your bundler optimize and share code more efficiently.
Use dist-cdn if you're loading directly in the browser or from a CDN. Use dist if you're using a bundler like Webpack or Vite.
Referencing Necessary Styles
If you're self-hosting Web Awesome, you'll need to set up your pages to reference any necessary styles. You can do so by referencing webawesome.css, or you can pick and choose specific stylesheets you'd like to use.
<!-- Option 1: use all Web Awesome styles --> <link rel="stylesheet" href="/dist/styles/webawesome.css" /> <!-- Option 2: pick and choose styles --> <!-- theme (required) --> <link rel="stylesheet" href="/dist/styles/themes/default.css" /> <!-- native styles (optional) --> <link rel="stylesheet" href="/dist/styles/native.css" /> <!-- CSS utilities (optional) --> <link rel="stylesheet" href="/dist/styles/utilities.css" />
If you choose to use a theme other than the default theme, be sure to add the corresponding class (e.g. .wa-theme-awesome) to your <html> element so that the class is applied.
Setting the Base Path
Some components rely on assets (icons, images, etc.) and Web Awesome needs to know where they're located. For convenience, Web Awesome will try to auto-detect the correct location based on the script you've loaded it from. This assumes assets are colocated with webawesome.loader.js and will "just work" for most users.
If you're using the CDN, you can skip this section. However, if you're using npm or a downloaded version, you'll need to set the base path. You can do this one of two ways.
<!-- Option 1: the data-webawesome attribute --> <script src="bundle.js" data-webawesome="/path/to/webawesome/dist"></script> <!-- Option 2: the setBasePath() method --> <script type="module"> import { setBasePath } from '/path/to/webawesome/dist/webawesome.js'; setBasePath('/path/to/webawesome/dist'); </script>
Referencing Assets
Most of the magic behind assets is handled internally by Web Awesome, but if you need to reference the base path for any reason, the same module exports a function called getBasePath(). An optional string argument can be passed, allowing you to get the full path to any asset.
<script type="module"> import { getBasePath, setBasePath } from '/path/to/webawesome/dist/webawesome.js'; setBasePath('/path/to/assets'); // ... // Get the base path, e.g. /path/to/assets const basePath = getBasePath(); // Get the path to an asset, e.g. /path/to/assets/file.ext const assetPath = getBasePath('file.ext'); </script>
Using Font Awesome Pro & Pro+
Font Awesome users can provide their kit code to unlock Pro and Pro+ icon packs. You can do so by adding the data-fa-kit-code attribute to any element on the page, or by calling the setKitCode() method.
<!-- Option 1: the data-fa-kit-code attribute --> <script src="bundle.js" data-fa-kit-code="abc123"></script> <!-- Option 2: the setKitCode() method --> <script type="module"> import { setKitCode } from 'https://ka-f.webawesome.com/webawesome@0.17.0/webawesome.loader.js'; setKitCode('YOUR_KIT_CODE_HERE'); </script>
Now you can use Font Awesome icons through the <wa-icon> component!