mantinedev/mantine 딥다이브
— "CSS-in-JS를 버린" 100개+ 컴포넌트 리액트 UI 킷

1한 줄 정체

Mantine은 리액트 개발자를 위한 "완제품 UI 부품 상자"다. 버튼·인풋·모달·테이블처럼 화면 어디에나 들어가는 기본 부품(@mantine/core)부터, 폼 상태 관리(@mantine/form), 날짜 선택기(@mantine/dates), 알림 토스트(@mantine/notifications), 차트(@mantine/charts), Ctrl+K 커맨드 팔레트(@mantine/spotlight)까지 — 실무에서 필요한 UI를 웬만하면 다 갖추고 있다.

더 중요한 건 스타일을 만드는 방식이다. 예전 버전(v6 이하)은 Emotion이라는 CSS-in-JS 라이브러리로 컴포넌트가 그려질 때마다 자바스크립트가 CSS 문자열을 계산해 <style> 태그로 밀어 넣었다. 지금(v7 이후, 현재 9.x)은 이 방식을 완전히 버리고, 색상·간격 같은 값은 빌드 시점에 고정된 .module.css 파일에 넣고, 인스턴스마다 달라지는 값(버튼 색상 등)만 CSS 변수를 담은 인라인 style로 갈아끼운다.

2왜 지금 뜨는가

2020년대 중반 리액트 생태계에서 벌어진 가장 큰 지각변동 중 하나가 "CSS-in-JS 이탈"이다. Emotion·styled-components처럼 런타임에 스타일을 계산하는 방식은 서버 컴포넌트(RSC)와 궁합이 나쁘고 번들·런타임 비용이 있다는 지적이 쌓였다. Mantine은 이 흐름을 가장 적극적으로, 그것도 대규모 컴포넌트 라이브러리 스케일에서 실제로 완주한 몇 안 되는 사례다.

① "Emotion 없이도 테마 가능"을 증명한 레퍼런스

많은 라이브러리가 "CSS-in-JS를 빼자"고 말은 하지만, Mantine처럼 Styles API(classNames/styles/vars/unstyled)를 그대로 유지하면서 내부 구현만 CSS Modules + CSS 변수로 완전히 갈아치운 사례는 드물다. "이렇게 하면 된다"는 실전 설계도로 자주 인용된다.

② 배터리 포함(batteries-included) 생산성

shadcn/ui류가 "복사해서 내 코드로 만드는" 방식이라면, Mantine은 npm install 한 번으로 폼 검증·날짜·차트·알림·커맨드 팔레트까지 끝난다. 스타트업이나 사이드 프로젝트에서 "UI 결정 피로"를 줄이고 싶을 때 여전히 강한 선택지다.

③ AI 코딩 시대에 맞춘 도구 확장 — @mantine/mcp-server

저장소 안에 AI 에이전트(Claude, Cursor 등)가 Mantine 문서를 직접 조회할 수 있는 MCP(Model Context Protocol) 서버 패키지가 정식으로 포함돼 있다. "AI가 UI 라이브러리를 얼마나 잘 아느냐"가 채택 기준이 되는 시대에, 공식 MCP 서버를 자체 제공하는 것은 눈에 띄는 선제 대응이다.

3무엇을 해결하나

Mantine이 실제로 없애주는 고통은 두 갈래다.

① "버튼부터 다시 만들기" 문제

새 프로젝트를 시작할 때마다 버튼·모달·드롭다운·폼 검증을 처음부터 짜는 건 시간 낭비다. Mantine은 116개 컴포넌트와 81개 유틸리티 훅(use-disclosure, use-debounced-value, use-hotkeys 등)으로 이 반복을 없앤다. 접근성(ARIA, 키보드 내비게이션)과 다크모드도 기본 내장이라 따로 신경 쓸 게 적다.

② "런타임 스타일 계산" 문제

