joy-ui

Joy UI

What is Joy UI?

Joy UI (@mui/joy) is MUI's alternative component library that offers a modern, clean design language distinct from Google's Material Design. It is built from the ground up with CSS variables as a first-class feature, a flexible variant system, and a simpler API surface compared to Material UI.

npm install @mui/joy @emotion/react @emotion/styled
# or
pnpm add @mui/joy @emotion/react @emotion/styled

Joy UI shares MUI's engineering quality (accessibility, TypeScript, composability) but makes different design decisions:

• CSS variables by default -- not experimental, not opt-in
• Variant system -- every component supports solid, soft, outlined, plain
• Color system -- semantic colors (primary, neutral, danger, success, warning) instead of primary/secondary
• Decoration levels -- replaces Material UI's elevation with a more flexible concept
• Modern aesthetic -- rounded, spacious, contemporary look out of the box

When to Use Joy UI

Scenario	Recommendation
App should NOT look like Material Design	Joy UI
Want CSS variables without experimental flags	Joy UI
Need Google Material Design compliance	Material UI
Building a modern SaaS dashboard	Joy UI
Existing Material UI codebase	Material UI (or gradual migration)
Need the largest component catalog	Material UI (more components today)
Want built-in dark mode with zero config	Joy UI

Key Differences from Material UI

Variant System

Material UI uses variant on some components (contained, outlined, text for Button). Joy UI applies a consistent variant system across ALL components:

Variant	Description	Use Case
solid	Filled background, high emphasis	Primary actions, selected states
soft	Subtle background tint	Secondary actions, tags, badges
outlined	Border only	Tertiary actions, form fields
plain	No background or border	Low-emphasis, text-like actions

import Button from '@mui/joy/Button';
import Chip from '@mui/joy/Chip';
import Alert from '@mui/joy/Alert';

// Every component supports all four variants
<Button variant="solid">Submit</Button>
<Button variant="soft">Draft</Button>
<Button variant="outlined">Cancel</Button>
<Button variant="plain">Skip</Button>

<Chip variant="soft" color="success">Active</Chip>
<Alert variant="outlined" color="warning">Check your input</Alert>

Color System

Material UI: primary, secondary, error, warning, info, success Joy UI: primary, neutral, danger, success, warning

import Button from '@mui/joy/Button';
import Typography from '@mui/joy/Typography';

<Button color="primary">Primary</Button>
<Button color="neutral">Neutral</Button>
<Button color="danger">Delete</Button>
<Button color="success">Approve</Button>
<Button color="warning">Caution</Button>

<Typography color="danger">Error message</Typography>

Component Naming Differences

Material UI	Joy UI	Notes
Paper	Sheet	Surface container
TextField	Input / Textarea	Separate components, not a wrapper
AppBar	Header (custom)	Joy UI does not ship AppBar; use Sheet
Snackbar	Snackbar	Same name, different API
Fab	No equivalent	Use IconButton with variant="solid"
Rating	No equivalent	Not yet available in Joy UI
SpeedDial	No equivalent	Not yet available

Decoration Levels vs Elevation

Material UI uses elevation={0..24} for box-shadow depth. Joy UI uses CSS variables and the shadow prop:

import Sheet from '@mui/joy/Sheet';

// Joy UI -- shadow levels
<Sheet variant="outlined" sx={{ p: 2 }}>No shadow</Sheet>
<Sheet variant="outlined" sx={{ p: 2, boxShadow: 'sm' }}>Small shadow</Sheet>
<Sheet variant="outlined" sx={{ p: 2, boxShadow: 'md' }}>Medium shadow</Sheet>
<Sheet variant="outlined" sx={{ p: 2, boxShadow: 'lg' }}>Large shadow</Sheet>

Setup

Basic Setup with CssVarsProvider

// src/main.tsx
import { CssVarsProvider } from '@mui/joy/styles';
import CssBaseline from '@mui/joy/CssBaseline';
import App from './App';

function Root() {
  return (
    <CssVarsProvider>
      <CssBaseline />
      <App />
    </CssVarsProvider>
  );
}

CssVarsProvider replaces Material UI's ThemeProvider. It automatically:

