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/[email protected]/styles/webawesome.css">
<script type="module" src="https://ka-f.webawesome.com/[email protected]/webawesome.loader.js"></script>
Pro users: get Web Awesome Pro installation instructions directly from your workspaces.

Now you can start using Web Awesome components! Here's a quick button you can use to test things out:

<wa-button variant="brand">Click me!</wa-button>

Installing with npm

Start by installing the Web Awesome package:

npm install @awesome.me/webawesome
Pro users: install @awesome.me/webawesome-pro instead. See your workspaces for details.

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 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 and 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/[email protected]/webawesome.loader.js';
  setKitCode('YOUR_KIT_CODE_HERE');
</script>

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

    No results