Joy UI (@mui/joy) is an open-source React component library designed as an alternative to Material UI (@mui/material). It implements MUI’s own distinctive "Joy Design" system, emphasizing a different aesthetic and design philosophy distinct from Material Design guidelines. Joy UI focuses on a modern, expressive design language with a strong emphasis on CSS variable-based theming, customization through a powerful slot system, and developer experience.
This page provides an in-depth technical overview of the Joy UI package, its integration with Base UI, architectural patterns, theming, and current development status.
For context on related libraries see:
Joy UI offers a cohesive React component set based on the Joy Design system. It is designed to provide:
Joy UI is currently in beta, positioning itself as a robust alternative but secondary priority compared to the flagship Material UI and Base UI libraries.
Sources:
packages/mui-material/package.json5 packages/mui-system/package.json5 packages/mui-utils/package.json5
@mui/joy package.@mui/base for headless component logic and @mui/system for styling and theming utilities.@mui/utils for shared React utility functions.Sources:
package.json102-103 packages/mui-system/package.json2-17 packages/mui-utils/package.json2-39
Each Joy UI component follows a standardized architecture emphasizing consistency, extensibility, and customization by:
useThemeProps to merge user props with theme defaults.ownerState object to represent component internal state.composeClasses utility based on ownerState.styled() components that respond to CSS variables and theme variants.Sources:
packages/mui-system/package.json85-93 packages/mui-utils/package.json71-73
Joy UI acts as a styled and design-integrated wrapper layer over the headless components provided by Base UI. This separation enables:
Joy UI components typically wrap Base UI hooks and add their styling via slots and CSS vars.
| Joy UI Component | Corresponding Base UI Hook | Purpose |
|---|---|---|
Button | useButton | Handles keyboard/focus logic and accessibility attributes |
Select | useSelect | Manages popup interactions and option selection logic |
Autocomplete | useAutocomplete | Complex filtering and popup controls |
Switch | useSwitch | Toggle state and accessible ARIA toggling |
Sources:
packages/mui-lab/package.json100 docs/package.json23 docs/package.json31
Joy UI components are composed of multiple slots — discrete internal parts customizable via props:
slots: map from slot name to component or element type.slotProps: map from slot name to props applied to the slot.Internally, this enables React composition without exposing component internals publicly.
For example, the Select component breaks down as:
root: wrapper divbutton: the control buttonindicator: arrow iconlistbox: dropdown list containerThe useSlot utility manages mapping and prop merging for each slot.
Sources:
packages/mui-material/package.json94-117 packages/mui-system/package.json84-95
Joy UI is designed from the ground up to fully leverage CSS custom properties (CSS variables) for theming, enabling:
InitColorSchemeScript.The CSS variables follow an extensive naming convention, e.g.:
| Category | Variable Pattern | Example Variable |
|---|---|---|
| Palette | --joy-palette-{color}-{variant} | --joy-palette-primary-solidBg |
| Typography | --joy-fontSize-{size} | --joy-fontSize-md |
| Radius | --joy-radius-{size} | --joy-radius-sm |
| Shadow | --joy-shadow-{size} | --joy-shadow-md |
These variables are exposed globally on the html or theme provider root and consumed inside styled components.
Sources:
packages/mui-material/src/styles/ThemeProviderWithVars.tsx1-20 packages/mui-system/package.json88-92 packages/mui-material/package.json108
Joy UI standardizes on four primary global visual variants used consistently across components, supporting a harmonious design language:
| Variant | Description |
|---|---|
| Solid | High emphasis, solid background color |
| Soft | Medium emphasis, lightly tinted background |
| Outlined | Medium-low emphasis, border with transparent bg |
| Plain | Low emphasis, text style until hover/focus |
This variant system uses the CSS vars and theme structure and is accessed via ownerState.variant inside styled components to apply the correct styling rules.
Sources:
packages/mui-system/src/styleFunctionSx/index.js1 packages/mui-system/src/createTheme/index.js1
Joy UI utilizes several internal monorepo packages for essential functionality:
| Package | Role |
|---|---|
@mui/system | Provides styled() abstraction, theming, and the sx prop API |
@mui/utils | Provides React utilities like useId, composeClasses, deepmerge |
@mui/styled-engine | Abstracts Emotion or styled-components styling engines used by Joy UI |
These dependencies ensure Joy UI components maintain consistency with the MUI ecosystem and benefit from shared optimizations and standards.
Sources:
packages/mui-system/package.json34-42 packages/mui-utils/package.json33-40 packages/mui-styled-engine/package.json33-39
The Joy UI package is built with the MUI shared build tools:
.ts and .tsx files are transpiled using Babel to generate ESM and CJS outputs.tsc to produce .d.ts files.This standard MUI build process ensures Joy UI is shipped with full type safety and compatibility across consumption environments.
Sources:
package.json7-12 package.json69-73 packages/mui-material/package.json28
| Concept | Code Symbols / Files | Description |
|---|---|---|
| Package name | @mui/joy | Main Joy UI package |
| Depends on | @mui/base, @mui/system, @mui/utils | Base UI for logic, System for theming and styling, Utils for React helpers |
| Component pattern | useThemeProps(), ownerState, useSlot(), styled() | Standard pattern for props, state-derived styles, slots, and final rendering |
| Slot props and slots | props.slots, props.slotProps | Mechanism to customize internal component parts |
| Global variants | ownerState.variant (e.g., "solid", "soft") | Visual style categories for consistent design |
| CSS variables prefix | --joy-* | Theming variables used throughout the components |
| Base UI integrations | useButton, useSelect, useSwitch | Headless hooks providing essential functionality |
| Build tools | Babel, TypeScript, code-infra, generateProptypes.ts | Standard MUI build and type generation pipeline |
Joy UI represents a distinct design system and component library within the MUI ecosystem. By combining Base UI’s accessibility logic, MUI System’s powerful styling engine, and a slot-based architecture with deep CSS variables integration, Joy UI provides a modern, flexible, and customizable alternative to Material UI with a fresh aesthetic and developer-friendly design system.
Although it is currently in beta, it is a mature offering backed by the core MUI infrastructure and shares the same build, testing, and release pipelines as other MUI Core packages.
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.