テーマをカスタマイズする

すべてのYamada UIのコンポーネントは、テーマからスタイルやトークンを継承します。シナリオによっては、プロジェクトに合わせたカラーなどをカスタマイズする必要がある場合があります。

テーマをカスタマイズする場合は、extendThemeを使用することをオススメします。これは、デフォルトのテーマを継承したテーマを作成します。extendThemeを使用しない場合は、デフォルトのテーマを継承せず全く新しいテーマになります。

テーマの運用

テーマをカスタマイズした場合、型補完をすることをオススメします。型補完は、CLIを使用します。

CLIを使用する場合は、ファイルのデフォルトでエクスポートされているテーマを参照するので、テーマのファイルを作成する必要があります。

開発中にテーマのトークンやスタイルが追加・変更することを考えて、テーマをフォルダにしておくことをオススメします。

./theme
├ components # 各コンポーネントのスタイルを定義するフォルダ
├ tokens # 各トークンを定義するフォルダ
├ styles # グローバルスタイルやリセットスタイルを定義するフォルダ
├ config.ts # コンフィグを設定するファイル
└ index.ts # テーマをデフォルトでエクスポートするファイル

./theme/index.ts

import { extendTheme, UsageTheme } from "@yamada-ui/react"
// import styles from './styles'
// import components from './components'
// import tokens from './tokens'

const customTheme: UsageTheme = {
  // styles,
  // components,
  // ...tokens,
}

export default extendTheme(customTheme)()

extendThemeを使用して、テーマをデフォルトでエクスポートしています。

テーマの適用

テーマを適用する場合は、UIProviderのthemeに渡します。

Create React Appの場合

index.tsx

import { createRoot } from "react-dom/client"
import { App } from "./app"
import { UIProvider } from "@yamada-ui/react"
import { theme } from "theme"

const container = document.getElementById("app")

const root = createRoot(container!)

root.render(
  <UIProvider theme={theme}>
    <App />
  </UIProvider>,
)

Next.jsの場合

_app.tsx

import type { AppProps } from "next/app"
import { UIProvider } from "@yamada-ui/react"
import { theme } from "theme"

const App = ({ Component, pageProps }: AppProps) => {
  return (
    <UIProvider theme={theme}>
      <Component {...pageProps} />
    </UIProvider>
  )
}

export default App

Viteの場合

.main.tsx

import React from "react"
import ReactDOM from "react-dom/client"
import App from "./App.tsx"
import { UIProvider } from "@yamada-ui/react"
import { theme } from "theme"

ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <UIProvider theme={theme}>
      <App />
    </UIProvider>
  </React.StrictMode>,
)

トークンを変更する

今回は、colorsに新しいトークンと既存のトークンを変更してみましょう。

tokensの配下にcolors.tsを作成します。

./theme/tokens/colors.ts

import { ThemeTokens } from "@yamada-ui/react"

export const colors: ThemeTokens = {
  banner: "#9d38a0",
  black: ["#1F2123", "#101112"],
}

colorsに新しくbannerを追加し、blackを変更しています。また、配列を定義することで、カラーモードに対応できます。

index.tsを作成し、先ほど作成したcolorsをエクスポートします。

./theme/tokens/index.ts

import { colors } from "./colors"

export default { colors }

customThemeにtokensを含めます。

./theme/index.ts

import { extendTheme, UsageTheme } from "@yamada-ui/react"
// import styles from './styles'
// import components from './components'
import tokens from "./tokens"

const customTheme: UsageTheme = {
  // styles,
  // components,
  ...tokens,
}

export default extendTheme(customTheme)()

もし、デフォルトのテーマからcolorsだけ継承したくない場合は、extendThemeにomitを渡します。

./theme/index.ts

import { extendTheme, UsageTheme } from "@yamada-ui/react"
// import styles from './styles'
// import components from './components'
import tokens from "./tokens"

const customTheme: UsageTheme = {
  // styles,
  // components,
  ...tokens,
}

export default extendTheme(customTheme)({ omit: ["colors"] })

セマンティックトークンを変更する

セマンティックトークンの中に、各コンポーネントで使用されるカラースキーマが設定されています。

実際に設定されている値はこちらです。

export const semantics: ThemeSemantics = {
  colors: {
    primary: "blue.500",
    secondary: "violet.500",
    info: "blue.500",
    success: "green.500",
    warning: "orange.500",
    danger: "red.500",
    link: "blue.500",
  },
  colorSchemes: {
    primary: "blue",
    secondary: "violet",
    info: "blue",
    success: "green",
    warning: "orange",
    danger: "red",
    link: "blue",
  },
}