Emotion 같은 CSS-in-JS는 컴포넌트가 리렌더될 때마다 스타일 객체를 해시하고 <style> 태그에 새로 주입하는 계산 비용이 든다. 서버 컴포넌트 환경에서는 이 계산이 애초에 서버에서 도는 게 애매해지는 문제도 있다. Mantine은 스타일 결정을 대부분 빌드 시점으로 옮기고, 런타임에는 "이미 있는 CSS 변수 값만 바꿔치기"하는 값싼 연산만 남겼다.

4전체 구조

저장소는 Yarn 4 워크스페이스 기반 모노레포(package.json의 workspaces: ["packages/**/*", "apps/*"])이며, 실제 배포 패키지는 packages/@mantine/ 아래 15개, 테스트 전용 유틸은 packages/@mantine-tests/, 문서 사이트는 apps/mantine.dev·apps/help.mantine.dev에 있다.

의존 방향은 단방향이다. @mantine/hooks는 아무것도 의존하지 않는 최하위 레이어, @mantine/core는 hooks에만 의존, 그 위의 form·dates·notifications·charts·spotlight·modals 같은 "확장 패키지"는 모두 core와 hooks를 peerDependency로 요구한다. 즉 @mantine/core가 사실상 프레임워크의 심장이고, 나머지는 그 위에 얹힌 플러그인이다.

5핵심 설계 · 동작 원리

이 장이 Mantine 이해의 핵심이다. "classNames·styles·unstyled로 커스터마이징 가능한 컴포넌트를, Emotion 없이 어떻게 만드는가"를 실제 소스로 뜯어본다.

① 모든 컴포넌트를 찍어내는 틀 — factory()

packages/@mantine/core/src/core/factory/factory.tsx의 factory() 함수는 평범한 함수형 컴포넌트를 받아 .extend()와 .withProps()라는 두 정적 메서드를 붙여 돌려준다. .extend()는 테마에서 이 컴포넌트의 기본값을 재정의할 때, .withProps()는 특정 props가 고정된 파생 컴포넌트를 만들 때 쓴다. Mantine의 모든 컴포넌트(Button, TextInput …)는 예외 없이 이 factory 또는 다형성 버전인 polymorphicFactory로 만들어진다.

// factory.tsx (실제 소스 요약)
export function factory<Payload>(ui) {
  const Component = ui;
  Component.extend = identity;         // 테마에서 defaultProps/classNames 재정의
  Component.withProps = (fixedProps) => {
    const Extended = (props) => <Component {...fixedProps} {...props} />;
    return Extended;
  };
  return Component;
}

② props의 3단 우선순위 — useProps()

컴포넌트 내부에서는 가장 먼저 useProps('Button', null, _props)를 호출한다. 이 훅(core/MantineProvider/use-props/use-props.ts)은 "실제로 넘어온 props" > "MantineProvider 테마의 theme.components.Button.defaultProps" > "컴포넌트 자체 기본값" 순서로 병합한다. 그래서 <MantineProvider theme={{ components: { Button: Button.extend({ defaultProps: { radius: 'xl' } }) } }}>처럼 앱 전체의 모든 버튼 기본 반경을 한 곳에서 바꿀 수 있다.

③ 클래스와 인라인 스타일을 동시에 계산 — useStyles()

Button 컴포넌트 내부의 실제 코드다: const getStyles = useStyles({ name: 'Button', props, classes, classNames, styles, unstyled, vars, varsResolver }). 이 getStyles('root', {...}) 호출이 리턴하는 { className, style }를 그대로 DOM에 스프레드한다 — <UnstyledButton {...getStyles('root', ...)}>. useStyles(core/styles-api/use-styles/use-styles.ts) 내부는 4겹을 합성한다.

1. 정적 클래스 — 빌드된 Button.module.css의 .root 클래스 (항상 붙는다)
2. 테마 단위 classNames/styles — theme.components.Button.classNames
3. 인스턴스 단위 classNames/styles prop — 이 버튼 하나에만 준 값
4. 동적 CSS 변수 — varsResolver(theme, props, ctx)가 계산한 { '--button-bg': ... }를 인라인 style로 병합

마지막 4번이 핵심이다. Button의 varsResolver는 이렇게 생겼다(실제 소스, Button.tsx):

