MantineProvider

MantineProvider는 theme 객체 컨텍스트 값을 제공하고, 색상 체계 변경을 관리하며, CSS variables를 주입해요. 애플리케이션의 루트에서 렌더링해야 하며 한 번만 사용해야 해요.

출처: 문서

본문

사용법

import { createTheme, MantineProvider } from '@mantine/core';

const theme = createTheme({
  /** Your theme override here */
});

function Demo() {
  return (
    <MantineProvider theme={theme}>
      {/* Your app here */}
    </MantineProvider>
  );
}

MantineProvider props

MantineProvider는 다음 props를 지원해요:

interface MantineProviderProps {
  /** Theme override object */
  theme?: MantineThemeOverride;

  /** Used to retrieve/set color scheme value in external storage; by default uses `window.localStorage` */
  colorSchemeManager?: MantineColorSchemeManager;

  /** Default color scheme value used when `colorSchemeManager` cannot retrieve value from external storage; `light` by default */
  defaultColorScheme?: MantineColorScheme;

  /** Forces color scheme value; if set, MantineProvider ignores `colorSchemeManager` and `defaultColorScheme` */
  forceColorScheme?: 'light' | 'dark';

  /** CSS selector to which CSS variables should be added, by default variables are applied to `:root` and `:host` */
  cssVariablesSelector?: string;

  /** Determines whether theme CSS variables should be added to given `cssVariablesSelector`; `true` by default */
  withCssVariables?: boolean;

  /** Determines whether CSS variables should be deduplicated: if CSS variable has the same value as in default theme, it is not added in the runtime; `true` by default. */
  deduplicateCssVariables?: boolean;

  /** Function to resolve root element to set `data-mantine-color-scheme` attribute; must return undefined on server, `() => document.documentElement` by default */
  getRootElement?: () => HTMLElement | undefined;

  /** A prefix for components' static classes (for example {selector}-Text-root); `mantine` by default */
  classNamesPrefix?: string;

  /** Function to generate nonce attribute added to all generated <style> tags */
  getStyleNonce?: () => string;

  /** Function to generate CSS variables based on theme object */
  cssVariablesResolver?: CSSVariablesResolver;

  /** Determines whether components should have static classes, for example, `mantine-Button-root`; `true` by default */
  withStaticClasses?: boolean;

  /** Determines whether global classes should be added with <style> tag. Global classes are required for `hiddenFrom`/`visibleFrom` and `lightHidden`/`darkHidden` props to work; `true` by default. */
  withGlobalClasses?: boolean;

  /** Determines whether inline styles with identical content should be deduplicated using React 19 style hoisting. When enabled, components with the same responsive style props share a single <style> tag instead of each generating their own. @default false */
  deduplicateInlineStyles?: boolean;

  /** Environment in which the provider is used; `'test'` environment disables all transitions and portals */
  env?: 'default' | 'test';

  /** Your application */
  children?: React.ReactNode;
}

theme

theme prop에 theme 객체 override를 전달해요. 기본 theme과 병합되어 모든 컴포넌트에서 사용돼요.

import { createTheme, MantineProvider } from '@mantine/core';

const theme = createTheme({
  fontFamily: 'Open Sans, sans-serif',
  primaryColor: 'cyan',
});

function Demo() {
  return (
    <MantineProvider theme={theme}>
      {/* Your app here */}
    </MantineProvider>
  );
}

colorSchemeManager

colorSchemeManager는 외부 저장소에서 색상 체계 값을 가져오고 설정하는 데 사용돼요. 기본적으로 MantineProvider는 색상 체계 값을 저장하기 위해 window.localStorage를 사용하지만, 자신만의 구현을 colorSchemeManager prop에 전달할 수 있어요. 색상 체계 관리에 대해 더 자세히 알아보려면 색상 체계 가이드를 참고하세요.

import {
  localStorageColorSchemeManager,
  MantineProvider,
} from '@mantine/core';

const colorSchemeManager = localStorageColorSchemeManager({
  key: 'my-app-color-scheme',
});

function Demo() {
  return (
    <MantineProvider colorSchemeManager={colorSchemeManager}>
      {/* Your app here */}
    </MantineProvider>
  );
}

defaultColorScheme

