Webawesome

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.

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

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

For complete usage details, see Usage Guide.

Components

Free Components

Actions

• <wa-button> - Buttons represent actions that are available to the user. (docs)
• <wa-button-group> - Button groups can be used to group related buttons into sections. (docs)
• <wa-copy-button> - Copies data to the clipboard when the user clicks the button. (docs)
• <wa-dropdown> - Dropdowns expose additional content that "drops down" in a panel. (docs)
• <wa-dropdown-item> - Provides items to select in a dropdown. (docs)
• <wa-qr-code> - Generates a QR code and renders it using the Canvas API. (docs)

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-page> - Pages offer an easy way to scaffold entire page layouts using minimal markup. (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-markdown> - A declarative utility that renders markdown in plain ol' HTML pages. (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)

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

• 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

• Installation Guide
• Usage Guide
• Form Controls
• Customizing
• Localization
• Themes & Palettes
• Layout Utilities
• Native Styles
• Design Tokens - Borders, Color, Space, Typography, Shadows, Focus, Transitions
• Framework Guides

Source: violit-dev/violit — distributed by TomeVault.