Guide

Getting started

MarclayUI is a claymorphism + neumorphism component library for React and Next.js — with light/dark theming and runtime color control, and no Tailwind or runtime dependencies.

bash

npm install marclayui

1 · Install

MarclayUI ships as ESM and CJS with full TypeScript definitions. React 18+ is the only peer dependency.

bash

npm install marclayui

2 · Set up the provider

Wrap your app once in MarclayProvider and import the stylesheet. The provider owns the style preset (claymorphism or neumorphism), the current mode (light / dark / system) and any runtime color overrides.

tsx

// app/layout.tsx
import { MarclayProvider, ToastProvider } from "marclayui";
import { themeInitScript } from "marclayui/theme-init";
import "marclayui/styles.css";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body className="mcl-root">
        {/* themeInitScript applies the saved theme before first paint (no flash) */}
        <script dangerouslySetInnerHTML={{ __html: themeInitScript }} />
        <MarclayProvider defaultMode="system">
          <ToastProvider>{children}</ToastProvider>
        </MarclayProvider>
      </body>
    </html>
  );
}

No flash of the wrong theme: render themeInitScript in your <head> and add suppressHydrationWarning to <html>. It reads localStorage and sets data-theme before first paint.

tsx

import { themeInitScript } from "marclayui";

<html suppressHydrationWarning>
  <head>
    <script dangerouslySetInnerHTML={{ __html: themeInitScript }} />
  </head>
  …
</html>

3 · Use components

Every component is importable from the package root. Interactive ones carry their own "use client" boundary, so they work in Server Components out of the box.

tsx

"use client";
import { Button, useTheme } from "marclayui";

export function ThemeActions() {
  const { toggle, setColors, setPreset } = useTheme();

  return (
    <>
      <Button variant="primary" onClick={toggle}>
        Toggle theme
      </Button>
      <Button variant="secondary" onClick={() => setPreset("neo")}>
        Neumorphism preset
      </Button>
      <Button variant="accent" onClick={() => setColors({ primary: "#7c5cff" })}>
        Violet primary
      </Button>
    </>
  );
}

Where to next

Theming

CSS variables, dark mode and the live color playground.

Guide

Button

Six clay variants, three sizes, loading states.

Guide

Modal

Portaled dialogs with focus handling and Escape.

Guide

Toast

Provider-based notifications in four tones.

Guide