Integrating Shoelace Web Components into Your Design System
Writing UI components from scratch is expensive. Every button, input, or dialog requires design, markup, accessibility testing, and cross-browser validation. If your project spans multiple frameworks (React, Vue, Angular), effort scales linearly. Shoelace (now Web Awesome) solves this: a ready library of 50+ Web Components, framework-agnostic. It customizes via CSS variables and parts, supports dark theme, and meets WCAG standards.
Our team has implemented Shoelace in 30+ projects — from startups to enterprise systems. Below we break down how integrating Shoelace speeds up development by 3–5x and why it beats custom development.
Why Shoelace Cuts Development Time by 3–5x
Let's compare: writing a single 'Select' component from scratch takes 3–5 days including testing and a11y. Shoelace gives a ready <sl-select> with keyboard support, ARIA attributes, and dark theme. You only need to override brand colors via CSS variables. Result: 2–4 days for the entire library instead of 2–3 months for your own.
Comparison of costs:
| Characteristic | Custom components | Shoelace |
|---|---|---|
| Development time (50 components) | 2–3 months | 2–4 days |
| Number of components | 10–20 | 50+ |
| Accessibility (a11y) | Requires separate work | Built-in (WCAG 2.1 AA) |
| Theme support | Need to implement | Built-in via CSS variables |
| Updates and bugfixes | Self-managed | Community and authors |
| Annual cost of ownership | High | $0 (free license) |
Development savings exceed 60% already on the first project. Migrating to Shoelace pays off through reduced development time and lower maintenance costs.
How to Integrate Shoelace with React
Integrating Shoelace with React requires minimal code:
- Install the package:
npm install @shoelace-style/shoelace - Register the needed components in a separate file (e.g.,
shoelace-setup.ts). We use cherry-pick imports with tree-shaking to reduce the bundle by 10x compared to full import. - Import the theme and configure the asset path.
Example of a typed React modal component:
import { useRef } from 'react' import type SlDialog from '@shoelace-style/shoelace/dist/components/dialog/dialog.js' import '../shoelace-setup' export function ContactModal() { const dialogRef = useRef<SlDialog>(null) const openDialog = () => dialogRef.current?.show() const closeDialog = () => dialogRef.current?.hide() const handleSubmit = async (e: React.FormEvent) => { e.preventDefault() // обработка формы closeDialog() } return ( <> <sl-button variant="primary" onClick={openDialog}> Написать нам </sl-button> <sl-dialog ref={dialogRef} label="Контактная форма"> <form onSubmit={handleSubmit}> <sl-input label="Имя" required placeholder="Иван Иванов" style={{ marginBottom: '16px' }} /> <sl-input label="Email" type="email" required placeholder="[email protected]" style={{ marginBottom: '16px' }} /> <sl-textarea label="Сообщение" rows={4} required /> </form> <sl-button slot="footer" variant="default" onClick={closeDialog}>Отмена</sl-button> <sl-button slot="footer" variant="primary" type="submit">Отправить</sl-button> </sl-dialog> </> ) } For JSX typing, add module declarations for all components. These can be generated via custom-elements.json shipped with the library.
Customization for Your Brand
Shoelace is built on design tokens. Override colors, fonts, radii, and other CSS variables — and the whole library changes appearance. For precise styling, use CSS parts (::part()). We also prepare a styling guide with examples for your team.
/* Global tokens */ :root { --sl-color-primary-600: hsl(262, 75%, 45%); --sl-font-sans: 'Inter', system-ui, sans-serif; --sl-border-radius-medium: 8px; --sl-transition-medium: 200ms ease; } /* Single button styling */ sl-button::part(base) { font-weight: 700; text-transform: uppercase; letter-spacing: 0.02em; } sl-button[variant="primary"]::part(base) { background: linear-gradient(135deg, #7000ff, #b600ff); border: none; } Dark Theme in 5 Minutes
Theme switching is implemented by adding the sl-theme-dark or sl-theme-light class to <html>. We connect the saved theme from localStorage and respect prefers-color-scheme. The entire initialization code is 10 lines.
Learn more about theming in the official Shoelace documentation: https://shoelace.style/getting-started/themes
Implementation Process
| Stage | Duration |
|---|---|
| Analysis of design system and requirements | 1–2 days |
| Shoelace setup and cherry-pick imports | 1 day |
| Brand customization (CSS variables, parts) | 1–2 days |
| React/Vue integration and testing | 1–2 days |
| Documentation and team training | 1 day |
| Support and warranty | within a month |
What's Included
- Shoelace setup with cherry-pick imports (tree-shaking) — bundle size reduced 10x.
- Customization of all components to your design system.
- Integration with your framework (React, Vue, Angular).
- Dark and light theme support.
- Usage and customization documentation.
- Team training (2–3 hours).
- Compatibility guarantee and free updates for one month.
Typical Mistakes and How to Avoid Them
- Importing the entire library instead of cherry-pick — increases bundle 10x.
- Ignoring CSS variables — styling via parts without tokens leads to code duplication.
- Missing TypeScript types — without declarations, components won't work in JSX.
We have prepared an integration checklist that we will share with you after the audit.
Request a consultation — we'll analyze your design system and propose a Shoelace implementation plan with cost savings calculation. Get a free audit of your current UI and an estimate of development time reduction. Save resources — use ready-made components.