@matteoaliano/forest-ui

v1.2.0

Published

6 days ago

Forest Design System — themed MUI components

0High
0Medium
0Low

matteoalianoretex

hirojanai

Forest UI

Forest Design System — A multi-tenant MUI v7 + Emotion component library.

Installation

Install the package and its peer dependencies:

npm install @matteoaliano/forest-ui \
  @mui/material@^7 @mui/icons-material@^7 \
  @mui/x-charts@^7 @mui/x-data-grid@^7 @mui/x-date-pickers@^8 \
  @emotion/react @emotion/styled dayjs

Forest UI re-exports MUI components with Forest defaults, so you should import everything from @matteoaliano/forest-ui rather than @mui/material. The only direct MUI import you need is @mui/icons-material for icons.

Quick Start

import { ForestProvider, Button, Typography } from '@matteoaliano/forest-ui';
import '@matteoaliano/forest-ui/fonts/aeonik/aeonik.css';

function App() {
  return (
    <ForestProvider>
      <Typography variant="h1">Hello Forest</Typography>
      <Button>Click me</Button>
    </ForestProvider>
  );
}

Next.js setup

Forest UI works with Next.js 14 / 15 / 16 (App Router and Pages Router). For best results with Turbopack and bundle size, add the following to next.config.js:

/** @type {import('next').NextConfig} */
const nextConfig = {
  transpilePackages: ['@matteoaliano/forest-ui'],
  experimental: {
    optimizePackageImports: [
      '@matteoaliano/forest-ui',
      '@mui/material',
      '@mui/icons-material',
    ],
  },
};

module.exports = nextConfig;

Because ForestProvider is a client component, wrap your app in a client boundary (a 'use client' component or a dedicated providers.tsx) before mounting it inside the App Router root layout.

Known issue: some @mui/x-* packages have intermittent Turbopack issues upstream that are unrelated to Forest UI. If you hit one, falling back to webpack (next dev without --turbo) usually clears it.

Theme Presets

The built-in preset is forest-alkemy-plus, which is also the default theme applied when no preset is set. Register your own with registerPreset().

Using a Preset

import { ForestProvider } from '@matteoaliano/forest-ui';

<ForestProvider preset="forest-alkemy+">
  {/* Your app */}
</ForestProvider>

Using a Custom Theme

import { ForestProvider, buildTheme, getPreset } from '@matteoaliano/forest-ui';

const preset = getPreset('forest-alkemy+');
const theme = buildTheme(preset.tokens, preset.tokensDark);

<ForestProvider theme={theme}>
  {/* Your app */}
</ForestProvider>

Dark Mode

forest-alkemy-plus ships a dark color scheme built on MUI's colorSchemes (CSS variables). It activates on a .dark class, the same convention as @matteoaliano/forest-web.

Recommended: useColorScheme() (below) — it puts the class on <html> for you, so portaled components (Modal, Menu, Tooltip, Popover, which render at document.body) switch too.

// Manual class toggle: put `dark` on <html> (not a deep wrapper) so portaled
// content inherits it. A wrapper only darkens its own subtree, leaving
// modals/menus light.
document.documentElement.classList.toggle("dark", isDark);

Set the initial scheme with defaultMode ("light" default, "dark", or "system" to follow prefers-color-scheme):

<ForestProvider preset="forest-alkemy+" defaultMode="system">
  {/* Your app */}
</ForestProvider>

Toggle programmatically with the re-exported MUI hook:

import { useColorScheme } from '@matteoaliano/forest-ui';

function ThemeToggle() {
  const { mode, setMode } = useColorScheme();
  return (
    <button onClick={() => setMode(mode === 'dark' ? 'light' : 'dark')}>
      {mode === 'dark' ? '☀️' : '🌙'}
    </button>
  );
}

Next.js App Router — render InitColorSchemeScript at the top of <body> to prevent a flash of the wrong scheme on load:

import { InitColorSchemeScript } from '@matteoaliano/forest-ui';

// app/layout.tsx, first child of <body>
<InitColorSchemeScript attribute="class" />

Components

40+ wrapped MUI components with Forest defaults. See Storybook for all components.

Inputs

Button, ButtonGroup
TextField, Select, MultiSelect
Checkbox, RadioGroup, Switch
ToggleButton
DatePicker
Autocomplete
Search

Data Display

Typography
Table, DataGrid
Chip, Badge
Tooltip
List
Divider
Skeleton

Surfaces

Card, Paper
AppBar
Accordion

Feedback

Alert, Snackbar
Dialog, Modal, Popover
Progress (Linear, Circular)
Backdrop

Navigation

Tabs, Stepper
Pagination
Breadcrumbs
Link
Menu
SidebarNav

Charts

LineChart, BarChart, PieChart

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Storybook
npm run storybook

License

MIT