Web Awesome

Web Awesome is a UI component library built with web components. Use when building buttons, inputs, selects, checkboxes, dialogs, modals, drawers, tabs, dropdowns, tooltips, carousels, forms, or using CSS utilities like wa-stack, wa-cluster, wa-grid. Supports React, Vue, Angular, Svelte, and vanilla JS.

Web Awesome web awesome link

Web Awesome is an open source UI component library with a Pro offering that helps sustain the project. It provides 50+ accessible, customizable web components that work with any framework.

Pro components and features are available to paid users. Purchase Pro

Quick Start quick start link

npm Installation npm installation link 

npm install @awesome.me/webawesome

Import styles and components:

import '@awesome.me/webawesome/dist/styles/webawesome.css';
import '@awesome.me/webawesome/dist/components/button/button.js';

CDN / Project Setup cdn project setup link

The easiest way to use Web Awesome is with a hosted project. Create a project to get a single line of code that loads everything automatically.

For detailed installation options, see Installation Guide.

Core Concepts core concepts link

Web Awesome components are custom HTML elements. They work like native elements but with enhanced functionality.

  • Attributes & Properties: Configure components via HTML attributes or JavaScript properties
  • Events: Listen to custom events prefixed with wa- (e.g., wa-change, wa-input)
  • Methods: Call methods programmatically (e.g., element.focus())
  • Slots: Insert content into named slots (e.g., <wa-icon slot="start">)
  • CSS Parts: Style internal elements using ::part() selectors
  • CSS Custom Properties: Customize appearance with CSS variables

Important: Always use closing tags. Custom elements cannot self-close.

<!-- Correct -->
<wa-input></wa-input>

<!-- Incorrect - will not work -->
<wa-input />

For complete usage details, see Usage Guide.

Components components link

Free Components free components link

Actions actions link

  • <wa-button> - Buttons represent actions the user can take, such as submitting a form, opening a dialog, or navigating to another page. (docs)
  • <wa-button-group> - Button groups combine related buttons into a single visual unit. Use them for toolbars, segmented controls, or any set of actions that belong together. (docs)
  • <wa-copy-button> - Copy buttons copy text to the clipboard when the user activates them. They provide built-in success and error feedback so users know the copy worked. (docs)
  • <wa-dropdown> - Dropdowns display a list of options triggered by a button or other element. They support keyboard navigation, submenus, and checkable items for building menus and context actions. (docs)
  • <wa-dropdown-item> - Dropdown items represent selectable entries within a dropdown menu, including standard actions, checkable items, and submenu triggers. (docs)
  • <wa-qr-code> - QR codes encode a URL or other short text into a scannable image, rendered client-side using the Canvas API. Use them to share links, contact info, or Wi-Fi credentials that visitors can scan with a phone. (docs)

Feedback & Status feedback status link

  • <wa-badge> - Badges draw attention to adjacent content by displaying a status, count, or label. Use them to highlight notifications, categorize items, or flag new activity. (docs)
  • <wa-callout> - Callouts display important messages inline with surrounding content. Use them to highlight tips, warnings, errors, or other information users should not miss. (docs)
  • <wa-progress-bar> - Progress bars show how far along an ongoing operation is as a horizontal fill. Use them for file uploads, multi-step flows, or any task with measurable progress. (docs)
  • <wa-progress-ring> - Progress rings show how far along a determinate operation is using a circular indicator. Use them as a compact alternative to progress bars when horizontal space is limited. (docs)
  • <wa-skeleton> - Skeletons show placeholder shapes where content will appear once it finishes loading, reducing perceived wait time and preventing layout shift. (docs)
  • <wa-spinner> - Spinners indicate that an operation is in progress when the duration is unknown. Use them for loading states where a determinate progress bar isn’t practical. (docs)
  • <wa-tag> - Tags label, categorize, or represent selections with a compact visual marker. Use them for status indicators, filters, or removable chips. (docs)
  • <wa-tooltip> - Tooltips display brief contextual information when the user hovers, focuses, or taps a target element. (docs)

Form Controls form controls link

  • <wa-checkbox> - Checkboxes let users toggle an option on or off, or select multiple items from a list. They also support an indeterminate state for partial selections in groups. (docs)
  • <wa-color-picker> - Color pickers let users choose a color from a visual palette or by entering a value. They support HEX, RGB, HSL, and HSV formats with optional alpha channel and swatch presets. (docs)
  • <wa-input> - Inputs collect single-line data from the user, such as text, numbers, email addresses, and passwords. They support labels, hints, validation, and prefix or suffix slots. (docs)
  • <wa-number-input> - Number inputs let users enter and edit numeric values, with optional stepper buttons for incrementing and decrementing. Use them for quantities, measurements, and other numeric form fields. (docs)
  • <wa-option> - Options represent the individual choices inside a select or similar form control. Each option holds a value and the label shown to the user. (docs)
  • <wa-radio> - Radios represent a single option within a mutually exclusive set. Use them inside a radio group when users must pick exactly one choice from a small list. (docs)
  • <wa-radio-group> - Radio groups wrap a set of radios so they function as a single form control with one shared value. They handle keyboard navigation, labeling, and validation for the group as a whole. (docs)
  • <wa-rating> - Ratings display a numeric score as a row of selectable symbols, typically stars. Use them to capture quick feedback or show an average rating for a product or piece of content. (docs)
  • <wa-select> - Selects let users choose one or more values from a dropdown list of predefined options. Use them in forms when a fixed set of choices needs to fit in limited space. (docs)
  • <wa-slider> - Sliders let users choose a numeric value within a defined range by dragging a thumb along a track. (docs)
  • <wa-switch> - Switches toggle a single setting on or off and apply the change immediately, without requiring a form submission. (docs)
  • <wa-textarea> - Textareas collect multi-line text input from the user, with optional resizing and character counting. (docs)

