mui/material-ui 딥다이브
— "버튼 하나 안 만들고" 앱을 완성하게 해주는 React UI 표준

1프로젝트 한 줄 요약

Material UI는 "이미 완성된 UI 부품 상자"다. 버튼·체크박스·다이얼로그·앱바·테이블·폼 필드처럼 웹 앱에 필요한 화면 요소를 <Button>, <Dialog>, <TextField> 같은 React 컴포넌트로 이미 만들어 배포한다. 개발자는 이걸 가져다 조립하고, 필요하면 테마(색·글꼴·간격)만 바꿔 자기 브랜드에 맞춘다.

npm install @mui/material @emotion/react @emotion/styled 한 줄이면 시작할 수 있다. 흔히 "MUI"라고 줄여 부르며, 회사 이름도 MUI(예전 material-ui.com)다. 이 저장소 하나에 @mui/material(컴포넌트), @mui/system(스타일 유틸), @mui/icons-material(구글 아이콘 2,000개+), @mui/lab(실험적 컴포넌트) 등 10여 개 패키지가 함께 산다.

2왜 지금 주목받는가

① "React UI 라이브러리"라는 카테고리 자체를 만든 원조

Material UI는 2014년부터 이어져 온, React UI 컴포넌트 생태계의 사실상 표준이다. React 프로젝트에서 "UI 라이브러리 뭐 쓸까"라는 질문에 가장 먼저 나오는 이름 중 하나이고, 채용 공고·튜토리얼·부트캠프 커리큘럼에 광범위하게 등장한다. "오래돼서 유행이 지났다"는 인식과 달리, npm 주간 다운로드 기준으로도 여전히 최상위권을 지킨다.

② shadcn/ui식 "코드 복사" 흐름 속에서도 흔들리지 않는 이유

최근 shadcn/ui처럼 "라이브러리를 설치하는 대신 소스 코드를 복사해 온다"는 접근이 뜨면서 전통적 컴포넌트 라이브러리가 낡아 보인다는 말이 나온다. 하지만 Material UI는 "완성된 디자인 시스템 + 방대한 접근성·국제화(i18n) 테스트"가 이미 끝나 있다는 점에서 여전히 다른 선택지다. 처음부터 커스텀 디자인을 원하면 shadcn류가 맞고, 빠르게 완성도 있는 화면이 목표면 MUI가 여전히 강하다.

③ 계속되는 내부 진화 — CSS 변수 테마, 제로런타임 실험

겉보기엔 "오래된 라이브러리"지만 내부는 계속 바뀐다. CSS 변수 기반 테마(cssVariables: true)로 서버 사이드 렌더링에서도 깜빡임 없는 다크모드를 지원하게 됐고, Pigment CSS라는 빌드타임 제로런타임 스타일링 실험이 진행 중이다(현재는 별도 저장소로 독립). Base UI·Joy UI를 별도 프로젝트로 떼어내면서 이 레포 자체는 "@mui/material에 집중"하는 쪽으로 재편되기도 했다.

3무엇을 해결하나

겉보기엔 간단해 보이는 버튼 하나에도 실은 포커스 링·키보드 조작·스크린리더 라벨·눌림 효과(ripple)·비활성 상태·로딩 상태·반응형 크기까지 신경 쓸 게 많다. 체크박스·드롭다운·모달은 더하다. 이걸 매 프로젝트 처음부터 만들면 시간이 많이 들고, 접근성 실수가 나기 쉽다.

Material UI는 이런 "당연히 필요하지만 반복적이고 까다로운" UI 로직을 미리 검증된 형태로 제공한다. 회사가 새 디자인 시스템 없이도 일관된 톤·간격·색상 체계로 화면을 빠르게 완성할 수 있고, 테마 하나로 전체 앱의 색·타이포그래피를 한 번에 바꿀 수 있다. 즉 "디자인 시스템 구축 비용"과 "접근성 준수 비용"을 동시에 줄여준다.

4전체 구조 — 패키지 지도

실제로 클론해 packages/를 열어 보면, "Material UI"라는 하나의 패키지가 아니라 여러 패키지가 계층을 이루는 모노레포임을 바로 확인할 수 있다. 핵심만 추리면 다음과 같다.

이 레포에서 "빠진" 것들 — Base UI · Joy UI · Pigment CSS