今回は、デフォルトのカラースキーマを変更してみましょう。

themeの配下にsemantics.tsを作成します。

./theme/semantics.ts

import { ThemeSemantics } from "@yamada-ui/react"

export const semantics: ThemeSemantics = {
  colors: {
    primary: "pink.500",
  },
  colorSchemes: {
    primary: "pink",
  },
}

customThemeにsemanticsを含めます。

./theme/index.ts

import { extendTheme, UsageTheme } from "@yamada-ui/react"
// import styles from './styles'
// import components from './components'
import tokens from "./tokens"
import { semantics } from "./semantics"

const customTheme: UsageTheme = {
  // styles,
  // components,
  semantics,
  ...tokens,
}

export default extendTheme(customTheme)()

セマンティックトークンをもっと学びたい場合は、こちらをご覧ください。

スタイルを変更する

stylesにはglobalStyle・resetStyle・layerStyles・textStylesなどを設定できます。

今回は、bodyのスタイルなどを設定するglobalStyleを変更してみましょう。

stylesの配下にglobal-style.tsを作成します。

./theme/styles/global-style.ts

import { UIStyle } from "@yamada-ui/react"

export const globalStyle: UIStyle = {
  body: {
    bg: ["black", "white"],
  },
}

bodyの背景を変更しています。また、配列を定義することで、カラーモードに対応できます。

index.tsを作成し、先ほど作成したglobalStyleをエクスポートします。

./theme/styles/index.ts

import { globalStyle } from "./global-style"

export default { globalStyle }

customThemeにstylesを含めます。

./theme/index.ts

import { extendTheme, UsageTheme } from "@yamada-ui/react"
import styles from "./styles"
// import components from './components'
import tokens from "./tokens"
import { semantics } from "./semantics"

const customTheme: UsageTheme = {
  styles,
  // components,
  semantics,
  ...tokens,
}

export default extendTheme(customTheme)()

もし、デフォルトのテーマからstylesだけ継承したくない場合は、extendThemeにomitを渡します。

./theme/index.ts

import { extendTheme, UsageTheme } from "@yamada-ui/react"
import styles from "./styles"
// import components from './components'
import tokens from "./tokens"
import { semantics } from "./semantics"

const customTheme: UsageTheme = {
  styles,
  // components,
  semantics,
  ...tokens,
}

export default extendTheme(customTheme)({ omit: ["styles"] })

テキストとレイヤースタイルを学びたい場合は、こちらをご覧ください。

コンポーネントのスタイルを変更する

プロジェクトによって、Yamada UIのコンポーネントのスタイルを変更したい場合があります。Yamada UIのコンポーネントは、テーマのスタイルを参照しているので簡単にコンポーネントのスタイルを変更することができます。

コンポーネントのスタイルは、コンポーネントの基本スタイル(baseStyle)、さまざまなサイズのスタイル(sizes)、さまざまなビジュアルのスタイル(variants)、デフォルトのprops(defaultProps)で構成されています。

すべてのコンポーネントは、sizeやvariantがあるわけではありません。どのコンポーネントが対応しているかを確認するには、コンポーネントのページのpropsを参照してください。

Yamada UIは、コンポーネントにスタイルのpropsを設定することでスタイリングすることができます。しかし、大規模なプロジェクトは開発者が多く、個々でスタイルを設定するとデザインの一貫性を担保できなくなります。その場合、共通しているスタイルをテーマのコンポーネントのスタイルに設定することで回避することができます。

今回は、コンポーネントのContainerを変更してみましょう。

componentsの配下にcontainer.tsを作成します。

./theme/components/container.ts

import { ComponentStyle } from "@yamada-ui/react"

export const Container: ComponentStyle = {
  baseStyle: {
    bg: "green.100",
  },
  sizes: {
    sm: { p: "sm", fontSize: "sm" },
    md: { p: "md", fontSize: "md" },
    lg: { p: "lg", fontSize: "lg" },
  },
  variants: {
    "wtih-border-solid": {
      borderWidth: "1px",
    },
    "wtih-border-dotted": {
      borderWidth: "1px",
      borderStyle: "dotted",
    },
  },
  defaultProps: {
    size: "md",
    variant: "wtih-border-solid",
  },
}

背景色を変更し、sizesで各サイズを、variantsで各バリアントを定義しています。defaultPropsは、初期値を設定しています。

index.tsを作成し、先ほど作成したContainerをエクスポートします。

./theme/components/index.ts

import { Container } from "./container"

