A lightweight, type-safe Web Component library built for the Genie ecosystem. Grimoire provides beautifully styled, customizable components with built-in dark/light theme support.
- 🎨 Theme-Aware: Built-in dark/light mode support with flexible theming options
- 🔧 Type-Safe: Full TypeScript support with comprehensive type definitions
- 🪄 Magik Integration: Built on @magik_io/mote for powerful DOM manipulation
- 📦 Tree-Shakeable: ES modules with dynamic imports for optimal bundle size
- 🎯 Standards-Based: Pure Web Components using Custom Elements API
- 💅 CSS Variables: Fully customizable via CSS custom properties
# Using pnpm (recommended)
pnpm add @magik_io/grimoire
# Using npm
npm install @magik_io/grimoire
# Using yarn
yarn add @magik_io/grimoire- Node.js 22.x or higher
- pnpm 9.x or higher (for development)
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Grimoire Demo</title>
</head>
<body>
<!-- Use components in your HTML -->
<slide-toggle label="Enable notifications" checked="true"></slide-toggle>
<e-sig>John Doe</e-sig>
<script type="module">
import { Grimoire } from '@magik_io/grimoire';
// Define which components you want to use
await Grimoire.Define('slide-toggle', 'e-sig');
</script>
</body>
</html>A beautiful, animated toggle switch component.
<slide-toggle
label="Dark Mode"
checked="false"
name="darkModeToggle">
</slide-toggle>Attributes:
label(string): The label text displayed next to the togglechecked(boolean): Initial checked state (default:false)name(string): Name attribute for the input element
Properties:
activated: Get/set the toggle state programmatically
Events:
change: Fired when the toggle state changesdetail.checked: Current checked state
CSS Variables:
--st-body-bg: Background color
--st-checked-bg: Background color when checked
--st-border-width: Border width
--st-border-color: Border color
--st-color: Text color
--st-check-bg: Checkbox background
--st-check-bg-image: Checkbox background imageExample:
const toggle = document.querySelector('slide-toggle');
// Listen for changes
toggle.addEventListener('change', (e) => {
console.log('Toggle is now:', e.detail.checked);
});
// Programmatically control
toggle.activated = true;An elegant electronic signature component with multiple font choices.
<e-sig font="dancing-script" icon="fas fa-pen">
Antonio Bourassa
</e-sig>Attributes:
font(string): Font style for the signaturedancing-script(default)great-vibeshomemade-applemarck-scriptsacramentosatisfy
icon(string): Font Awesome icon class (default:fas fa-cog)
CSS Variables:
--eSig-bg: Background color
--eSig-border-color: Border color
--eSig-border-style: Border style
--eSig-border-radius: Border radius
--eSig-border-width: Border width
--eSig-line-height: Line height
--eSig-padding: Padding
--eSig-margin-bottom: Bottom margin
--eSig-color: Text colorFeatures:
- Click the icon to open a font selection modal
- Interactive font preview
- Responsive scaling
Note: You'll need to include Google Fonts in your HTML:
<link href="https://fonts.googleapis.com/css?family=Dancing+Script|Great+Vibes|Homemade+Apple|Marck+Script|Sacramento|Satisfy" rel="stylesheet">Grimoire provides flexible theming options:
Uses CSS media queries to detect system preferences:
Grimoire.Configure({ chroma: 'browser' });Uses body classes (.dark and .light):
Grimoire.Configure({ chroma: 'class' });Define your own theme classes:
Grimoire.Configure({
chroma: {
dark: 'my-dark-theme',
light: 'my-light-theme'
}
});Disable theme switching:
Grimoire.Configure({ chroma: false });Only load the components you need to keep your bundle small:
// Load only SlideToggle
await Grimoire.Define('slide-toggle');
// Load multiple components
await Grimoire.Define('slide-toggle', 'e-sig');Override CSS variables globally or per-component:
/* Global overrides */
:root {
--st-checked-bg: #ff6b6b;
--eSig-bg: #f0f0f0;
}
/* Dark mode overrides */
@media (prefers-color-scheme: dark) {
:root {
--st-checked-bg: #ff4757;
--eSig-bg: #2c2c2c;
}
}
/* Component-specific overrides */
slide-toggle {
--st-checked-bg: green;
}Full type definitions are included:
import { Grimoire, type GrimoireTemplateNames } from '@magik_io/grimoire';
const components: GrimoireTemplateNames[] = ['slide-toggle', 'e-sig'];
await Grimoire.Define(...components);
// Type-safe component references
const toggle = document.querySelector('slide-toggle') as HTMLElement & {
activated: boolean;
};Grimoire uses a sophisticated component registration system:
- Dynamic Imports: Components are loaded on-demand
- Style Extraction: CSS is automatically extracted and injected
- Theme Management: Automatic light/dark theme handling
- Custom Elements: Standards-based Web Components
Each component uses a ComponentDescriptor that defines:
- Component name and HTML tag
- Element class (extends
HTMLElement) - Style configuration (base styles, CSS variables, theme variants)
- Type of custom element
export default new ComponentDescriptor({
name: 'my-component',
element: MyComponent,
type: 'custom-element',
style: {
base: CSSVars => CSSVars`/* CSS */`,
vars: { /* CSS variables */ },
theme: {
light: { /* light theme vars */ },
dark: { /* dark theme vars */ }
}
}
});# Clone the repository
git clone https://github.com/MagikIO/grimoire.git
cd grimoire
# Install dependencies
pnpm install
# Start development server
pnpm dev# Build for production
pnpm build# Bump version, push tags, and publish
pnpm iterateGrimoire supports all modern browsers that implement:
- Custom Elements v1
- ES2022
- CSS Custom Properties
- ES Modules
Tested on:
- Chrome/Edge 90+
- Firefox 88+
- Safari 14+
- @magik_io/mote - Lightweight DOM manipulation library
- ulid - Universally Unique Lexicographically Sortable Identifiers
Contributions are welcome! Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests.
MIT © Antonio B.
See CHANGELOG.md for a list of changes.
- 🐛 Report a bug
- 💡 Request a feature
- 📧 Contact: Abourassa@AssetVal.com
- @magik_io/mote - DOM manipulation library
- @magik_io/lint_golem - ESLint configuration
Made with ✨ by MagikIO