Webcomponent edu-webcomponents following open-wc recommendations
npm install edu-webcomponents


A modern, lightweight collection of reusable web components built with Lit following open-wc recommendations.
๐ View Live Demo & Documentation
- ๐ Lightweight - Built with Lit for minimal bundle size
- โฟ Accessible - ARIA-compliant components with keyboard support
- ๐ฏ Framework-agnostic - Works with any JavaScript framework or vanilla JS
- ๐จ Customizable - CSS custom properties for easy theming
- ๐ Dark mode support - Automatic theme switching with @media (prefers-color-scheme: dark)
- ๐ฆ Tree-shakeable - Import only what you need
- โ
Well-tested - Comprehensive test coverage
``bash`
npm install edu-webcomponents
Import all components:
`html
`
Or import individual components:
`html
`
A full-width notification banner for displaying important messages and alerts with multiple types and positioning options.
Properties:
- type (String) - Banner type: 'info', 'success', 'warning', 'error', or 'neutral' (default: 'info')message
- (String) - Banner message content (default: '')dismissible
- (Boolean) - Shows close button to dismiss the banner (default: false)position
- (String) - Position variant: 'static', 'sticky', or 'fixed' (default: 'static')icon
- (String) - Custom icon (uses default icon per type if not provided)aria-label
- (String) - Accessibility label
Accessibility:
- Uses role="alert" for immediate screen reader announcements
- Customizable ARIA labels for context
- Keyboard-accessible close button with visible focus indicators
- Semantic color choices with sufficient contrast ratios
- Full dark mode support
Usage:
`html
message="This is an informational message">
message="Your changes have been saved successfully!">
message="Your session will expire in 5 minutes"
dismissible>
message="Unable to process your request. Please try again.">
message="New features available!"
position="sticky"
dismissible>
message="Scheduled maintenance tonight at 10 PM"
position="fixed">
message="Achievement unlocked!"
icon="๐">
`
JavaScript:
`javascript
import { EduBanner } from 'edu-webcomponents';
const banner = document.querySelector('edu-banner');
// Listen for close event
banner.addEventListener('banner-close', () => {
console.log('Banner dismissed');
});
// Programmatically update banner
banner.message = 'Updated message';
banner.type = 'error';
`
---
A lightweight toast notification for brief status messages, with positioning, auto-hide, and dismissal options.
Properties:
- message (String) - Toast message content (default: '')type
- (String) - Toast type: 'info', 'success', 'warning', 'error', or 'neutral' (default: 'info')duration
- (Number) - Auto-hide duration in ms (0 disables auto-hide) (default: 3000)open
- (Boolean) - Shows or hides the toast (default: false)dismissible
- (Boolean) - Shows close button (default: false)position
- (String) - Position: 'top-right', 'top-left', 'bottom-right', 'bottom-left' (default: 'top-right')aria-label
- (String) - Accessibility label
Accessibility:
- Uses role="status" (or role="alert" for error) with aria-live for announcements
- Customizable ARIA labels for context
- Keyboard-accessible close button with visible focus indicators
- Semantic color choices with sufficient contrast ratios
- Full dark mode support
Usage:
`html
message="Changes saved"
duration="3000"
open
dismissible
>
message="Something went wrong"
duration="0"
open
dismissible
position="bottom-left"
>
`
JavaScript:
`javascript
import { EduToast } from 'edu-webcomponents';
const toast = document.querySelector('edu-toast');
toast.message = 'Saved!';
toast.type = 'success';
toast.duration = 3000;
toast.show();
`
---
A small status indicator or label component perfect for displaying counts, categories, or status information.
Properties:
- text (String) - Badge text content (default: '')variant
- (String) - Color variant: 'default', 'primary', 'success', 'warning', 'error', or 'info' (default: 'default')size
- (String) - Size variant: 'small', 'medium', or 'large' (default: 'medium')aria-label
- (String) - Accessibility labelaria-live
- (String) - Announces dynamic changes to screen readers: 'polite' or 'assertive'decorative
- (Boolean) - Marks badge as decorative (hidden from screen readers)
Accessibility:
- Uses role="status" for screen reader announcements (non-decorative badges)aria-live
- Supports attribute for dynamic content announcementsaria-atomic="true"
- Automatically adds when aria-live is setdecorative
- Decorative mode ( property) hides badge from screen readers with aria-hidden="true"
- Customizable ARIA labels for better context
- Semantic color choices with sufficient contrast ratios
- Full dark mode support with optimized color schemes
Usage:
`html
Messages
variant="primary"
size="small"
aria-live="polite"
aria-label="5 unread messages">
`
JavaScript:
`javascript
import { EduBadge } from 'edu-webcomponents';
const badge = document.querySelector('edu-badge');
badge.text = '10';
badge.variant = 'error';
`
---
A customizable button component with hover effects and disabled state.
Properties:
- text (String) - Button text content (default: 'Default text')type
- (String) - Button type attribute (default: 'button')disabled
- (Boolean) - Whether the button is disabled (default: false)aria-label
- (String) - Accessibility label
Accessibility:
- WCAG-compliant touch targets (44ร44px minimum)
- Clear focus indicators with focus-visible
- Proper ARIA labels and disabled state
- Keyboard accessible
Usage:
`html
type="submit"
aria-label="Submit the form">
`
JavaScript:
`javascript
import { EduButton } from 'edu-webcomponents';
const button = document.querySelector('edu-button');
button.addEventListener('click', () => {
console.log('Button clicked!');
});
`
---
A horizontal divider to visually separate content sections.
Properties:
- label (String) - Optional text label displayed in the center (default: '')
Accessibility:
- Uses semantic separator role with aria-orientation
- Decorative visual elements hidden from screen readers
- Optional label for additional context
Usage:
`html
`
---
An animated circular loading spinner with smooth rotation animation. Includes screen reader announcements and respects reduced motion preferences.
Properties:
- label (String) - Screen reader label for the loading state (default: 'Loading')
Accessibility:
- Announces loading state to screen readers with role="status"prefers-reduced-motion
- Slows animation speed when is enabled
- Customizable label for context-specific loading messages
Usage:
`html
`
---
A progress bar component to visualize task completion or loading progress.
Properties:
- value (Number) - Current progress value (default: 0)max
- (Number) - Maximum value (default: 100)showLabel
- (Boolean) - Whether to display percentage label (default: false)progressbarName
- (String) - Accessibility label (default: 'Progress bar')
Accessibility:
- Full ARIA progressbar implementation with role="progressbar"aria-valuenow
- Dynamic , aria-valuemin, and aria-valuemax attributes
- Customizable labels for context-specific progress tracking
Usage:
`html
max="100"
showLabel>
max="5"
showLabel
progressbarName="File upload progress">
`
JavaScript:
`javascript
const progressBar = document.querySelector('edu-progress-bar');
let progress = 0;
const interval = setInterval(() => {
progress += 10;
progressBar.value = progress;
if (progress >= 100) {
clearInterval(interval);
}
}, 500);
`
---
Animated skeleton loader for content placeholders during loading states. Includes screen reader announcements and respects reduced motion preferences.
Properties:
- width (String) - Width of skeleton lines (default: '100%')lineHeight
- (String) - Height of each line (default: '1em')lines
- (Number) - Number of skeleton lines to display (default: 1)
Accessibility:
- Announces loading state to screen readers with role="status"prefers-reduced-motion
- Automatically pauses animation when is enabled
Usage:
`html
lineHeight="1.5em"
lines="2">
`
Common Patterns:
`html
---
$3
A flexible tooltip component that displays contextual information on hover.
Properties:
-
text (String) - Tooltip content to display
- position (String) - Tooltip position: 'top', 'bottom', 'left', or 'right' (default: 'bottom')Accessibility:
- Semantic
tooltip role with proper ARIA relationships
- Full keyboard support (hover, focus, Escape to dismiss)
- Screen reader announcements via aria-describedbyUsage:
`html
๐ฏ Target element
`---
๐จ Theming
Components use CSS custom properties for easy theming. Override these in your CSS:
`css
:root {
--primary: #1976d2;
--primaryHover: #1565c0;
--primaryForeground: #ffffff;
--disabled: #bdbdbd;
--greyLight: #e0e0e0;
--greyDark: #757575;
--blackLight: #424242;
--skeletonBase: #e0e0e0;
--skeletonHighlight: #f0f0f0;
}
`$3
All components automatically support dark mode via
@media (prefers-color-scheme: dark). When your operating system or browser is set to dark mode, the components will automatically adapt with optimized color schemes:`css
@media (prefers-color-scheme: dark) {
:host {
--primary: #4db8ff;
--primaryHover: #66c2ff;
--primaryForeground: #000;
--blackLight: #e0e0e0;
--greyLight: #3d3d3d;
--greyDark: #666;
--disabled: #555;
--skeletonBase: #3d3d3d;
--skeletonHighlight: #4d4d4d;
}
}
`No additional configuration required - dark mode works out of the box!
๐งช Development
$3
Run the local development server with live demo:
`bash
npm start
`Opens a development server at http://localhost:8000 with the demo page.
$3
View components in Storybook with interactive controls:
`bash
npm run storybook
`Build Storybook for deployment:
`bash
npm run build-storybook
`$3
Run tests once:
`bash
npm run test
`Run tests in watch mode:
`bash
npm run test:watch
`$3
Check for linting/formatting errors:
`bash
npm run lint
`Auto-fix linting/formatting errors:
`bash
npm run format
`๐ Browser Support
- Chrome/Edge (latest)
- Firefox (latest)
- Safari (latest)
- Modern browsers with ES2015+ support
๐ค Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
1. Fork the repository
2. Create your feature branch (
git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature`)This project is licensed under the MIT License - see the LICENSE file for details.
- ๐ Live Demo & Storybook
- ๐ฆ npm Package
- ๐ป GitHub Repository
- ๐ฅ Lit Documentation
- ๐ Open Web Components
Built with Lit and following open-wc recommendations for modern web component development.
---
Made with โค๏ธ by Eduardo de la Cruz Palacios