export default { Container }

customThemeにcomponentsを含めます。

./theme/index.ts

import { extendTheme, UsageTheme } from "@yamada-ui/react"
import styles from "./styles"
import components from "./components"
import tokens from "./tokens"
import { semantics } from "./semantics"

const customTheme: UsageTheme = {
  styles,
  components,
  semantics,
  ...tokens,
}

export default extendTheme(customTheme)()

これで、Containerの背景色は変更され、sizeまたはvariantを渡すことでスタイルが変更されます。

import { Container } from "@yamada-ui/react"

const Demo = () => {
  return (
    <Container size="sm" variant="with-border-dotted">
      This is Container
    </Container>
  )
}

今回変更したContainerは、単一の要素で構成されるコンポーネントです。また、複数の要素で構成されるコンポーネント(Accordionなど)があります。複数の要素で構成されるコンポーネントを変更する場合、型定義はComponentMultiStyleになります。

各コンポーネントのテーマのスタイルを確認するには、コンポーネントのページのテーマを参照してください。

Yamada UIが提供するコンポーネントに限らず、独自のカスタムコンポーネントのスタイルを作成することができます。詳しくは、こちらをご覧ください。

ユーティリティ

Yamada UIは、テーマのユーティリティを多く提供しています。

`extendTheme`を使う

デフォルトのテーマを継承して、新しいテーマを作成します。複数のオブジェクトを渡すことも可能です。また、オプションを指定することも可能です。

複数のテーマをマージする

./theme/index.ts

import { extendTheme, UsageTheme } from "@yamada-ui/react"

const firstTheme: UsageTheme = {}
const secondTheme: UsageTheme = {}

export default extendTheme(firstTheme, secondTheme)()

デフォルトのテーマを継承しない

./theme/index.ts

import { extendTheme, UsageTheme } from "@yamada-ui/react"

const firstTheme: UsageTheme = {}
const secondTheme: UsageTheme = {}

export default extendTheme(firstTheme, secondTheme)({ merge: false })

デフォルトテーマから特定のトークンを除外して継承する

./theme/index.ts

import { extendTheme, UsageTheme } from "@yamada-ui/react"

const customTheme: UsageTheme = {}

export default extendTheme(customTheme)({ omit: ["colors"] })

デフォルトテーマから特定のトークンだけ継承する

./theme/index.ts

import { extendTheme, UsageTheme } from "@yamada-ui/react"

const customTheme: UsageTheme = {}

export default extendTheme(customTheme)({ pick: ["spaces"] })

`extendBaseTheme`を使う

デフォルトのテーマのグローバルスタイルやカラーなどのトークンのみを継承して、新しいテーマを作成します。複数のオブジェクトを渡すことも可能です。また、オプションを指定することも可能です。

./theme/index.ts

import { extendBaseTheme, UsageTheme } from "@yamada-ui/react"
import styles from "./styles"
import tokens from "./tokens"

const customTheme: UsageTheme = {
  styles,
  ...tokens,
}

export default extendBaseTheme(customTheme)()

extendBaseThemeは、内部的にbaseThemeを使用しています。baseThemeは、グローバルスタイルやカラーなどのトークンは定義されていますが、コンポーネントのスタイルが定義されていません。

`extendStyle`を使う

globalStyleやresetStyleを継承して、新しいスタイルを作成します。

import { extendStyle, UIStyle } from "@yamada-ui/react"

const globalStyle: UIStyle = extendStyle("globalStyle", {
  /**
   * 追加のスタイルを定義する
   */
})

`extendToken`を使う

特定のトークンを継承して、新しいトークンを作成します。

import { extendToken, ThemeTokens } from "@yamada-ui/react"

const colors: ThemeTokens = extendToken("colors", {
  /**
   * 追加のトークンを定義する
   */
})

`extendComponent`を使う

特定のコンポーネントのスタイルを継承して、新しいコンポーネントのスタイルを作成します。

import { extendComponent, ComponentStyle } from "@yamada-ui/react"

const Button: ComponentStyle = extendComponent("Button", {
  /**
   * 追加の`baseStyle`や`sizes`を定義する
   */
})

`extendComponentSize`を使う

特定のコンポーネントのサイズを継承して、新しいコンポーネントのサイズを作成します。

import { extendComponentSize, ComponentStyle } from "@yamada-ui/react"

const Tag: ComponentStyle = {
  baseStyle: {
    /**
     * 新しいスタイルを定義する
     */
  },
  sizes: extendComponentSize("Tag", {
    /**
     * 追加のサイズを定義する
     */
  }),
}