• Injects CSS variables into :root
• Supports light/dark mode toggle without theme re-creation
• Enables runtime theme switching without JavaScript recalculation

Dark Mode Toggle

import { useColorScheme } from '@mui/joy/styles';
import IconButton from '@mui/joy/IconButton';

function ColorSchemeToggle() {
  const { mode, setMode } = useColorScheme();

  return (
    <IconButton
      variant="outlined"
      color="neutral"
      onClick={() => setMode(mode === 'dark' ? 'light' : 'dark')}
    >
      {mode === 'dark' ? <SunIcon /> : <MoonIcon />}
    </IconButton>
  );
}

No need to create separate light/dark themes. The CSS variables automatically switch.

Theme Customization

Using extendTheme

import { CssVarsProvider, extendTheme } from '@mui/joy/styles';

const customTheme = extendTheme({
  colorSchemes: {
    light: {
      palette: {
        primary: {
          50: '#eff6ff',
          100: '#dbeafe',
          200: '#bfdbfe',
          300: '#93c5fd',
          400: '#60a5fa',
          500: '#3b82f6',
          600: '#2563eb',
          700: '#1d4ed8',
          800: '#1e40af',
          900: '#1e3a8a',
        },
        success: {
          solidBg: '#16a34a',
          solidHoverBg: '#15803d',
        },
      },
    },
    dark: {
      palette: {
        primary: {
          solidBg: '#3b82f6',
          solidHoverBg: '#2563eb',
        },
      },
    },
  },
  fontFamily: {
    body: '"Inter", var(--joy-fontFamily-fallback)',
    display: '"Inter", var(--joy-fontFamily-fallback)',
  },
  typography: {
    h1: {
      fontSize: '2.25rem',
      fontWeight: 700,
      lineHeight: 1.2,
    },
    h2: {
      fontSize: '1.875rem',
      fontWeight: 600,
      lineHeight: 1.3,
    },
  },
  radius: {
    sm: '6px',
    md: '8px',
    lg: '12px',
  },
  components: {
    JoyButton: {
      styleOverrides: {
        root: {
          borderRadius: 'var(--joy-radius-md)',
          fontWeight: 600,
        },
      },
      defaultProps: {
        variant: 'solid',
        color: 'primary',
      },
    },
    JoyInput: {
      styleOverrides: {
        root: {
          '--Input-radius': 'var(--joy-radius-md)',
        },
      },
    },
  },
});

function App() {
  return (
    <CssVarsProvider theme={customTheme}>
      <CssBaseline />
      {/* app content */}
    </CssVarsProvider>
  );
}

Accessing CSS Variables in Custom Components

import { styled } from '@mui/joy/styles';

const CustomCard = styled('div')(({ theme }) => ({
  padding: theme.spacing(2),
  borderRadius: theme.vars.radius.md,
  backgroundColor: theme.vars.palette.background.surface,
  border: `1px solid ${theme.vars.palette.divider}`,
  boxShadow: theme.vars.shadow.sm,
  // CSS variables are also accessible as plain CSS
  // background: 'var(--joy-palette-background-surface)',
}));

Custom Tokens

const theme = extendTheme({
  colorSchemes: {
    light: {
      palette: {
        // Custom semantic tokens
        brand: {
          50: '#fdf2f8',
          500: '#ec4899',
          700: '#be185d',
        },
      },
    },
  },
});

// TypeScript: augment the palette interface
declare module '@mui/joy/styles' {
  interface PaletteRange {
    // already exists in Joy
  }
  interface Palette {
    brand: PaletteRange;
  }
}

Component Examples

Button

import Button from '@mui/joy/Button';
import IconButton from '@mui/joy/IconButton';
import ButtonGroup from '@mui/joy/ButtonGroup';

// Variants and colors
<Button variant="solid" color="primary">Save</Button>
<Button variant="soft" color="neutral">Cancel</Button>
<Button variant="outlined" color="danger">Delete</Button>
<Button variant="plain" color="success">Approve</Button>

// Sizes
<Button size="sm">Small</Button>
<Button size="md">Medium</Button>
<Button size="lg">Large</Button>