defaultColorScheme 값은 colorSchemeManager가 외부 저장소에서 값을 가져올 수 없을 때 사용돼요. 예를 들어 서버 사이드 렌더링 중이거나 사용자가 선호 색상 체계를 선택하지 않았을 때요. 가능한 값은 light, dark, auto예요. 기본적으로 색상 체계 값은 light예요. 색상 체계 관리에 대해 더 자세히 알아보려면 색상 체계 가이드를 참고하세요.

import { MantineProvider } from '@mantine/core';

function Demo() {
  return (
    <MantineProvider defaultColorScheme="auto">
      {/* Your app here */}
    </MantineProvider>
  );
}

cssVariablesSelector

cssVariablesSelector는 CSS variables가 추가되어야 하는 CSS selector예요. 기본적으로 변수는 :root와 :host에 적용돼요. MantineProvider는 주어진 theme override와 cssVariablesResolver를 기반으로 CSS variables를 생성한 다음, 이 변수들을 애플리케이션 옆의 `` 태그로 렌더링해요. Mantine CSS variables에 대해 더 자세히 알아보려면 CSS variables 가이드를 참고하세요.

import { MantineProvider } from '@mantine/core';

function Demo() {
  return (
    <MantineProvider cssVariablesSelector=".app">
      {/* Your app here */}
    </MantineProvider>
  );
}

withCssVariables

withCssVariables는 theme CSS variables를 주어진 cssVariablesSelector에 추가할지 여부를 결정해요. 기본적으로 true로 설정돼요. .css 파일로 CSS variables를 관리하려면 바꾸지 않아야 해요(이 경우 기본 theme의 일부가 아닌 모든 theme 토큰을 직접 생성해야 한다는 점에 주의하세요).

import { MantineProvider } from '@mantine/core';

function Demo() {
  return (
    <MantineProvider withCssVariables={false}>
      {/* Your app here */}
    </MantineProvider>
  );
}

deduplicateCssVariables

deduplicateCssVariables는 CSS variables를 중복 제거할지 여부를 결정해요: CSS variable이 기본 theme과 같은 값을 가지면 런타임에 추가되지 않아요. 기본적으로 true로 설정돼요. false로 설정하면 기본 theme과 같은 값을 가지더라도 모든 Mantine CSS variables가 `` 태그에 추가돼요.

import { MantineProvider } from '@mantine/core';

function Demo() {
  return (
    <MantineProvider deduplicateCssVariables={false}>
      {/* Your app here */}
    </MantineProvider>
  );
}

deduplicateInlineStyles

deduplicateInlineStyles는 반응형 style props에 대해 React 19 스타일 태그 중복 제거를 활성화해요. 여러 컴포넌트가 같은 반응형 style prop 값을 공유할 때(예: mt={{ base: 10, md: 20 }}을 가진 많은 목록 항목), 각 컴포넌트가 자신의 을 주입하는 대신 하나의 태그만 생성되어 ``로 끌어올려져요.

이것은 많은 컴포넌트가 같은 반응형 style props를 사용하는 상황에서 성능을 크게 향상시킬 수 있어요. 자세한 내용은 styles performance 가이드를 참고하세요.

import { MantineProvider } from '@mantine/core';

function Demo() {
  return (
    <MantineProvider deduplicateInlineStyles>
      {/* Your app here */}
    </MantineProvider>
  );
}

getRootElement

getRootElement는 data-mantine-color-scheme 속성을 설정할 루트 애플리케이션 요소(보통 html)를 반환하는 함수예요. 기본값은 () => document.documentElement로, data-mantine-color-scheme 속성이 `` 태그에 추가된다는 뜻이에요. 색상 체계 관리에 대해 더 자세히 알아보려면 색상 체계 가이드를 참고하세요.

import { MantineProvider } from '@mantine/core';

const getRootElement = () =>
  typeof window === 'undefined' ? undefined : document.body;

function Demo() {
  return (
    <MantineProvider getRootElement={getRootElement}>
      {/* Your app here */}
    </MantineProvider>
  );
}

classNamesPrefix

classNamesPrefix는 컴포넌트의 정적 클래스(예: {selector}-Text-root)의 접두사예요. 기본값은 mantine – 모든 컴포넌트가 정적 클래스에 mantine- 접두사를 가져요.