Imagery imagery link

  • <wa-animated-image> - Animated images display GIFs and WEBPs with controls to play and pause them on demand. Use them when you want motion but need to give users control over when it plays. (docs)
  • <wa-avatar> - Avatars represent a person or object with an image, initials, or icon. Use them in lists, comments, and profiles to give users visual context at a glance. (docs)
  • <wa-carousel> - Carousels display a series of content slides along a horizontal or vertical axis, one or more at a time. Users can navigate between slides with controls, pagination, or autoplay. (docs)
  • <wa-carousel-item> - Carousel items represent individual slides within a carousel. (docs)
  • <wa-comparison> - Comparisons show the visual differences between two pieces of similar content using a draggable divider. Use them for before/after images, design revisions, or side-by-side previews. (docs)
  • <wa-icon> - Icons are scalable vector symbols that represent actions, content, or status throughout your application. They support Font Awesome and custom icon libraries with animation presets. (docs)
  • <wa-zoomable-frame> - Zoomable frames embed iframe content with built-in controls for zooming, panning, and managing interaction. (docs)
  • <wa-breadcrumb> - Breadcrumbs display a trail of links that show users where they are in a site’s hierarchy. They help users understand the current location and navigate back to parent pages. (docs)
  • <wa-breadcrumb-item> - Breadcrumb items represent individual links inside a breadcrumb, typically one per level of the site hierarchy. (docs)
  • <wa-tab> - Tabs label and activate an individual panel inside a tab group. (docs)
  • <wa-tab-group> - Tab groups organize related content into a single container that displays one panel at a time, with tabs for switching between them. (docs)
  • <wa-tab-panel> - Tab panels hold the content shown for a single tab inside a tab group. (docs)
  • <wa-tree> - Trees allow you to display a hierarchical list of selectable tree items. Items with children can be expanded and collapsed as desired by the user. (docs)
  • <wa-tree-item> - Tree items represent a single hierarchical node inside a tree, and can contain nested items that expand and collapse. (docs)

Organization organization link

  • <wa-card> - Cards group related content and actions inside a bordered container. Use them to present products, articles, user profiles, or any self-contained unit of information. (docs)
  • <wa-details> - Details display a brief summary and expand to reveal additional content. Use them to progressively disclose information, group related FAQs, or hide advanced options. (docs)
  • <wa-dialog> - Dialogs appear above the page and require the user’s immediate attention. Use them for confirmations, forms, or focused tasks that interrupt the main flow. (docs)
  • <wa-divider> - Dividers visually separate or group adjacent elements with a horizontal or vertical line. Use them to establish rhythm and hierarchy within menus, toolbars, and layouts. (docs)
  • <wa-drawer> - Drawers slide in from the edge of a container to expose additional options and information without navigating away. Useful for navigation menus, filters, and secondary content. (docs)
  • <wa-page> - Pages scaffold an entire application layout with header, navigation, sidebar, main content, aside, and footer regions. Use them to structure full pages with minimal markup and responsive behavior built in. (docs)
  • <wa-scroller> - Scrollers wrap overflowing content in an accessible container with visual cues that help users recognize and navigate scrollable regions. (docs)
  • <wa-split-panel> - Split panels display two adjacent panels separated by a draggable divider, letting users resize each side to suit their workflow. (docs)