예전 자료를 보면 @mui/base, @mui/joy가 이 모노레포 안에 있었다고 나온다. 실제로 클론해 확인하면 지금은 둘 다 존재하지 않는다. Base UI는 완전히 새로 설계돼 mui/base-ui 저장소(패키지명도 @base-ui/react·@base-ui-components/react)로 독립했고, Joy UI 관련 코드도 최근 커밋에서 "leftover Joy UI references"를 지우며 정리됐다. packages/pigment-css-react·packages/pigment-react 폴더를 열어보면 실제 코드 대신 "The package has moved to mui/pigment-css"라는 안내 README만 남아 있다 — 이는 문서와 실제 코드가 어긋나는 대표적 함정이라 9장에서 다시 다룬다.

5핵심 설계·동작 원리

① styled()·sx prop — Emotion을 "갈아 끼울 수 있게" 감춘다

Material UI의 모든 컴포넌트는 CSS-in-JS 라이브러리 Emotion 위에서 스타일을 만든다. 그런데 실제 소스(packages/mui-styled-engine/src/index.ts)를 보면 컴포넌트들이 Emotion을 직접 부르지 않는다. 대신 @mui/styled-engine이라는 얇은 재수출(re-export) 계층을 거친다.

// packages/mui-styled-engine/src/index.ts (발췌, 실제 소스)
import emStyled from '@emotion/styled';

function styled(tag, options) {
  const stylesFactory = emStyled(tag, options);
  // 개발 모드에서 styled(Comp)() 처럼 인자 없이 호출하면 경고를 띄운다
  return stylesFactory;
}
export default styled;
export { ThemeContext, keyframes, css } from '@emotion/react';

@mui/styled-engine-sc는 같은 인터페이스로 Emotion 대신 styled-components를 감싼다. 그래서 프로젝트 번들러 설정에서 @mui/styled-engine을 @mui/styled-engine-sc로 별칭(alias) 처리하면, MUI 컴포넌트 코드는 한 줄도 안 건드리고 내부 CSS-in-JS 엔진을 바꿀 수 있다. 이게 "styled-engine 추상화"의 정체다.

그 위에 @mui/system의 createStyled(packages/mui-system/src/createStyled/createStyled.js)가 한 겹 더 쌓인다. 여기서 모든 스타일드 컴포넌트에 sx prop을 자동으로 붙여준다 — attachTheme으로 테마를 주입하고, styleFunctionSx로 sx={{ p: 2, color: 'primary.main' }} 같은 객체를 실제 CSS로 변환한 뒤 기존 스타일 뒤에 이어붙인다. 즉 "Emotion 스타일 + sx 인라인 스타일"을 한 컴포넌트가 동시에 받는 구조다.

② createTheme·ThemeProvider — 테마 스케일과 팔레트 생성

@mui/system의 기본 createTheme(packages/mui-system/src/createTheme/createTheme.js)는 breakpoints·spacing·shape만 만드는 저수준 버전이다. 실제로 앱에서 쓰는 건 @mui/material/styles의 createTheme(packages/mui-material/src/styles/createTheme.ts)인데, 이게 팔레트 생성(createPalette)·타이포그래피 스케일·트랜지션·컴포넌트별 기본값까지 얹은 "완전판"이다.

import { createTheme, ThemeProvider } from '@mui/material/styles';

const theme = createTheme({
  palette: { primary: { main: '#1565c0' } },
});

function App() {
  return (
    <ThemeProvider theme={theme}>
      <Button>눌러보세요</Button>
    </ThemeProvider>
  );
}

primary.main 색 하나만 주면, 내부적으로 createPalette가 light/dark 보조색을 자동 생성하고, 컴포넌트들은 ThemeProvider의 React Context를 통해 이 값을 읽어 자기 스타일을 결정한다. "버튼 색을 하나하나 바꾸는 대신 테마 하나로 앱 전체 톤을 바꾼다"는 MUI의 핵심 사용 방식이 여기서 나온다.

③ CSS 변수 기반 테마(cssVariables)와 다크모드 — 실제 분기 코드

v5까지는 테마 값이 JS 객체로만 존재해, 다크모드 전환 시 리액트가 전체 트리를 다시 렌더링해야 했다. 최근 버전은 cssVariables: true 옵션으로 테마 값을 실제 CSS 커스텀 프로퍼티(--mui-palette-primary-main 등)로 뽑아내는 방식을 지원한다. createTheme.ts의 실제 분기 로직을 그대로 옮기면:

// packages/mui-material/src/styles/createTheme.ts (발췌)
if (cssVariables === false) {
  // v5와 완전히 동일하게 동작 — JS 객체 테마
  return createThemeNoVars(options, ...args);
}
// cssVariables: true 인 경우 — CSS 변수 + colorSchemes 기반 테마
return createThemeWithVars({
  ...other,
  colorSchemes: colorSchemesInput,
  defaultColorScheme: defaultColorSchemeInput,
}, ...args);

cssVariables: true로 만들면 colorSchemes: { light: {...}, dark: {...} }를 함께 정의할 수 있고, 실제 화면 전환은 CSS의 data-mui-color-scheme 어트리뷰트만 바꿔치기하면 된다 — React 리렌더링 없이 브라우저가 CSS 변수 값을 즉시 다시 계산해준다. useColorScheme() 훅으로 모드를 읽고 바꾸며, 서버 사이드 렌더링에서 "처음 깜빡이는(FOUC)" 문제도 InitColorSchemeScript가 막아준다.

④ slots·slotProps와 useSlotProps — 내부 구조를 열어주는 커스터마이징 API

Autocomplete·DataGrid류의 복합 컴포넌트는 내부에 여러 하위 요소(팝업, 리스트박스, 페이퍼 등)를 갖는다. 이를 개별적으로 바꿔치기·prop 추가할 수 있게 하는 것이 slots(컴포넌트 교체)와 slotProps(그 컴포넌트에 넘길 prop)다. 실제 구현은 @mui/utils의 useSlotProps(packages/mui-utils/src/useSlotProps/useSlotProps.ts)가 담당한다.

// 사용 예 — Select의 팝업 부분(paper)만 커스텀 스타일 주기
<Select
  slotProps={{
    paper: { sx: { borderRadius: 2 } },
  }}
>
  ...
</Select>

useSlotProps 내부는 외부에서 온 slotProps(함수 또는 객체 모두 허용)를 컴포넌트 내부 기본 props와 병합(mergeSlotProps)하고, ownerState(현재 상태값)를 필요하면 함께 넘겨준다. "라이브러리가 미리 정한 마크업 안에서, 내가 원하는 하위 요소만 정밀 타격으로 바꾼다"는 게 이 API의 핵심 아이디어이며, 최근 data-* 어트리뷰트도 slotProps에 직접 얹을 수 있도록 확장됐다(9.2.0 변경 로그).

⑤ Pigment CSS — 제로런타임 시도의 현황

MUI는 런타임에 스타일을 계산하는 Emotion 방식의 성능 한계(초기 렌더링·SSR 비용)를 넘기 위해 빌드타임에 CSS를 미리 뽑아내는 Pigment CSS를 실험해 왔다. 하지만 이 저장소 안의 packages/pigment-css-react·packages/pigment-react 폴더는 현재 빈 껍데기고, 실제 구현은 mui/pigment-css라는 별도 저장소로 옮겨졌다. 이 레포에 남아 있는 @mui/material-pigment-css는 "Pigment CSS 위에 Material UI와 같은 styled/테마 API를 얹어주는 얇은 어댑터"일 뿐이다.

⑥ MUI X와의 경계 — "복잡한 유료 컴포넌트는 여기 없다"

6기술 스택 · 의존성

버전의 진실원(source of truth)은 각 패키지 폴더의 package.json이다. 저장소 루트 package.json의 version(예: 9.2.0)은 모노레포 관리용 사설(private) 버전이고, 실제로 npm에 배포되는 @mui/material·@mui/system·@mui/utils 등은 Lerna의 independent 모드 덕에 패키지마다 다른 속도로 버전이 오를 수 있다(실제로 @mui/styled-engine은 9.1.1인데 @mui/material은 9.2.0인 시점이 있다). "루트 버전 = 전체 버전"이라고 단정하면 안 된다.

7설치 · 요구사항

일반 사용자(라이브러리로 쓰는 경우)는 매우 가볍다.

npm install @mui/material @emotion/react @emotion/styled
# 또는 styled-components 를 쓰고 싶다면:
npm install @mui/material @mui/styled-engine-sc styled-components

Roboto 폰트와 아이콘까지 쓰려면 @fontsource/roboto, @mui/icons-material을 추가로 설치한다. Next.js App Router라면 @mui/material-nextjs로 서버 컴포넌트 캐시 처리를 얹는 게 공식 권장이다.

