Migrating from MUI to Ninna UI: A Practical Guide

MUI is a fantastic library — it's the most mature React component library with over 90K stars and 100+ components. But if you're moving to Tailwind CSS v4 and CSS-first theming, MUI's Emotion-based approach adds overhead you no longer need. This guide walks through a practical migration.

1. Install Ninna UI alongside MUI

npm install @ninna-ui/core @ninna-ui/primitives @ninna-ui/forms @ninna-ui/layout @ninna-ui/overlays

2. Add the CSS theme

MUI uses a ThemeProvider with createTheme(). Ninna UI uses a CSS import. Add both to your app during migration:

@import "tailwindcss";
@import "@ninna-ui/core/theme/presets/default.css";
@variant dark (&:is(.dark *));

3. Map components

Most MUI components have a Ninna UI equivalent. The mental model is different (style props → className), but the functionality maps:

// MUI
<Button variant="contained" color="primary" size="large">Click</Button>
<TextField label="Email" variant="outlined" />
<Dialog open={open} onClose={onClose}>
  <DialogTitle>Title</DialogTitle>
  <DialogContent>Content</DialogContent>
</Dialog>

// Ninna UI
<Button color="primary" size="lg">Click</Button>
<Field label="Email"><Input /></Field>
<Modal open={open} onOpenChange={setOpen}>
  <Modal.Content>
    <Modal.Header>Title</Modal.Header>
    <Modal.Body>Content</Modal.Body>
  </Modal.Content>
</Modal>

4. Replace sx prop with className

MUI's sx prop is powerful but adds runtime overhead. With Tailwind v4, use utility classes:

// MUI
<Box sx={{ display: "flex", gap: 2, p: 3 }}>...</Box>

// Ninna UI + Tailwind
<div className="flex gap-2 p-3">...</div>
// or
<Flex gap="2" p="3">...</Flex>

5. Remove MUI gradually

As you migrate each page, remove the corresponding MUI imports. Once all pages are migrated, remove @mui/material, @emotion/react, and @emotion/styled from your dependencies. You'll typically save 100-200KB from your bundle.

What you gain

• CSS-first theming — no ThemeProvider, no createTheme, no Emotion runtime.
• Smaller bundle — remove Emotion (~15KB) and MUI's runtime.
• Tailwind v4 native — utility classes instead of sx objects.
• oklch colors — perceptually uniform palettes.
• No hydration mismatches — CSS imports resolve at build time.

What you give up

MUI has 100+ components and a massive ecosystem. Ninna UI has 69 — still comprehensive, but if you depend on MUI-specific components (DataGrid, DateRangePicker, Rich Text), you'll need alternatives. Also, MUI's Material Design compliance is best-in-class; if Material Design is a hard requirement, MUI may still be the right choice.