Utilities utilities link

  • <wa-animation> - Animate elements declaratively with nearly 100 baked-in presets, or roll your own with custom keyframes. Powered by the Web Animations API. (docs)
  • <wa-format-bytes> - Formats a number of bytes as a human-readable string with the appropriate unit, such as kB, MB, or GB. Supports both byte and bit units with configurable locale. (docs)
  • <wa-format-date> - Formats a date or time for display using the specified locale and options. Powered by the Intl.DateTimeFormat API for consistent, localized output. (docs)
  • <wa-format-number> - Formats a number for display using the specified locale and options, including currency, percent, and unit styles. Powered by the Intl.NumberFormat API. (docs)
  • <wa-include> - Fetches an external HTML file and embeds its contents inline on the page. Useful for reusing shared markup like headers, footers, and partials across multiple pages. (docs)
  • <wa-intersection-observer> - Tracks immediate child elements and fires events as they move in and out of view. Useful for lazy loading, scroll-triggered animations, and viewport-aware interactions. (docs)
  • <wa-markdown> - Markdown elements render markdown content as HTML directly in the browser, making it easy to display user-generated content or documentation without a server-side build step. (docs)
  • <wa-mutation-observer> - Mutation observers watch for changes to an element’s DOM tree and emit an event when they occur. Provides a thin, declarative interface to the browser’s MutationObserver API. (docs)
  • <wa-popover> - Popovers display contextual content and interactive elements in a floating panel anchored to a trigger. Use them for rich tooltips, menus, or any content that appears on demand without navigating away. (docs)
  • <wa-popup> - Popups declaratively anchor one element to another and keep them positioned together as the page scrolls or resizes. Primarily a low-level building block for popovers, dropdowns, and tooltips. (docs)
  • <wa-relative-time> - Relative times display a date as a localized phrase relative to now, such as “3 hours ago” or “in 2 days”. The phrase updates automatically as time passes and respects the user’s locale. (docs)
  • <wa-resize-observer> - Resize observers watch their slotted elements for size changes and emit an event when they occur. Provides a thin, declarative interface to the browser’s ResizeObserver API. (docs)

Themes themes link

Web Awesome includes pre-built themes. Apply a theme by adding its class to the <html> element.

Free Themes free themes link

  • Default - The foundational theme
  • Awesome - Bright, vibrant color palette
  • Shoelace - Classic Shoelace styling

Pro Themes pro themes link

  • Active - Green branding with rudimentary palette
  • Brutalist - Blue branding with default palette
  • Glossy - Indigo accents with elegant palette
  • Matter - Purple branding with mild palette
  • Mellow - Blue branding with natural palette
  • Playful - Purple branding with rudimentary palette
  • Premium - Cyan branding with anodized palette
  • Tailspin - Indigo accents with vogue palette

See Themes Reference for usage details.

Color Palettes color palettes link

Each palette provides 10 color hues with 11 tints each.

Free Palettes free palettes link

  • Default, Bright, Shoelace

Pro Palettes pro palettes link

  • Rudimentary, Elegant, Mild, Natural, Anodized, Vogue

See Themes Reference for palette usage.

Utilities utilities 1 link

Web Awesome provides CSS utilities for common styling tasks:

  • Layout: wa-stack, wa-cluster, wa-grid, wa-split, wa-flank, wa-frame
  • Spacing: wa-gap-* utilities
  • Text: Typography utilities
  • Color: Color variant utilities
  • Rounding: wa-border-radius-* utilities
  • Accessibility: wa-visually-hidden utilities
  • FOUCE Prevention: wa-cloak utility
  • Native Styles: Enhanced styling for native HTML elements

See Layout Utilities, Rounding, Visually Hidden, FOUCE, and Native Styles.

Design Tokens design tokens link

Web Awesome uses CSS custom properties (design tokens) for consistent theming:

  • Borders: --wa-border-* for width, radius, style
  • Color: --wa-color-* for surfaces, text, semantic colors
  • Space: --wa-space-* for consistent spacing
  • Typography: --wa-font-* for font families, sizes, weights
  • Shadows: --wa-shadow-* for elevation
  • Focus: --wa-focus-* for focus ring styles
  • Transitions: --wa-transition-* for animation timing

See Design Tokens for full reference.

Form Controls form controls 1 link

Web Awesome form controls are form-associated custom elements supporting native form validation and the Constraint Validation API.

  • Use required, pattern, minlength, maxlength attributes
  • Use setCustomValidity() for custom error messages
  • Style validation states with :state(valid), :state(invalid), etc.

See Form Controls Reference for details.

Icons icons link

Font Awesome is the default icon library. Use <wa-icon> with Font Awesome icon names:

<wa-icon name="house"></wa-icon>
<wa-icon name="gear"></wa-icon>
<wa-icon name="check"></wa-icon>

Framework Integration framework integration link

Web Awesome works with any framework:

  • React 19+: Native custom element support with TypeScript types
  • React 18 and below: Use provided React wrappers
  • Vue: Works out of the box
  • Angular: Works out of the box
  • Svelte: Works out of the box

See framework-specific guides in references/frameworks/.

Pro Features pro features link

Web Awesome Pro includes:

  • Pro Components (Data Grid, Date Picker, Rich Text Editor, etc.)
  • Pro Themes and Color Palettes
  • Theme Builder tool
  • Official Figma Design Kit
  • Responsive Layout Tools
  • Pattern Library
  • Priority Support

Support support link

  • GitHub Issues: https://github.com/shoelace-style/webawesome/issues
  • GitHub Discussions: https://github.com/shoelace-style/webawesome/discussions
  • Discord: Community chat and support
  • Email: For account and billing questions

See Support Reference for more details.

Reference Documentation reference documentation link