**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
index.css (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(
theme={{
primary: '#18333E',
secondary: '#1987C6',
background: "#FFFFFF",
}}
>
defaultPosition="top-right"
defaultDuration={5000}
>
)
`$3
| Provider | Required | Purpose |
| ------------------ | -------- | -------------------- |
|
GrimoireProvider | โ
| 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
*
success
* error
* info
* warning$3
`js
addToast(message, type, {
duration: 5000,
position: 'top-left'
})
`---
๐งฉ Component Overview
Every component:
* Is controlled
* Accepts
className
* Uses cn() internally for safe overrides---
๐ Actions & Controls
$3
`jsx
text="Save"
icon={ }
onClick={handleSave}
/>
`Variants
*
primary (default)
* secondary
* outline
* ghostProps
*
text
* icon
* onClick
* type
* disabled
* tooltip
* className---
$3
`jsx
label="Enable notifications"
checked={enabled}
onChange={setEnabled}
/>
`---
$3
`jsx
label="Plan"
options={[
{ label: 'Free', value: 'free' },
{ label: 'Pro', value: 'pro' },
]}
value={plan}
onChange={setPlan}
/>
`---
๐ Forms & Inputs
$3
`jsx
label="Email"
icon={ }
value={email}
onChange={e => setEmail(e.target.value)}
error="Invalid email"
/>
`---
$3
`jsx
label="Password"
value={password}
onChange={e => setPassword(e.target.value)}
/>
`---
$3
`jsx
label="Bio"
rows={3}
value={bio}
onChange={e => setBio(e.target.value)}
/>
`---
$3
`jsx
label="Upload avatar"
accept="image/*"
maxSizeMB={2}
value={file}
onChange={setFile}
/>
`โ Drag & drop
โ Size validation
โ Auto-dismiss errors
---
$3
`jsx
label="Accept terms"
description="You must accept before continuing"
checked={checked}
onChange={setChecked}
/>
`---
๐ฝ Selection & Navigation
$3
`jsx
label="Framework"
options={options}
value={value}
onChange={setValue}
/>
`---
$3
`jsx
label="Technologies"
options={options}
value={values}
onChange={setValues}
/>
`---
$3
`jsx
tabs={[
{ 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
key={}
variant={}
items={}
logo={}
collapsedLogo={}
footer={}
items={[
{
key: 1,
label: "Dashboard",
icon: ,
collapsedIcon: ,
onClick: () => navigate('/dashboard')
}
]}
/>
`Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
|
items | 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
size="md"
variant="rounded"
src="/user.jpg"
fallback="JD"
/>
`Sizes
*
sm md lg xlVariants
*
circle
* square
* rounded---
$3
`jsx
`Variants
*
primary
* neutral
* success
* warning
* danger---
$3
`jsx
`Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
|
content | 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
progress={75}
label="Upload"
showPercentage
variant="warning"
/>
`---
๐งฑ Layout Components
$3
`jsx
Title
Description
Content here
`---
โ ๏ธ Modals & Feedback
$3
`jsx
isOpen={open}
onClose={() => setOpen(false)}
onConfirm={handleConfirm}
title="Delete item?"
description="This action is permanent."
confirmText="Delete"
variant="danger"
isLoading={loading}
/>
`---
๐จ Styling & Overrides (
cn())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