const varsResolver = createVarsResolver<ButtonFactory>(
  (theme, { radius, color, gradient, variant, size }) => {
    const colors = theme.variantColorResolver({ color, theme, gradient, variant });
    return {
      root: {
        '--button-height': getSize(size, 'button-height'),
        '--button-bg': colors.background,
        '--button-color': colors.color,
        // ...
      },
    };
  }
);

이 결과가 DOM에 인라인 style="--button-bg: #1c5fd6; --button-height: 42px"로 찍히고, Button.module.css는 background: var(--button-bg, var(--mantine-primary-color-filled))처럼 그 변수를 참조만 한다. 즉 CSS는 빌드 때 이미 완성돼 있고, React는 매 렌더마다 "변수 값 몇 개"만 계산해 인라인으로 얹는다 — Emotion처럼 스타일시트 자체를 새로 만들지 않는다.

④ 전역 값은 "빌드 타임에 굳힌다" — default-css-variables.css

버튼 배경색처럼 인스턴스마다 달라지는 값은 위 방식으로 런타임에 넣지만, --mantine-spacing-md·--mantine-color-blue-6처럼 테마 전체에서 한 벌만 있으면 되는 값은 아예 빌드 스크립트(scripts/codegen/generate-default-css-variables.ts)가 DEFAULT_THEME을 읽어 정적 CSS 파일(default-css-variables.css, 527줄)로 미리 생성해 둔다. 앱이 <MantineProvider>로 테마를 바꾸면 이 파일 대신 MantineCssVariables 컴포넌트가 루트 <style> 하나만 다시 계산해 갈아끼운다 — 컴포넌트마다 스타일시트를 다시 만드는 게 아니라 "이 앱 전체에 딱 하나 있는 변수 사전"만 바꾸는 것이다.

⑤ 다크모드 — 깜빡임 없는 ColorSchemeScript

다크모드는 새 스타일시트가 아니라 <html data-mantine-color-scheme="dark"> 속성 하나로 전환된다. 모든 색상 변수가 [data-mantine-color-scheme="dark"] 셀렉터 아래 다시 정의돼 있을 뿐이다. 문제는 서버 렌더링(SSR) 시 "깜빡임(FOUC)"인데, Mantine은 <head>에 심는 <ColorSchemeScript>가 브라우저가 리액트를 실행하기도 전에 localStorage를 읽어 이 속성을 즉시 세팅하는 인라인 <script>를 실제로 렌더한다:

