Quick Start

Get up and running with MantleUI in under 5 minutes.

Requirements

React 18+ (React 19 supported)
TypeScript 5+ (recommended, not required)

Installation

Install the core package with your preferred package manager.

npm install @mantleui/react

Import Styles

Import the CSS file in your app's entry point (e.g., main.tsx, globals.css, or layout.tsx).

import "@mantleui/react/styles.css";

Basic Usage

Wrap your app with ThemeProvider to enable dark mode and theming. Then import and use any component.

import { Button, ThemeProvider } from "@mantleui/react";
import "@mantleui/react/styles.css";

function App() {
  return (
    <ThemeProvider>
      <Button color="blue" variant="solid">
        Get Started
      </Button>
    </ThemeProvider>
  );
}

ThemeProvider auto-detects system preference, persists to localStorage, and is SSR-safe.

Dark Mode

Dark mode is built into every component. Use useTheme to toggle between light and dark modes programmatically.

import { ThemeProvider, useTheme, Switch } from "@mantleui/react";

function ThemeSwitch() {
  const { theme, setTheme } = useTheme();
  return (
    <Switch
      checked={theme === "dark"}
      onCheckedChange={(v) => setTheme(v ? "dark" : "light")}
    />
  );
}

function App() {
  return (
    <ThemeProvider>
      <ThemeSwitch />
      {/* All components respond to theme changes instantly */}
    </ThemeProvider>
  );
}

3D Components (Optional)

MantleUI includes 11 Three.js-powered 3D components via a separate entry point. Install the peer dependencies to use them.

npm install three @react-three/fiber @react-three/drei

import { Globe, ParticleField } from "@mantleui/react/three";
import "@mantleui/react/three-styles.css";

function Scene() {
  return (
    <>
      <Globe
        showCountries
        markers={[{ lat: 40.7, lng: -74, label: "NYC" }]}
      />
      <ParticleField count={200} color="#8b5cf6" connections />
    </>
  );
}

Motion Components (Optional)

25 framer-motion-powered components including animations, 7 carousel variants, and advanced motion effects. Install framer-motion to use them.

npm install framer-motion

import {
  AnimatedCounter,
  Carousel,
  FloatingDock,
} from "@mantleui/react/motion";
import "@mantleui/react/motion-styles.css";

function Dashboard() {
  return (
    <>
      <AnimatedCounter value={12847} prefix="$" duration={1.5} />
      <Carousel slides={slides} autoplay interval={3000} />
      <FloatingDock items={dockItems} />
    </>
  );
}