**Grimoire** is a modern, opinionated React component library focused on **clean UI**, **strong defaults**, and **easy customization** — without fighting CSS.
npm install @shazam-codes/grimoireGrimoire is a modern, opinionated React component library focused on clean UI, strong defaults, and easy customization — without fighting CSS.
It is built with:
* React
* Tailwind CSS (precompiled)
* Lucide Icons
* Context-first theming
> Think of Grimoire as a spellbook of ready-to-use UI components for dashboards, admin panels, and SaaS apps.
---
* 🎨 Themeable via GrimoireProvider
* 🧩 Composable components (Card, Tabs, Dialogs)
* ⚡ Fully controlled inputs
* 🔔 Built-in Toast system
* 🧠 Smart defaults with easy overrides
* 🧵 Tailwind-powered with class merging via cn()
---
bash
npm install @shazam-codes/grimoire
`or
bash
yarn add @shazam-codes/grimoire
`---
🏗️ Global Setup (Required)
$3
Grimoire ships with precompiled Tailwind styles.
js
import "@shazam-codes/grimoire/style.css";
`> ⚠️ Important
> Remove generic element resets from your own
(e.g. button, input, h1) as they may override Grimoire styles.---
$3
`jsx
import { GrimoireProvider, ToastProvider } from '@shazam-codes/grimoire'createRoot(document.getElementById('root')).render(
primary: '#18333E',
secondary: '#1987C6',
background: "#FFFFFF",
}}
>
defaultDuration={5000}
>
)
`$3
| Provider | Required | Purpose |
| ------------------ | -------- | -------------------- |
|
| ✅ | Injects theme colors |
| ToastProvider | ❌ | Enables useToast() |---
🔔 Toast System
Trigger notifications from anywhere:
`jsx
import { useToast } from '@shazam-codes/grimoire'const { addToast } = useToast()
addToast('Saved successfully!', 'success')
`$3
*
*
*
* $3
js
addToast(message, type, {
duration: 5000,
position: 'top-left'
})
`---
🧩 Component Overview
Every component:
* Is controlled
* Accepts
* Uses internally for safe overrides---
🔘 Actions & Controls
$3
`jsx
icon={
onClick={handleSave}
/>
`Variants
*
(default)
* secondary
*
* Props
*
*
*
*
*
*
* ---
$3
jsx
checked={enabled}
onChange={setEnabled}
/>
`---
$3
jsx
options={[
{ label: 'Free', value: 'free' },
{ label: 'Pro', value: 'pro' },
]}
value={plan}
onChange={setPlan}
/>
`---
📝 Forms & Inputs
$3
jsx
icon={
value={email}
onChange={e => setEmail(e.target.value)}
error="Invalid email"
/>
`---
$3
jsx
value={password}
onChange={e => setPassword(e.target.value)}
/>
`---
$3
jsx
rows={3}
value={bio}
onChange={e => setBio(e.target.value)}
/>
`---
$3
jsx
accept="image/*"
maxSizeMB={2}
value={file}
onChange={setFile}
/>
`✔ Drag & drop
✔ Size validation
✔ Auto-dismiss errors
---
$3
jsx
description="You must accept before continuing"
checked={checked}
onChange={setChecked}
/>
`---
🔽 Selection & Navigation
$3
jsx
options={options}
value={value}
onChange={setValue}
/>
`---
$3
jsx
options={options}
value={values}
onChange={setValues}
/>
`---
$3
jsx
{ id: 'account', label: 'Account', icon: User },
{ id: 'security', label: 'Security', count: 2 },
]}
activeTab={tab}
onChange={setTab}
/>
`---
$3
A responsive, state-persistent navigation sidebar with built-in storage management and multiple themes.
jsx
variant={}
items={}
logo={}
collapsedLogo={}
footer={}
items={[
{
key: 1,
label: "Dashboard",
icon: ,
collapsedIcon: ,
onClick: () => navigate('/dashboard')
}
]}
/>
`Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
|
| Array | [] | Array of nav items { key, label, icon, collapsedIcon, onClick } |
| variant | string | 'primary' | Visual theme: primary, secondary, outline, ghost |
| collapsible | boolean | true | Whether the sidebar can be toggled by the user |
| defaultExpanded | boolean | true | Initial state (useful if collapsible is false) |
| storageKey | string | 'sidebar-state' | Key for localStorage to persist collapsed state & active item |
| logo | ReactNode | - | Component to show when expanded |
| collapsedLogo | ReactNode | - | Component to show when collapsed |
| footer | ReactNode | - | Content at the bottom. Collapses into a popover automatically. |Variants
*
primary: Active item uses solid primary color
* secondary: Active item uses solid secondary color
* outline: Active item has primary border and light background
* ghost: Active item has transparent background and underlined textFeatures
✔ Automatic state persistence via localStorage
✔ Smooth collapse/expand animations
✔ Footer popover when collapsed
✔ Support for different icons in collapsed/expanded states
✔ Keyboard accessible
---
📊 Data Display
$3
`jsx
variant="rounded"
src="/user.jpg"
fallback="JD"
/>
`Sizes
*
md lg xlVariants
*
*
* ---
$3
jsx
`Variants
*
*
*
*
* ---
$3
jsx
`Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
|
| string | - | The text to display inside the tooltip |
| position | string | 'right' | top, bottom, left, right |
| variant | string | 'primary' | primary, secondary, dark, light, outline |
| className | string | '' | Additional classes for the tooltip bubble |Variants
*
primary: Uses your theme's primary color
* secondary: Uses your theme's secondary color
* dark: Black background with white text
* light: White background with dark text
* outline: Bordered tooltip with transparent background$3
`jsx
`---
$3
jsx
label="Upload"
showPercentage
variant="warning"
/>
`---
🧱 Layout Components
$3
jsx
Title
Description
Content here
`---
⚠️ Modals & Feedback
$3
jsx
onClose={() => setOpen(false)}
onConfirm={handleConfirm}
title="Delete item?"
description="This action is permanent."
confirmText="Delete"
variant="danger"
isLoading={loading}
/>
`---
🎨 Styling & Overrides (
)All components merge classes safely:
`jsx
``Your styles override defaults cleanly — no CSS battles.
---
* Controlled components only
* No magic state
* Minimal props, strong defaults
* Easy to extend, hard to break
---
* Dark mode support
* Table component
* Date picker
* Command palette
---
MIT © Shazam Codes