# Web Awesome > A forward-thinking library of web components. Version 3.6.0. Web Awesome provides a comprehensive set of customizable, accessible web components for building modern web applications. All components use shadow DOM and are framework-agnostic, working with vanilla JavaScript or any framework including React, Vue, Angular, and Svelte. Form controls are form-associated custom elements that work with native form validation and the Constraint Validation API. Font Awesome is the default icon library, so `` values should reference Font Awesome icon names. ## Documentation For comprehensive documentation, visit https://webawesome.com/docs/ - [Getting Started](https://webawesome.com/docs/getting-started): Installation and setup guide - [Components Overview](https://webawesome.com/docs/components): Complete component reference - [Theming](https://webawesome.com/docs/theming): Customization and design tokens - [Form Controls](https://webawesome.com/docs/form-controls): Form integration and validation ## Components - [Animated Image](https://webawesome.com/docs/components/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. - [Animation](https://webawesome.com/docs/components/animation): Animate elements declaratively with nearly 100 baked-in presets, or roll your own with custom keyframes. Powered by the Web Animations API. - [Avatar](https://webawesome.com/docs/components/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. - [Badge](https://webawesome.com/docs/components/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. - [Breadcrumb](https://webawesome.com/docs/components/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. - [Breadcrumb Item](https://webawesome.com/docs/components/breadcrumb-item): Breadcrumb items represent individual links inside a breadcrumb, typically one per level of the site hierarchy. - [Button](https://webawesome.com/docs/components/button): Buttons represent actions the user can take, such as submitting a form, opening a dialog, or navigating to another page. - [Button Group](https://webawesome.com/docs/components/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. - [Callout](https://webawesome.com/docs/components/callout): Callouts display important messages inline with surrounding content. Use them to highlight tips, warnings, errors, or other information users should not miss. - [Card](https://webawesome.com/docs/components/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. - [Carousel](https://webawesome.com/docs/components/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. - [Carousel Item](https://webawesome.com/docs/components/carousel-item): Carousel items represent individual slides within a carousel. - [Checkbox](https://webawesome.com/docs/components/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. - [Color Picker](https://webawesome.com/docs/components/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. - [Comparison](https://webawesome.com/docs/components/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. - [Copy Button](https://webawesome.com/docs/components/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. - [Details](https://webawesome.com/docs/components/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. - [Dialog](https://webawesome.com/docs/components/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. - [Divider](https://webawesome.com/docs/components/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. - [Drawer](https://webawesome.com/docs/components/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. - [Dropdown](https://webawesome.com/docs/components/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. - [Dropdown Item](https://webawesome.com/docs/components/dropdown-item): Dropdown items represent selectable entries within a dropdown menu, including standard actions, checkable items, and submenu triggers. - [Format Bytes](https://webawesome.com/docs/components/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. - [Format Date](https://webawesome.com/docs/components/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. - [Format Number](https://webawesome.com/docs/components/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. - [Icon](https://webawesome.com/docs/components/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. - [Include](https://webawesome.com/docs/components/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. - [Input](https://webawesome.com/docs/components/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. - [Intersection Observer](https://webawesome.com/docs/components/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. - [Markdown](https://webawesome.com/docs/components/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. - [Mutation Observer](https://webawesome.com/docs/components/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. - [Number Input](https://webawesome.com/docs/components/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. - [Option](https://webawesome.com/docs/components/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. - [Page](https://webawesome.com/docs/components/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. - [Popover](https://webawesome.com/docs/components/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. - [Popup](https://webawesome.com/docs/components/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. - [Progress Bar](https://webawesome.com/docs/components/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. - [Progress Ring](https://webawesome.com/docs/components/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. - [QR Code](https://webawesome.com/docs/components/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. - [Radio](https://webawesome.com/docs/components/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. - [Radio Group](https://webawesome.com/docs/components/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. - [Rating](https://webawesome.com/docs/components/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. - [Relative Time](https://webawesome.com/docs/components/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. - [Resize Observer](https://webawesome.com/docs/components/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. - [Scroller](https://webawesome.com/docs/components/scroller): Scrollers wrap overflowing content in an accessible container with visual cues that help users recognize and navigate scrollable regions. - [Select](https://webawesome.com/docs/components/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. - [Skeleton](https://webawesome.com/docs/components/skeleton): Skeletons show placeholder shapes where content will appear once it finishes loading, reducing perceived wait time and preventing layout shift. - [Slider](https://webawesome.com/docs/components/slider): Sliders let users choose a numeric value within a defined range by dragging a thumb along a track. - [Spinner](https://webawesome.com/docs/components/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. - [Split Panel](https://webawesome.com/docs/components/split-panel): Split panels display two adjacent panels separated by a draggable divider, letting users resize each side to suit their workflow. - [Switch](https://webawesome.com/docs/components/switch): Switches toggle a single setting on or off and apply the change immediately, without requiring a form submission. - [Tab](https://webawesome.com/docs/components/tab): Tabs label and activate an individual panel inside a tab group. - [Tab Group](https://webawesome.com/docs/components/tab-group): Tab groups organize related content into a single container that displays one panel at a time, with tabs for switching between them. - [Tab Panel](https://webawesome.com/docs/components/tab-panel): Tab panels hold the content shown for a single tab inside a tab group. - [Tag](https://webawesome.com/docs/components/tag): Tags label, categorize, or represent selections with a compact visual marker. Use them for status indicators, filters, or removable chips. - [Textarea](https://webawesome.com/docs/components/textarea): Textareas collect multi-line text input from the user, with optional resizing and character counting. - [Tooltip](https://webawesome.com/docs/components/tooltip): Tooltips display brief contextual information when the user hovers, focuses, or taps a target element. - [Tree](https://webawesome.com/docs/components/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. - [Tree Item](https://webawesome.com/docs/components/tree-item): Tree items represent a single hierarchical node inside a tree, and can contain nested items that expand and collapse. - [Zoomable Frame](https://webawesome.com/docs/components/zoomable-frame): Zoomable frames embed iframe content with built-in controls for zooming, panning, and managing interaction. ## Optional The following is a quick reference describing every component's API. For comprehensive documentation, refer to the component documentation using the URLs provided above. #### `` **Description:** 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. **Documentation:** https://webawesome.com/docs/components/animated-image **Slots:** - `play-icon`: Optional play icon to use instead of the default. Works best with ``. - `pause-icon`: Optional pause icon to use instead of the default. Works best with ``. **Properties:** - `css`: One or more CSSResultGroup to include in the component's shadow root. Host styles are automatically prepended. (Type: `CSSResultGroup | undefined`, Default: `styles`) - `src`: The path to the image to load. (Type: `string`) - `alt`: A description of the image used by assistive devices. (Type: `string`) - `play`: Plays the animation. When this attribute is remove, the animation will pause. (Type: `boolean`) **Events:** - `wa-load`: Emitted when the image loads successfully. - `wa-error`: Emitted when the image fails to load. **CSS Custom Properties:** - `--control-box-size`: The size of the icon box. - `--icon-size`: The size of the play/pause icons. **CSS Parts:** - `control-box`: The container that surrounds the pause/play icons and provides their background. #### `` **Description:** Animate elements declaratively with nearly 100 baked-in presets, or roll your own with custom keyframes. Powered by the Web Animations API. **Documentation:** https://webawesome.com/docs/components/animation **Slots:** - `(default)`: The element to animate. Avoid slotting in more than one element, as subsequent ones will be ignored. To animate multiple elements, either wrap them in a single container or use multiple `` elements. **Properties:** - `css`: One or more CSSResultGroup to include in the component's shadow root. Host styles are automatically prepended. (Type: `CSSResultGroup | undefined`, Default: `styles`) - `name`: The name of the built-in animation to use. For custom animations, use the `keyframes` prop. (Type: `string`, Default: `'none'`) - `play`: Plays the animation. When omitted, the animation will be paused. This attribute will be automatically removed when the animation finishes or gets canceled. (Type: `boolean`, Default: `false`) - `delay`: The number of milliseconds to delay the start of the animation. (Type: `number`, Default: `0`) - `direction`: Determines the direction of playback as well as the behavior when reaching the end of an iteration. [Learn more](https://developer.mozilla.org/en-US/docs/Web/CSS/animation-direction) (Type: `PlaybackDirection`, Default: `'normal'`) - `duration`: The number of milliseconds each iteration of the animation takes to complete. (Type: `number`, Default: `1000`) - `easing`: The easing function to use for the animation. This can be a Web Awesome easing function or a custom easing function such as `cubic-bezier(0, 1, .76, 1.14)`. (Type: `string`, Default: `'linear'`) - `endDelay` (attribute: `end-delay`): The number of milliseconds to delay after the active period of an animation sequence. (Type: `number`, Default: `0`) - `fill`: Sets how the animation applies styles to its target before and after its execution. (Type: `FillMode`, Default: `'auto'`) - `iterations`: The number of iterations to run before the animation completes. Defaults to `Infinity`, which loops. (Type: `number`, Default: `Infinity`) - `iterationStart` (attribute: `iteration-start`): The offset at which to start the animation, usually between 0 (start) and 1 (end). (Type: `number`, Default: `0`) - `keyframes`: The keyframes to use for the animation. If this is set, `name` will be ignored. (Type: `Keyframe[] | undefined`) - `playbackRate` (attribute: `playback-rate`): Sets the animation's playback rate. The default is `1`, which plays the animation at a normal speed. Setting this to `2`, for example, will double the animation's speed. A negative value can be used to reverse the animation. This value can be changed without causing the animation to restart. (Type: `number`, Default: `1`) - `currentTime`: Gets and sets the current animation time. (Type: `CSSNumberish`) **Methods:** - `cancel()`: Clears all keyframe effects caused by this animation and aborts its playback. - `finish()`: Sets the playback time to the end of the animation corresponding to the current playback direction. **Events:** - `wa-cancel`: Emitted when the animation is canceled. - `wa-finish`: Emitted when the animation finishes. - `wa-start`: Emitted when the animation starts or restarts. #### `` **Description:** 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. **Documentation:** https://webawesome.com/docs/components/avatar **Slots:** - `icon`: The default icon to use when no image or initials are present. Works best with ``. **Properties:** - `css`: One or more CSSResultGroup to include in the component's shadow root. Host styles are automatically prepended. (Type: `CSSResultGroup | undefined`, Default: `styles`) - `image`: The image source to use for the avatar. (Type: `string`, Default: `''`) - `label`: A label to use to describe the avatar to assistive devices. (Type: `string`, Default: `''`) - `initials`: Initials to use as a fallback when no image is available (1-2 characters max recommended). (Type: `string`, Default: `''`) - `loading`: Indicates how the browser should load the image. (Type: `'eager' | 'lazy'`, Default: `'eager'`) - `shape`: The shape of the avatar. (Type: `'circle' | 'square' | 'rounded'`, Default: `'circle'`) **Events:** - `wa-error`: The image could not be loaded. This may because of an invalid URL, a temporary network condition, or some unknown cause. **CSS Custom Properties:** - `--size`: The size of the avatar. **CSS Parts:** - `icon`: The container that wraps the avatar's icon. - `initials`: The container that wraps the avatar's initials. - `image`: The avatar image. Only shown when the `image` attribute is set. #### `` **Description:** Badges draw attention to adjacent content by displaying a status, count, or label. Use them to highlight notifications, categorize items, or flag new activity. **Documentation:** https://webawesome.com/docs/components/badge **Slots:** - `(default)`: The badge's content. - `start`: An element, such as ``, placed before the label. - `end`: An element, such as ``, placed after the label. **Properties:** - `css`: One or more CSSResultGroup to include in the component's shadow root. Host styles are automatically prepended. (Type: `CSSResultGroup | undefined`, Default: `[variantStyles, styles]`) - `variant`: The badge's theme variant. Defaults to `brand` if not within another element with a variant. (Type: `'brand' | 'neutral' | 'success' | 'warning' | 'danger'`, Default: `'brand'`) - `appearance`: The badge's visual appearance. (Type: `'accent' | 'filled' | 'outlined' | 'filled-outlined'`, Default: `'accent'`) - `pill`: Draws a pill-style badge with rounded edges. (Type: `boolean`, Default: `false`) - `attention`: Adds an animation to draw attention to the badge. (Type: `'none' | 'pulse' | 'bounce'`, Default: `'none'`) **CSS Custom Properties:** - `--pulse-color`: The color of the badge's pulse effect when using `attention="pulse"`. **CSS Parts:** - `base`: The component's base wrapper. - `start`: The container that wraps the `start` slot. - `end`: The container that wraps the `end` slot. #### `` **Description:** 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. **Documentation:** https://webawesome.com/docs/components/breadcrumb **Slots:** - `(default)`: One or more breadcrumb items to display. - `separator`: The separator to use between breadcrumb items. Works best with ``. **Properties:** - `css`: One or more CSSResultGroup to include in the component's shadow root. Host styles are automatically prepended. (Type: `CSSResultGroup | undefined`, Default: `styles`) - `label`: The label to use for the breadcrumb control. This will not be shown on the screen, but it will be announced by screen readers and other assistive devices to provide more context for users. (Type: `string`, Default: `''`) **CSS Parts:** - `base`: The component's base wrapper. #### `` **Description:** Breadcrumb items represent individual links inside a breadcrumb, typically one per level of the site hierarchy. **Documentation:** https://webawesome.com/docs/components/breadcrumb-item **Slots:** - `(default)`: The breadcrumb item's label. - `start`: An element, such as ``, placed before the label. - `end`: An element, such as ``, placed after the label. - `separator`: The separator to use for the breadcrumb item. This will only change the separator for this item. If you want to change it for all items in the group, set the separator on `` instead. **Properties:** - `css`: One or more CSSResultGroup to include in the component's shadow root. Host styles are automatically prepended. (Type: `CSSResultGroup | undefined`, Default: `styles`) - `href`: Optional URL to direct the user to when the breadcrumb item is activated. When set, a link will be rendered internally. When unset, a button will be rendered instead. (Type: `string | undefined`) - `target`: Tells the browser where to open the link. Only used when `href` is set. (Type: `'_blank' | '_parent' | '_self' | '_top' | undefined`) - `rel`: The `rel` attribute to use on the link. Only used when `href` is set. (Type: `string`, Default: `'noreferrer noopener'`) **CSS Parts:** - `label`: The breadcrumb item's label. - `start`: The container that wraps the `start` slot. - `end`: The container that wraps the `end` slot. - `separator`: The container that wraps the separator. #### `` **Description:** Buttons represent actions the user can take, such as submitting a form, opening a dialog, or navigating to another page. **Documentation:** https://webawesome.com/docs/components/button **Slots:** - `(default)`: The button's label. - `start`: An element, such as ``, placed before the label. - `end`: An element, such as ``, placed after the label. **Properties:** - `css`: One or more CSSResultGroup to include in the component's shadow root. Host styles are automatically prepended. (Type: `CSSResultGroup | undefined`, Default: `[styles, variantStyles, sizeStyles]`) - `validators`: Validators are static because they have `observedAttributes`, essentially attributes to "watch" for changes. Whenever these attributes change, we want to be notified and update the validator. (Type: `Validator[]`, Default: `[]`) - `variant`: The button's theme variant. Defaults to `neutral` if not within another element with a variant. (Type: `'neutral' | 'brand' | 'success' | 'warning' | 'danger'`, Default: `'neutral'`) - `appearance`: The button's visual appearance. (Type: `'accent' | 'filled' | 'outlined' | 'filled-outlined' | 'plain'`, Default: `'accent'`) - `size`: The button's size. (Type: `'xs' | 's' | 'm' | 'l' | 'xl' | 'small' | 'medium' | 'large'`, Default: `'m'`) - `withCaret` (attribute: `with-caret`): Draws the button with a caret. Used to indicate that the button triggers a dropdown menu or similar behavior. (Type: `boolean`, Default: `false`) - `withStart` (attribute: `with-start`): Only required for SSR. Set to `true` if you're slotting in a `start` element so the server-rendered markup includes the start slot before the component hydrates on the client. (Type: `boolean`, Default: `false`) - `withEnd` (attribute: `with-end`): Only required for SSR. Set to `true` if you're slotting in an `end` element so the server-rendered markup includes the end slot before the component hydrates on the client. (Type: `boolean`, Default: `false`) - `disabled`: Disables the button. (Type: `boolean`, Default: `false`) - `loading`: Draws the button in a loading state. (Type: `boolean`, Default: `false`) - `pill`: Draws a pill-style button with rounded edges. (Type: `boolean`, Default: `false`) - `type`: The type of button. Note that the default value is `button` instead of `submit`, which is opposite of how native `