import { MantineProvider, Text } from '@mantine/core';

function Demo() {
  return (
    <MantineProvider>
      <Text>Just some text</Text>
    </MantineProvider>
  );
}

이 경우(기본 classNamesPrefix) Text 컴포넌트는 다음 클래스를 가져요:

mantine-focus-auto – 전역 유틸리티 클래스
m-3nrA4eL – 컴포넌트 클래스, 보통 임의의 문자열; 이 클래스로 라이브러리 스타일이 적용돼요
mantine-Text-root – 컴포넌트 정적 클래스, Styles API의 일부

classNamesPrefix로 정적 클래스만 바꿀 수 있어요:

import { MantineProvider, Text } from '@mantine/core';

function Demo() {
  return (
    <MantineProvider classNamesPrefix="app">
      <Text>Just some text</Text>
    </MantineProvider>
  );
}

이제 Text 컴포넌트는 다음 클래스를 가져요:

mantine-focus-auto – classNamesPrefix는 전역 유틸리티 클래스에 영향을 주지 않아요 – 정적이며 변경할 수 없어요
m-3nrA4eL – classNamesPrefix는 라이브러리 클래스에 영향을 주지 않아요 – 정적이며 변경할 수 없어요
app-Text-root – 컴포넌트 정적 클래스가 mantine 대신 classNamesPrefix를 가져요

withStaticClasses

withStaticClasses는 컴포넌트가 mantine-Button-root 같은 정적 클래스를 가질지 여부를 결정해요. 기본적으로 정적 클래스는 활성화돼요. 비활성화하려면 withStaticClasses를 false로 설정해요:

import { MantineProvider } from '@mantine/core';

function Demo() {
  return (
    <MantineProvider withStaticClasses={false}>
      {/* Your app here */}
    </MantineProvider>
  );
}

withGlobalClasses

withGlobalClasses는 전역 클래스를 `` 태그로 추가할지 여부를 결정해요. 전역 클래스는 hiddenFrom/visibleFrom과 lightHidden/darkHidden props가 동작하는 데 필요해요. 기본적으로 전역 클래스는 활성화돼요. 비활성화하려면 withGlobalClasses를 false로 설정해요. 전역 클래스를 비활성화하면 일부 컴포넌트의 스타일이 깨질 수 있다는 점에 주의하세요.

import { MantineProvider } from '@mantine/core';

function Demo() {
  return (
    <MantineProvider withGlobalClasses={false}>
      {/* Your app here */}
    </MantineProvider>
  );
}

getStyleNonce

getStyleNonce는 동적으로 생성된 `` 태그에 추가되는 nonce 속성을 생성하는 함수예요.

cssVariablesResolver

cssVariablesResolver는 theme 객체를 기반으로 CSS variables 스타일을 생성하는 함수예요. Mantine CSS variables에 대해 더 자세히 알아보려면 CSS variables 가이드를 참고하세요.

env

env prop은 테스트 환경에서 테스트에 영향을 주거나 컴포넌트 테스트를 어렵게 만들 수 있는 일부 기능을 비활성화하는 데 사용할 수 있어요:

자식 컴포넌트를 지연으로 마운트/언마운트하는 전환(transition)
자식 컴포넌트를 DOM의 다른 부분에 렌더링하는 portal

테스트 환경을 활성화하려면 env를 test로 설정해요:

import { MantineProvider } from '@mantine/core';

function Demo() {
  return (
    <MantineProvider env="test">
      {/* Your app here */}
    </MantineProvider>
  );
}

env="test"는 Jest나 Vitest 같은 테스트 환경에서만 사용하도록 의도된 것이라는 점에 주의하세요. 개발이나 프로덕션 환경에서는 사용하지 마세요. Cypress나 Playwright 같은 end-to-end 테스트 도구에서 사용하는 것도 권장되지 않아요.

MantineProvider

MantineProvider

본문

사용법

MantineProvider props

theme

colorSchemeManager

defaultColorScheme

cssVariablesSelector

withCssVariables

deduplicateCssVariables

deduplicateInlineStyles

getRootElement

classNamesPrefix

withStaticClasses

withGlobalClasses

getStyleNonce

cssVariablesResolver

env

더 알아보기 (Learn more)