この関数は、baseStyleやvariantsは継承したくないが、sizesだけ継承したいケースに使えます。

`extendComponentVariant`を使う

特定のコンポーネントのバリアントを継承して、新しいコンポーネントのバリアントを作成します。

import { extendComponentVariant, ComponentStyle } from "@yamada-ui/react"

const Tag: ComponentStyle = {
  baseStyle: {
    /**
     * 新しいスタイルを定義する
     */
  },
  variants: extendComponentVariant("Tag", {
    /**
     * 追加のバリアントを定義する
     */
  }),
}

この関数は、baseStyleやsizesは継承したくないが、variantsだけ継承したいケースに使えます。

`extendComponentDefaultProps`を使う

特定のコンポーネントのpropsを継承して、新しいコンポーネントのpropsを作成します。

import { extendComponentDefaultProps, ComponentStyle } from "@yamada-ui/react"

const Tag: ComponentStyle = {
  baseStyle: {
    /**
     * 新しいスタイルを定義する
     */
  },
  defaultProps: extendComponentDefaultProps("Tag", {
    /**
     * 追加のpropsを定義する
     */
  }),
}

この関数は、baseStyleやsizesは継承したくないが、defaultPropsだけ継承したいケースに使えます。

`withDefaultSize`を使う

すべてまたは一部のコンポーネントのデフォルトのサイズを変更します。

./theme/index.ts

import { extendTheme, withDefaultSize } from "@yamada-ui/react"

/**
 * 省略
 */

export default extendTheme(
  customTheme,
  withDefaultSize({
    size: "lg",
    components: ["Badge", "Tag", "Button"], // もし、空の配列を渡した場合は、すべてのコンポーネントに設定されます。
  }),
)()

`withDefaultVariant`を使う

すべてまたは一部のコンポーネントのデフォルトのバリアントを変更します。

./theme/index.ts

import { extendTheme, withDefaultVariant } from "@yamada-ui/react"

/**
 * 省略
 */

export default extendTheme(
  customTheme,
  withDefaultVariant({
    variant: "solid",
    components: ["Badge", "Tag", "Button"], // もし、空の配列を渡した場合は、すべてのコンポーネントに設定されます。
  }),
)()

`withDefaultColorScheme`を使う

すべてまたは一部のコンポーネントのデフォルトのカラースキーマを変更します。

./theme/index.ts

import { extendTheme, withDefaultColorScheme } from "@yamada-ui/react"

/**
 * 省略
 */

export default extendTheme(
  customTheme,
  withDefaultColorScheme({
    colorScheme: "primary",
    components: ["Badge", "Tag", "Button"], // もし、空の配列を渡した場合は、すべてのコンポーネントに設定されます。
  }),
)()

`withDefaultProps`を使う

すべてまたは一部のコンポーネントのデフォルトのpropsを一括で変更します。

./theme/index.ts

import { extendTheme, withDefaultProps } from "@yamada-ui/react"

/**
 * 省略
 */

export default extendTheme(
  customTheme,
  withDefaultProps({
    defaultProps: {
      size: "lg",
      variant: "solid",
      colorScheme: "primary",
    },
    components: ["Badge", "Tag", "Button"], // もし、空の配列を渡した場合は、すべてのコンポーネントに設定されます。
  }),
)()

GitHubでこのページを編集する

前デフォルトのテーマ次コンポーネントのスタイル

テーマをカスタマイズする

テーマの適用

Create React Appの場合

Next.jsの場合

Viteの場合

トークンを変更する

セマンティックトークンを変更する

スタイルを変更する

コンポーネントのスタイルを変更する

ユーティリティ

extendThemeを使う

複数のテーマをマージする

デフォルトのテーマを継承しない

デフォルトテーマから特定のトークンを除外して継承する

デフォルトテーマから特定のトークンだけ継承する

extendBaseThemeを使う

extendStyleを使う

extendTokenを使う

extendComponentを使う

extendComponentSizeを使う

extendComponentVariantを使う

extendComponentDefaultPropsを使う

withDefaultSizeを使う

withDefaultVariantを使う

withDefaultColorSchemeを使う

withDefaultPropsを使う

`extendTheme`を使う

`extendBaseTheme`を使う

`extendStyle`を使う

`extendToken`を使う

`extendComponent`を使う

`extendComponentSize`を使う

`extendComponentVariant`を使う

`extendComponentDefaultProps`を使う

`withDefaultSize`を使う

`withDefaultVariant`を使う

`withDefaultColorScheme`を使う

`withDefaultProps`を使う