🎨 Edu Web Components Library


A modern, lightweight collection of reusable web components built with Lit following open-wc recommendations.

📖 View Live Demo & Documentation

✨ Features

- 🚀 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

📦 Installation

``bash
npm install edu-webcomponents
`

🚀 Quick Start

Import all components:

`html



`

Or import individual components:

`html



`

📚 Components

$3

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

type="info"
message="This is an informational message">



type="success"
message="Your changes have been saved successfully!">



type="warning"
message="Your session will expire in 5 minutes"
dismissible>



type="error"
message="Unable to process your request. Please try again.">



type="info"
message="New features available!"
position="sticky"
dismissible>



type="warning"
message="Scheduled maintenance tonight at 10 PM"
position="fixed">



type="success"
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';
`

---

$3

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

type="success"
message="Changes saved"
duration="3000"
open
dismissible
>


type="error"
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();
`

---

$3

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 label
- aria-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)
- Supports aria-live attribute for dynamic content announcements
- Automatically adds aria-atomic="true" when aria-live is set
- Decorative mode (decorative 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
text="5"
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';
`

---

$3

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







text="Submit Form"
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!');
});
`

---

$3

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





`

---

$3

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"
- Slows animation speed when prefers-reduced-motion is enabled
- Customizable label for context-specific loading messages

Usage:

`html





`

---

$3

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"
- Dynamic aria-valuenow, aria-valuemin, and aria-valuemax attributes
- Customizable labels for context-specific progress tracking

Usage:

`html




value="75"
max="100"
showLabel>



value="3"
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);
`

---

$3

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"
- Automatically pauses animation when prefers-reduced-motion is enabled

Usage:

`html







width="60%"
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-describedby

Usage:

`html


Hover me




🎯 Target element








Link with tooltip

`

---

🎨 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`)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

- 📖 Live Demo & Storybook
- 📦 npm Package
- 💻 GitHub Repository
- 🔥 Lit Documentation
- 🌐 Open Web Components

🙏 Acknowledgments

Built with Lit and following open-wc recommendations for modern web component development.

---

Made with ❤️ by Eduardo de la Cruz Palacios