| name | webawesome |
| description | 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. |
| license | MIT / Commercial (for Web Awesome Pro) |
| metadata | {"author":"Web Awesome","version":"3.4.0","homepage":"https://webawesome.com","repository":"https://github.com/shoelace-style/webawesome"} |
| compatibility | Works in modern browsers. Requires no build tools when using CDN. Works with bundlers like Webpack and Vite when installed via npm. |
| allowed-tools | Read |
Web Awesome
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
npm Installation
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
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
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.
<wa-input></wa-input>
<wa-input />
For complete usage details, see Usage Guide.
Components
Free Components
Actions
Feedback & Status
<wa-badge> - Badges are used to draw attention and display statuses or counts. (docs)<wa-callout> - Callouts are used to display important messages inline. (docs)<wa-progress-bar> - Progress bars are used to show the status of an ongoing operation. (docs)<wa-progress-ring> - Progress rings are used to show the progress of a determinate operation in a circular fashion. (docs)<wa-skeleton> - Skeletons are used to provide a visual representation of where content will eventually be drawn. (docs)<wa-spinner> - Spinners are used to show the progress of an indeterminate operation. (docs)<wa-tag> - Tags are used as labels to organize things or to indicate a selection. (docs)<wa-tooltip> - Tooltips display additional information based on a specific action. (docs)
Form Controls
<wa-checkbox> - Checkboxes allow the user to toggle an option on or off. (docs)<wa-color-picker> - Color pickers allow the user to select a color. (docs)<wa-input> - Inputs collect data from the user. (docs)<wa-number-input> - Number inputs allow users to enter and edit numeric values with optional stepper buttons. (docs)<wa-option> - Options define the selectable items within various form controls such as select. (docs)<wa-radio> - Radios allow the user to select a single option from a group. (docs)<wa-radio-group> - Radio groups are used to group multiple radios so they function as a single form control. (docs)<wa-rating> - Ratings give users a way to quickly view and provide feedback. (docs)<wa-select> - Selects allow you to choose items from a menu of predefined options. (docs)<wa-slider> - Ranges allow the user to select a single value within a given range using a slider. (docs)<wa-switch> - Switches allow the user to toggle an option on or off. (docs)<wa-textarea> - Textareas collect data from the user and allow multiple lines of text. (docs)
Imagery
<wa-animated-image> - A component for displaying animated GIFs and WEBPs that play and pause on interaction. (docs)<wa-avatar> - Avatars are used to represent a person or object. (docs)<wa-carousel> - Carousels display an arbitrary number of content slides along a horizontal or vertical axis. (docs)<wa-carousel-item> - A carousel item represent a slide within a carousel. (docs)<wa-comparison> - Compare visual differences between similar content with a sliding panel. (docs)<wa-icon> - Icons are symbols that can be used to represent various options within an application. (docs)<wa-zoomable-frame> - Zoomable frames render iframe content with zoom and interaction controls. (docs)
Navigation
<wa-breadcrumb> - Breadcrumbs provide a group of links so users can easily navigate a website's hierarchy. (docs)<wa-breadcrumb-item> - Breadcrumb Items are used inside breadcrumbs to represent different links. (docs)<wa-tab> - Tabs are used inside tab groups to represent and activate tab panels. (docs)<wa-tab-group> - Tab groups organize content into a container that shows one section at a time. (docs)<wa-tab-panel> - Tab panels are used inside tab groups to display tabbed content. (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> - A tree item serves as a hierarchical node that lives inside a tree. (docs)
Organization
<wa-card> - Cards can be used to group related subjects in a container. (docs)<wa-details> - Details show a brief summary and expand to show additional content. (docs)<wa-dialog> - Dialogs, sometimes called "modals", appear above the page and require the user's immediate attention. (docs)<wa-divider> - Dividers are used to visually separate or group elements. (docs)<wa-drawer> - Drawers slide in from a container to expose additional options and information. (docs)<wa-scroller> - Scrollers create an accessible container while providing visual cues that help users identify and navigate through content that scrolls. (docs)<wa-split-panel> - Split panels display two adjacent panels, allowing the user to reposition them. (docs)
Utilities
<wa-animation> - Animate elements declaratively with nearly 100 baked-in presets, or roll your own with custom keyframes. (docs)<wa-format-bytes> - Formats a number as a human readable bytes value. (docs)<wa-format-date> - Formats a date/time using the specified locale and options. (docs)<wa-format-number> - Formats a number using the specified locale and options. (docs)<wa-include> - Includes give you the power to embed external HTML files into the page. (docs)<wa-intersection-observer> - Tracks immediate child elements and fires events as they move in and out of view. (docs)<wa-mutation-observer> - The Mutation Observer component offers a thin, declarative interface to the MutationObserver API. (docs)<wa-popover> - Popovers display interactive content when their anchor element is clicked. (docs)<wa-popup> - Popup is a utility that lets you declaratively anchor "popup" containers to another element. (docs)<wa-relative-time> - Outputs a localized time phrase relative to the current date and time. (docs)<wa-resize-observer> - The Resize Observer component offers a thin, declarative interface to the ResizeObserver API. (docs)
Pro Components
These components require Web Awesome Pro.
Data Visualization
<wa-bar-chart> [Pro] - They work well for comparing quantities across categories, showing rankings, and highlighting differences between groups. (docs)<wa-bubble-chart> [Pro] - They are useful for visualizing relationships where a third variable adds meaning beyond a simple x/y correlation. (docs)<wa-chart> [Pro] - Use this component for advanced configuration such as mixed chart types, custom plugins, and direct Chart.js access. (docs)<wa-doughnut-chart> [Pro] - They offer a cleaner look than pie charts that works well in dashboards, and are best suited for a small number of categories. (docs)<wa-line-chart> [Pro] - Use them when the x-axis represents a sequential dimension and you want to emphasize the shape and direction of the data. (docs)<wa-pie-chart> [Pro] - They work best with a small number of categories where the relative proportions matter more than exact values. (docs)<wa-polar-area-chart> [Pro] - Unlike pie charts, each segment has an equal angle while the radius varies, making them useful for comparing magnitudes without visual bias. (docs)<wa-radar-chart> [Pro] - They are well-suited for comparing profiles across several dimensions, such as skill assessments, product attributes, or performance metrics. (docs)<wa-scatter-chart> [Pro] - They are ideal for identifying correlations, clusters, and outliers in datasets. (docs)<wa-sparkline> [Pro] - Sparklines display inline data trends as compact, visual charts. (docs)
Feedback & Status
<wa-toast> [Pro] - Toasts display brief, non-blocking notifications that appear temporarily above the page content. (docs)<wa-toast-item> [Pro] - Toast items are individual notifications displayed within a toast container. (docs)
Form Controls
<wa-combobox> [Pro] - Comboboxes combine a text input with a listbox, allowing users to filter and select from predefined options or enter custom values. (docs)<wa-file-input> [Pro] - File inputs allow users to select files from their device. (docs)
Organization
<wa-page> [Pro] - Pages offer an easy way to scaffold entire page layouts using minimal markup. (docs)
Themes
Web Awesome includes pre-built themes. Apply a theme by adding its class to the <html> element.
Free Themes
- Default - The foundational theme
- Awesome - Bright, vibrant color palette
- Shoelace - Classic Shoelace styling
Pro Themes
- 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
Each palette provides 10 color hues with 11 tints each.
Free Palettes
- Default, Bright, Shoelace
Pro Palettes
- Rudimentary, Elegant, Mild, Natural, Anodized, Vogue
See Themes Reference for palette usage.
Utilities
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
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
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
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
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
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
See Support Reference for more details.
Reference Documentation