// With icons
<Button startDecorator={<PlusIcon />}>Add item</Button>
<Button endDecorator={<ArrowRightIcon />}>Next</Button>

// Loading state
<Button loading>Saving...</Button>
<Button loading loadingPosition="start" startDecorator={<SaveIcon />}>
  Saving...
</Button>

// Icon button
<IconButton variant="soft" color="neutral">
  <SettingsIcon />
</IconButton>

// Button group
<ButtonGroup variant="outlined" color="neutral">
  <Button>Left</Button>
  <Button>Center</Button>
  <Button>Right</Button>
</ButtonGroup>

Input and Textarea

import Input from '@mui/joy/Input';
import Textarea from '@mui/joy/Textarea';
import FormControl from '@mui/joy/FormControl';
import FormLabel from '@mui/joy/FormLabel';
import FormHelperText from '@mui/joy/FormHelperText';

// Basic input
<Input placeholder="Enter your name" />

// With decorators (adornments)
<Input
  startDecorator={<SearchIcon />}
  endDecorator={<IconButton variant="plain"><ClearIcon /></IconButton>}
  placeholder="Search..."
/>

// Form control with label and helper text
<FormControl error>
  <FormLabel>Email</FormLabel>
  <Input
    type="email"
    placeholder="name@example.com"
    variant="outlined"
  />
  <FormHelperText>Please enter a valid email address.</FormHelperText>
</FormControl>

// Textarea with auto-resize
<Textarea
  placeholder="Write your message..."
  minRows={3}
  maxRows={6}
  variant="outlined"
/>

Card (Sheet-based)

import Card from '@mui/joy/Card';
import CardContent from '@mui/joy/CardContent';
import CardOverflow from '@mui/joy/CardOverflow';
import CardActions from '@mui/joy/CardActions';
import AspectRatio from '@mui/joy/AspectRatio';
import Typography from '@mui/joy/Typography';
import Button from '@mui/joy/Button';
import Chip from '@mui/joy/Chip';

function ProductCard() {
  return (
    <Card variant="outlined" sx={{ width: 320 }}>
      <CardOverflow>
        <AspectRatio ratio="16/9">
          <img src="/product.jpg" alt="Product" loading="lazy" />
        </AspectRatio>
      </CardOverflow>

      <CardContent>
        <Typography level="title-md">Premium Headphones</Typography>
        <Typography level="body-sm" textColor="text.tertiary">
          Noise-cancelling wireless headphones with 30-hour battery life.
        </Typography>
        <Chip variant="soft" color="success" size="sm" sx={{ mt: 1 }}>
          In Stock
        </Chip>
      </CardContent>

      <CardOverflow variant="soft" sx={{ bgcolor: 'background.level1' }}>
        <CardActions>
          <Typography level="title-lg" sx={{ mr: 'auto' }}>
            $299
          </Typography>
          <Button variant="solid" color="primary" size="sm">
            Add to Cart
          </Button>
        </CardActions>
      </CardOverflow>
    </Card>
  );
}

Typography

import Typography from '@mui/joy/Typography';

// Joy UI uses "level" instead of "variant"
<Typography level="h1">Heading 1</Typography>
<Typography level="h2">Heading 2</Typography>
<Typography level="h3">Heading 3</Typography>
<Typography level="h4">Heading 4</Typography>
<Typography level="title-lg">Title Large</Typography>
<Typography level="title-md">Title Medium</Typography>
<Typography level="title-sm">Title Small</Typography>
<Typography level="body-lg">Body Large</Typography>
<Typography level="body-md">Body Medium (default)</Typography>
<Typography level="body-sm">Body Small</Typography>
<Typography level="body-xs">Body Extra Small</Typography>

// With color
<Typography color="primary">Primary text</Typography>
<Typography color="danger">Error message</Typography>
<Typography textColor="text.secondary">Secondary text</Typography>

// Decorators (icons inline with text)
<Typography startDecorator={<InfoIcon />}>
  This is an informational message.
</Typography>

Modal