8실제 사용 흐름

실제 화면 하나를 만드는 전형적인 흐름을 코드로 옮기면 다음과 같다.

import { createTheme, ThemeProvider, CssBaseline } from '@mui/material';
import Button from '@mui/material/Button';
import TextField from '@mui/material/TextField';

// 1) 앱 전역 테마 정의 — 색·다크모드 옵션까지 한 번에
const theme = createTheme({
  cssVariables: true,
  colorSchemes: { light: true, dark: true },
  palette: { primary: { main: '#1565c0' } },
});

function App() {
  return (
    <ThemeProvider theme={theme}>
      {/* 브라우저 기본 스타일 초기화 */}
      <CssBaseline />

      {/* 2) 컴포넌트 조립 — 이미 접근성·상태 처리 완료 */}
      <TextField label="이메일" fullWidth sx={{ mb: 2 }} />
      <Button variant="contained" sx={{ mt: 1 }}>
        가입하기
      </Button>
    </ThemeProvider>
  );
}

더 깊이 커스텀하고 싶으면 slots/slotProps로 내부 하위 요소를 겨냥하고, 아예 새 스타일드 컴포넌트가 필요하면 styled(Button)(...)로 확장한다. 다크모드 토글은 useColorScheme() 훅 하나로 끝난다 — 이 모든 게 위 5장에서 본 내부 설계(styled-engine 추상화·CSS 변수 테마·슬롯 API)가 실제 사용자에게 노출되는 표면이다.

9함정 · 오해 방지

10대안 비교

11정리 · 누가 쓰면 좋은가

Material UI는 "React 위에서 완성된 UI 부품 세트를 원하는 사람"에게 여전히 강력한 선택이다. 스타트업 MVP, 사내 어드민, 접근성이 중요한 공공·금융 서비스, "디자이너 없이도 봐줄 만한 화면"이 필요한 개인 프로젝트까지 폭넓게 맞는다. 반대로 처음부터 완전히 고유한 브랜드 룩을 원한다면 shadcn/ui 같은 복사형이나 Chakra·Mantine처럼 스타일 언어가 덜 고정된 쪽이 나을 수 있다.

레포 자체를 공부 대상으로 본다면, ① styled-engine 같은 "구현체를 갈아 끼울 수 있게 감추는" 어댑터 패턴, ② createTheme의 팔레트/스케일 자동 생성, ③ CSS 변수로 리렌더링 없이 다크모드를 전환하는 기법, ④ slots/slotProps로 "정해진 마크업 안에서 정밀하게 커스터마이징을 열어주는" API 설계, ⑤ 모노레포 안에서 패키지 경계·라이선스 경계(MUI X)를 어떻게 긋는지가 좋은 학습 포인트다.

12직접 해볼 수 있는 실습 과제

아래 과제는 의존성이 준비된 별도 실습용 사본에서 수행한다. 명령과 경로는 모두 Material UI 저장소 루트를 기준으로 한다. Node와 pnpm 요구사항은 그 사본의 package.json에서 확인한다.

pnpm --dir examples/material-ui-vite-ts dev
pnpm --dir examples/material-ui-vite-ts build

const theme = createTheme({
  cssVariables: { colorSchemeSelector: 'class' },
  colorSchemes: {
    light: { palette: { primary: { main: '#1565c0' } } },
    dark: { palette: { primary: { main: '#90caf9' } } },
  },
  spacing: 10,
});

<Dialog
  open={open}
  onClose={() => setOpen(false)}
  slotProps={{
    paper: {
      sx: { borderRadius: 3 },
      'data-testid': 'preview-paper',
    },
  }}
>
  <DialogTitle>설정 미리보기</DialogTitle>
  <DialogContent>
    <Button onClick={() => setOpen(false)}>닫기</Button>
  </DialogContent>
</Dialog>

pnpm test:unit run packages/mui-material/src/Button/Button.test.js --project 'node:@mui/material'

13관련 기술 심화 학습 로드맵

매주 “입력 속성 → 내부 처리 → 화면에서 관찰한 결과”를 연결해 기록한다. 실습은 앞의 설정 패널을 이어서 사용하고, 소스 읽기는 아래 경로를 기준으로 한다.

14핵심 키워드 사전