// ColorSchemeScript.tsx가 만드는 스크립트(실제 소스)
try {
  var _colorScheme = window.localStorage.getItem("mantine-color-scheme-value");
  var colorScheme = (_colorScheme === "light" || _colorScheme === "dark" || _colorScheme === "auto")
    ? _colorScheme : "light";
  var computed = colorScheme !== "auto" ? colorScheme
    : (window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light");
  document.documentElement.setAttribute("data-mantine-color-scheme", computed);
} catch (e) {}

⑥ unstyled와 headless — "스타일을 아예 끄는" 탈출구

각 컴포넌트 unstyled prop이나 MantineProvider의 headless 모드를 켜면 useStyles가 Mantine의 기본 클래스·변수 주입을 전부 건너뛴다. Tailwind나 다른 디자인 시스템 위에 Mantine의 "동작(behavior)"만 얹고 싶은 팀을 위한 탈출구다.

6기술 스택 · 의존성

7설치 · 요구사항

8실제 사용 흐름

import { MantineProvider, ColorSchemeScript } from '@mantine/core';
import '@mantine/core/styles.css';

export default function RootLayout({ children }) {
  return (
    <html lang="ko">
      <head><ColorSchemeScript /></head>
      <body>
        <MantineProvider theme={{ primaryColor: 'blue' }}>
          {children}
        </MantineProvider>
      </body>
    </html>
  );
}

import { Button, TextInput, Group } from '@mantine/core';

function LoginForm() {
  return (
    <Group>
      <TextInput label="이메일" placeholder="you@example.com" />
      <Button color="blue" radius="md">로그인</Button>
    </Group>
  );
}

import { useForm } from '@mantine/form';
import { notifications } from '@mantine/notifications';

const form = useForm({
  initialValues: { email: '' },
  validate: { email: (v) => (/^\S+@\S+$/.test(v) ? null : '이메일 형식 오류') },
});

function onSubmit(values) {
  notifications.show({ message: '저장 완료', color: 'green' });
}

// 인스턴스 하나만 커스터마이징
<Button
  classNames={{ root: styles.myButton }}
  styles={{ root: { textTransform: 'uppercase' } }}
>확인</Button>

// 앱 전체 버튼 기본값을 한 곳에서 바꾸기
<MantineProvider theme={{
  components: {
    Button: Button.extend({ defaultProps: { radius: 'xl' } }),
  },
}}>

9함정 · 오해 방지

10대안 비교

11정리 · 누가 쓰면 좋은가

Mantine은 "CSS-in-JS 없이도 강력하게 커스터마이징 가능한 완제품 컴포넌트 라이브러리"를 대규모로 증명한 프로젝트다. factory로 컴포넌트를 찍어내고, useProps로 테마 기본값을 주입하고, useStyles가 정적 CSS Modules와 동적 CSS 변수를 인라인 스타일로 합성하는 삼각 구조가 116개 컴포넌트 전체에 일관되게 적용돼 있다.

코드를 배우는 관점에서는, "CSS-in-JS 없이 다크모드·테마·컴포넌트 커스터마이징을 어떻게 설계하는가"를 실제 프로덕션 규모로 보여주는 교재로서 가치가 크다. packages/@mantine/core/src/core 폴더 하나만 정독해도 현대 리액트 UI 라이브러리의 스타일 아키텍처를 상당 부분 이해할 수 있다.

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

아래 실습은 의존성이 이미 준비된 개인 학습용 사본에서 진행한다. 경로와 명령의 기준은 Mantine 저장소 루트다. 실행 환경은 해당 사본의 .nvmrc와 루트 package.json에서 확인한다. Storybook의 예제 선택 방식은 .storybook/main.ts, 공통 테마 설정은 .storybook/preview.tsx에 있다.

COMPONENT=Button npm run storybook

export function ThemePractice() {
  return (
    <MantineProvider
      theme={{
        components: {
          Button: Button.extend({ defaultProps: { radius: 'xl' } }),
        },
      }}
    >
      <Button>테마 기본값</Button>
      <Button radius="sm">직접 지정한 값</Button>
    </MantineProvider>
  );
}

COMPONENT=UseLocalStorage npm run storybook

export function ReadingProgress() {
  const [count, setCount, removeCount] = useLocalStorage<number>({
    key: 'mantine-study-progress',
    defaultValue: 0,
  });

  return (
    <div>
      <p>완료한 과제: {count}</p>
      <button type="button" onClick={() => setCount((value) => value + 1)}>
        하나 완료
      </button>
      <button type="button" onClick={removeCount}>초기화</button>
    </div>
  );
}

npm run jest -- --runInBand packages/@mantine/hooks/src/use-local-storage/use-local-storage.test.ts

COMPONENT=Form npm run storybook

<Button type="button" onClick={() => form.setFieldValue('name', '연습생')}>
  이름 채우기
</Button>
<Button type="button" onClick={() => form.reset()}>초기화</Button>

npm run jest -- --runInBand packages/@mantine/form/src/tests/use-form/getInputProps.test.ts

npm run jest -- --runInBand packages/@mantine/core/src/core/styles-api/use-styles/get-style/resolve-vars/resolve-vars.test.ts

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

한 번에 모든 컴포넌트를 읽기보다 버튼 하나의 속성값이 화면에 도착하는 경로를 먼저 따라간다. 이후 상태 관리·폼·초기 색상 설정으로 넓히면 같은 설계가 어디에서 반복되는지 보인다.

매주 결과물에는 “어떤 값을 바꾸었는가 → 어느 함수가 처리했는가 → 무엇으로 확인했는가”를 남긴다. 화면 확인과 객체·속성 검증을 구분하면, 테스트가 통과했을 때 어디까지 믿을 수 있는지도 함께 배울 수 있다.

14핵심 키워드 사전