This guide will help you understand the concepts of Yamada UI. We recommend reading this guide before you start developing with Yamada UI.

About Themes

Yamada UI, like other UI libraries, has a concept of themes.

A theme is a modifiable object where tokens of many properties such as component styles, colors, spaces, font sizes, and others are defined.

To set a Default Theme for your project, you need to add UIProvider to the root of your application.

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

const App = () => {
  return (
    <UIProvider>
      <YourApplication />
    </UIProvider>
  )
}

Customize the Theme

If you want to customize the theme, pass theme to UIProvider.

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

const customTheme = extendTheme({
  spaces: {
    xs: "1rem",
    sm: "1.25rem",
    md: "1.5rem",
    normal: "2rem",
    lg: "2.5rem",
    xl: "3rem",
  },
})()

const App = () => {
  return (
    <UIProvider theme={customTheme}>
      <YourApplication />
    </UIProvider>
  )
}

This has changed the margins throughout the application.

Changing Semantic Tokens

Yamada UI supports semantic tokens of all scales (such as color and font size).

The values that are actually set are as follows.

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",
  },
}

Depending on the project, you may want to change the semantic tokens.

For example, suppose you want to change primary to pink. In that case, you change semantics.

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

const customTheme = extendTheme({
  semantics: {
    colors: {
      primary: "pink.500",
    },
    colorSchemes: {
      primary: "pink",
    },
  },
})()

const App = () => {
  return (
    <UIProvider theme={customTheme}>
      <YourApplication />
    </UIProvider>
  )
}

Using Loading

Yamada UI supports loading animation necessary for applications.

To display loading, use useLoading. useLoading returns instances of screen, page, background, and custom. The instance includes several methods.

• isLoading: Determines whether the loading animation is in progress.
• start: Starts the loading animation.
• update: Updates the information of the loading animation.
• finish: Ends the loading animation.

const { screen, page, background } = useLoading()

const onLoadingScreen = async () => {
  try {
    screen.start()

    await wait(5000)
  } finally {
    screen.finish()
  }
}

const onLoadingPage = async () => {
  try {
    page.start()

    await wait(5000)
  } finally {
    page.finish()
  }
}

const onLoadingBackground = async () => {
  try {
    background.start()

    await wait(5000)
  } finally {
    background.finish()
  }
}

return (
  <Wrap gap="md">
    <Button onClick={onLoadingScreen}>Start screen loading</Button>
    <Button onClick={onLoadingPage}>Start page loading</Button>
    <Button onClick={onLoadingBackground}>Start background loading</Button>
  </Wrap>
)

Using Notifications

Yamada UI supports notifications needed in the application.

To display notifications, use useNotice. useNotice returns an instance to display and control notifications.

const notice = useNotice()

return (
  <Button
    onClick={() =>
      notice({
        title: "Notification",
        description: "This is description.",
      })
    }
  >
    Show notification
  </Button>
)

About Styles

With Yamada UI, you can easily change styles just by passing props to the components. It also provides many useful shorthands, improving development efficiency.

For example, you can write p for padding, and if you want to set both margin-left and margin-right, you can write mx.

<Box w="full" p="md" bg="warning" color="white">
  This is Box
</Box>

Pseudo Elements

<Box
  position="relative"
  boxSize="2xs"
  bg="primary"
  p="md"
  color="white"
  _after={{
    content: "'after'",
    position: "absolute",
    top: "0",
    right: "0",
    bg: "secondary",
    p: "md",
    color: "white",
  }}
>
  Box
</Box>

Components

Many of the components provided by Yamada UI can have their styles changed by setting variant, size, and colorScheme.

<Wrap gap="md">
  <Button>Basic</Button>

  <Button variant="solid" colorScheme="green">
    Solid
  </Button>

  <Button variant="outline" colorScheme="orange">
    Outline
  </Button>

  <Button variant="ghost" colorScheme="red">
    Ghost
  </Button>

  <Button variant="link" colorScheme="sky">
    Link
  </Button>

  <Button variant="unstyled">Unstyle</Button>
</Wrap>

<Wrap gap="md">
  <Button colorScheme="primary" size="xs">
    X Small
  </Button>

  <Button colorScheme="secondary" size="sm">
    Small
  </Button>

  <Button colorScheme="warning" size="md">
    Medium
  </Button>

  <Button colorScheme="danger" size="lg">
    Large
  </Button>
</Wrap>

About Responsiveness

Yamada UI supports responsive styles that are ready to use. By simply passing an object to the style's props, it will support PC-first responsive styles.

All style props also accept objects. Let's start by changing the background color.

• The keys of the object define the keys set in the theme's breakpoints.
• The values of the object define the values of the styles set by the key.

<Box
  w="full"
  p="md"
  bg={{ base: "primary", "2xl": "secondary", xl: "warning", lg: "danger" }}
  color="white"
>
  This is Box
</Box>

Please change the screen width and check it out.

The above code generates the following CSS.

