Installation

Installation installation link

Full documentation: https://webawesome.com/docs

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) cdn easiest link

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@3.7.0/styles/webawesome.css" />
<script type="module" src="https://ka-f.webawesome.com/webawesome@3.7.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>

Using Web Awesome Pro?

Get personalized installation instructions from your workspaces instead.

Installing with npm installing with npm link

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.

Using Web Awesome Pro?

Get personalized installation instructions from your workspaces instead.

Get the Download (Advanced) get the download advanced link

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 additional setup link

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 referencing necessary styles link

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 setting the base path link

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 referencing assets link

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 and Pro+ using font awesome pro and pro link

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@3.7.0/webawesome.loader.js';
  setKitCode('YOUR_KIT_CODE_HERE');
</script>

Now you can use Font Awesome icons through the <wa-icon> component!