Shoelace — Framework-Agnostic Web Components for Any Project

Introduction

Shoelace is a collection of professionally designed, accessible web components built on the Web Components standard. Because they use the browser's native component model, Shoelace components work with React, Vue, Angular, Svelte, or plain HTML. The library emphasizes progressive enhancement and full CSS customizability through design tokens.

What Shoelace Does

• Provides 60+ UI components as native custom elements (buttons, modals, tabs, trees, etc.)
• Uses CSS custom properties as design tokens for deep theming without build tools
• Ships light and dark themes with the ability to create custom themes
• Supports form association so custom elements work natively with HTML forms
• Includes an animation system built on the Web Animations API

Architecture Overview

Shoelace components are built with Lit, a lightweight library for creating web components. Each component registers as a custom element and encapsulates its styles in shadow DOM. Design tokens are exposed as CSS custom properties on the :root selector, making global theming straightforward. The component source is authored in TypeScript with decorators for reactive properties.

Self-Hosting & Configuration

• Install via npm and import individual components for tree shaking
• Or use the CDN with the autoloader, which lazy-loads components as they appear in the DOM
• Override design tokens by setting CSS custom properties on :root or scoped containers
• Copy the built assets to your public directory for full self-hosted setups
• Works with any bundler; no framework-specific plugins required

Key Features

• Framework-agnostic: works with React, Vue, Angular, Svelte, and vanilla HTML
• Full accessibility with ARIA attributes and keyboard navigation built in
• Design-token-based theming through CSS custom properties—no Sass or JS needed
• Form-associated custom elements that work with native form validation
• 13k+ GitHub stars and an active community with regular releases

Comparison with Similar Tools

• Radix Primitives — React-only headless components; Shoelace provides styled, framework-agnostic web components
• Headless UI — unstyled and framework-specific (React/Vue); Shoelace ships complete styles and works everywhere
• Material Web — Google's Material Design web components; Shoelace has its own design system with broader theming
• Vuetify / Ant Design — framework-locked component libraries; Shoelace works across all frameworks

FAQ

Q: Can I use Shoelace with React? A: Yes. Shoelace provides a React wrapper package that maps custom element events to React-compatible callbacks.

Q: How does theming work without Sass? A: Themes are pure CSS files that set CSS custom properties. Override any token in your own stylesheet.

Q: Are Shoelace components accessible? A: Yes. Every component includes appropriate ARIA attributes, focus management, and keyboard interaction patterns.

Q: Does shadow DOM prevent global CSS from styling components? A: Shadow DOM isolates internal styles, but Shoelace exposes CSS parts and custom properties for external customization.

Sources

• https://github.com/shoelace-style/shoelace
• https://shoelace.style/