.Box {
  background: var(--ui-colors-primary);

  @media screen and (max-width: 1440px) {
    background: var(--ui-colors-secondary);
  }

  @media screen and (max-width: 1280px) {
    background: var(--ui-colors-warning);
  }

  @media screen and (max-width: 976px) {
    background: var(--ui-colors-warning);
  }

  @media screen and (max-width: 480px) {
    background: var(--ui-colors-danger);
  }
}

About Breakpoints

Responsive styles refer to the breakpoints defined in the theme. Yamada UI has a Default Theme where breakpoints are defined.

Here are the actual defined values.

export const breakpoints = {
  sm: "30em", // 480px
  md: "48em", // 768px
  lg: "61em", // 976px
  xl: "80em", // 1280px
  "2xl": "90em", // 1440px
}

About Color Mode

Yamada UI incorporates support for managing the color mode of the application.

All components of Yamada UI support dark mode. Also, if you want to set the style of the color mode individually, it will correspond to the color mode just by passing an array to the props of the style.

All props of the style also accept arrays. First, let's change the background color.

• Define the value of the style you want to set in light mode as the first argument.
• Define the value of the style you want to set in dark mode as the second argument.

<Box w="full" p="md" bg={["primary", "secondary"]} color="white">
  This is Box
</Box>

Please change the color mode with the button below and check it out.

Switching Color Modes

The color mode is set in the Default Config.

Here are the actual defined values.

export const config: ThemeConfig = {
  initialColorMode: "light",
}

• initialColorMode: The initial value of the color mode. It accepts three values.

  • light: Light mode.
  • dark: Dark mode.
  • system: Retrieves the color mode from the Operating System (OS).

If you want to change the color mode within the application, use changeColorMode or toggleColorMode.

• changeColorMode: Sets any color mode.
• toggleColorMode: Switches to dark mode if it's light mode, and to light mode if it's dark mode.

const { colorMode, changeColorMode, toggleColorMode } = useColorMode()

return (
  <Wrap gap="md">
    <Button onClick={() => changeColorMode("light")}>Light Mode</Button>
    <Button onClick={() => changeColorMode("dark")}>Dark Mode</Button>
    <Button onClick={() => changeColorMode("system")}>System</Button>
    <Button onClick={toggleColorMode}>
      Switch to {colorMode === "light" ? "Dark" : "Light"} Mode
    </Button>
  </Wrap>
)

About Animation

Yamada UI provides many utilities, such as Motion, a component specialized for animation, and useAnimation, which can be described like CSS's keyframes.

Usage of useAnimation

useAnimation sets arguments such as keyframes, and passes the generated animation to props.

• keyframes: Set the style of keyframes (or intermediate points) along the flow of the animation. The values of each style can use tokens from the Yamada UI style system and theme.
• duration: Set the length of time required for one animation cycle.
• timingFunction: Set how the animation progresses. This defines the acceleration curve, setting how the animation progresses between keyframes.
• delay: Set the delay time from when the element is loaded until the animation begins.
• iterationCount: Set the number of times the animation repeats. To repeat the animation indefinitely, specify infinite.
• direction: Set whether to animate in the reverse direction and repeat when the animation sequence is completed, or to reset to the initial state and repeat the animation.
• fillMode: Set whether to apply the specified style before and after the execution of the animation.
• playState: Set whether to pause or resume the animation.

const animation = useAnimation({
  keyframes: {
    from: {
      transform: "rotate(0)",
    },
    to: {
      transform: "rotate(359deg)",
    },
  },
  duration: "0.8s",
  iterationCount: "infinite",
  timingFunction: "linear",
})

return (
  <Center p="lg">
    <Center
      w="150px"
      h="150px"
      p="1"
      rounded="50%"
      bgGradient={[
        "linear(blackAlpha.50, blackAlpha.500)",
        "linear(whiteAlpha.50, whiteAlpha.500)",
      ]}
      animation={animation}
    >
      <Box w="full" h="full" rounded="50%" bg={["white", "black"]} />
    </Center>
  </Center>
)

Using Motion

There are many props for the Motion component. This time, we will briefly introduce whileHover, whileTap, and whileFocus.

• whileHover: This is an animation that fires when the element is hovered over.
• whileTap: This is an animation that fires when the element is clicked or tapped.
• whileFocus: This is an animation that fires when the element is focused.

In this case, we are setting scale: 1.1 and scale: 0.9 to enlarge and reduce the size.

<Center p="lg">
  <Motion
    as="button"
    whileHover={{ scale: 1.1 }}
    whileTap={{ scale: 0.9 }}
    whileFocus={{ scale: 1.1 }}
    p="md"
    rounded="md"
    bg="primary"
    color="white"
  >
    Click me!
  </Motion>
</Center>

Congratulations!

Congratulations🎉

Now, you have become a Regular Yamada🥳

To you who have become a Regular Yamada, Yamada gives you these words.

"I'll be waiting in Learn the Advanced next///"😘

Learn More

Want to learn more about Yamada UI, including its applications and themes? 😎