import Modal from '@mui/joy/Modal';
import ModalDialog from '@mui/joy/ModalDialog';
import ModalClose from '@mui/joy/ModalClose';
import DialogTitle from '@mui/joy/DialogTitle';
import DialogContent from '@mui/joy/DialogContent';
import DialogActions from '@mui/joy/DialogActions';
import Button from '@mui/joy/Button';
import { useState } from 'react';

function ConfirmDialog() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <Button variant="outlined" color="danger" onClick={() => setOpen(true)}>
        Delete Account
      </Button>

      <Modal open={open} onClose={() => setOpen(false)}>
        <ModalDialog variant="outlined" role="alertdialog" size="md">
          <ModalClose />
          <DialogTitle>
            Are you sure?
          </DialogTitle>
          <DialogContent>
            This action cannot be undone. All your data will be permanently deleted.
          </DialogContent>
          <DialogActions>
            <Button variant="solid" color="danger" onClick={() => setOpen(false)}>
              Delete
            </Button>
            <Button variant="plain" color="neutral" onClick={() => setOpen(false)}>
              Cancel
            </Button>
          </DialogActions>
        </ModalDialog>
      </Modal>
    </>
  );
}

// Fullscreen modal on mobile
<ModalDialog
  layout="fullscreen" // 'center' | 'fullscreen'
  sx={(theme) => ({
    [theme.breakpoints.only('xs')]: {
      top: 'unset',
      bottom: 0,
      left: 0,
      right: 0,
      borderRadius: '12px 12px 0 0',
      transform: 'none',
    },
  })}
>
  {/* content */}
</ModalDialog>

Autocomplete

import Autocomplete from '@mui/joy/Autocomplete';
import AutocompleteOption from '@mui/joy/AutocompleteOption';
import FormControl from '@mui/joy/FormControl';
import FormLabel from '@mui/joy/FormLabel';
import ListItemContent from '@mui/joy/ListItemContent';
import ListItemDecorator from '@mui/joy/ListItemDecorator';
import Typography from '@mui/joy/Typography';

interface Country {
  code: string;
  label: string;
  phone: string;
}

const countries: Country[] = [
  { code: 'US', label: 'United States', phone: '+1' },
  { code: 'GB', label: 'United Kingdom', phone: '+44' },
  { code: 'DE', label: 'Germany', phone: '+49' },
  // ...
];

function CountrySelect() {
  return (
    <FormControl>
      <FormLabel>Country</FormLabel>
      <Autocomplete
        placeholder="Choose a country"
        options={countries}
        getOptionLabel={(option) => option.label}
        isOptionEqualToValue={(option, value) => option.code === value.code}
        renderOption={(props, option) => (
          <AutocompleteOption {...props}>
            <ListItemDecorator>
              <span className={`fi fi-${option.code.toLowerCase()}`} />
            </ListItemDecorator>
            <ListItemContent>
              <Typography level="body-md">{option.label}</Typography>
              <Typography level="body-xs" textColor="text.tertiary">
                {option.phone}
              </Typography>
            </ListItemContent>
          </AutocompleteOption>
        )}
        variant="outlined"
        sx={{ width: 300 }}
      />
    </FormControl>
  );
}

Using Joy UI + Material UI Together

It is possible to use both Joy UI and Material UI in the same application. This is useful during migration or when you need components that only exist in one library.

Setup: Dual Provider

import { CssVarsProvider as JoyCssVarsProvider } from '@mui/joy/styles';
import {
  ThemeProvider as MaterialThemeProvider,
  createTheme as materialCreateTheme,
  THEME_ID as MATERIAL_THEME_ID,
} from '@mui/material/styles';
import CssBaseline from '@mui/joy/CssBaseline';

const materialTheme = materialCreateTheme();

function App() {
  return (
    <MaterialThemeProvider theme={{ [MATERIAL_THEME_ID]: materialTheme }}>
      <JoyCssVarsProvider>
        <CssBaseline enableColorScheme />
        {/* Both Joy UI and Material UI components work here */}
      </JoyCssVarsProvider>
    </MaterialThemeProvider>
  );
}

Avoiding CSS Variable Conflicts

Joy UI and Material UI both generate CSS variables. To avoid collisions:

import { extendTheme } from '@mui/joy/styles';

const joyTheme = extendTheme({
  cssVarPrefix: 'joy', // default, but explicit for clarity
});

// Material UI variables use --mui- prefix
// Joy UI variables use --joy- prefix
// No collision

Sharing Design Tokens Between Both Libraries

// shared-tokens.ts
export const sharedTokens = {
  primaryMain: '#2563eb',
  primaryLight: '#60a5fa',
  primaryDark: '#1d4ed8',
  fontFamily: '"Inter", sans-serif',
  borderRadius: '8px',
};

// joy-theme.ts
import { extendTheme } from '@mui/joy/styles';
import { sharedTokens } from './shared-tokens';

export const joyTheme = extendTheme({
  colorSchemes: {
    light: {
      palette: {
        primary: {
          500: sharedTokens.primaryMain,
          400: sharedTokens.primaryLight,
          700: sharedTokens.primaryDark,
        },
      },
    },
  },
  fontFamily: {
    body: sharedTokens.fontFamily,
  },
});

// material-theme.ts
import { createTheme } from '@mui/material/styles';
import { sharedTokens } from './shared-tokens';

export const materialTheme = createTheme({
  palette: {
    primary: {
      main: sharedTokens.primaryMain,
      light: sharedTokens.primaryLight,
      dark: sharedTokens.primaryDark,
    },
  },
  typography: {
    fontFamily: sharedTokens.fontFamily,
  },
  shape: {
    borderRadius: parseInt(sharedTokens.borderRadius),
  },
});

Migration Considerations

When to Choose Joy UI over Material UI

Choose Joy UI when:

1. Starting a new project that should not look like Material Design
2. CSS variables are critical for runtime theming (white-label, user-customizable themes)
3. Dark mode must work seamlessly without re-rendering the component tree
4. Consistent variant system across all components is important to your design team
5. Modern aesthetic is desired without heavy theme overrides

Stay with Material UI when:

1. You have a large existing Material UI codebase -- migration cost may not be justified
2. You need components that Joy UI does not yet offer (Rating, SpeedDial, Timeline, TreeView, DataGrid)
3. Material Design compliance is required (e.g., internal Google-ecosystem tools)
4. Ecosystem maturity matters -- Material UI has more community themes, templates, and third-party integrations

Migration Checklist (Material UI to Joy UI)

[ ] Replace ThemeProvider with CssVarsProvider
[ ] Replace createTheme with extendTheme
[ ] Update component imports: @mui/material -> @mui/joy
[ ] Replace Paper with Sheet
[ ] Replace TextField with Input/Textarea + FormControl
[ ] Update variant values: "contained" -> "solid", "text" -> "plain"
[ ] Update color values: "error" -> "danger", "info" -> (use "primary" or "neutral")
[ ] Replace elevation prop with boxShadow sx prop
[ ] Replace Typography variant prop with level prop
[ ] Update Chip variant: "filled" -> "solid"
[ ] Test dark mode toggle (should work out of the box)
[ ] Verify CSS variable usage in custom styled components
[ ] Replace makeStyles/withStyles with sx prop or styled()

Side-by-Side Component Mapping

// MATERIAL UI                           // JOY UI
// ============                          // ======

import Paper from '@mui/material/Paper';  import Sheet from '@mui/joy/Sheet';
<Paper elevation={3}>                     <Sheet variant="outlined" sx={{ boxShadow: 'md' }}>

import TextField from '@mui/material/..'; import Input from '@mui/joy/Input';
<TextField                                <FormControl>
  label="Name"                              <FormLabel>Name</FormLabel>
  variant="outlined"                        <Input variant="outlined"
  error                                       error
  helperText="Required"                       />
/>                                          <FormHelperText>Required</FormHelperText>
                                           </FormControl>

<Button variant="contained">              <Button variant="solid">
<Button variant="text">                   <Button variant="plain">
<Chip variant="filled">                   <Chip variant="solid">
<Alert severity="error">                  <Alert color="danger">
<Typography variant="h4">                 <Typography level="h4">
<Typography variant="body1">              <Typography level="body-md">