Migration

New features and improvements from v1.x to v2.x.

New Features

Setup

Using CLI, you can easily set up Yamada UI in your project.

pnpm yamada-cli init

npm yamada-cli init

yarn yamada-cli init

bun yamada-cli init

init command will display the following prompts.

Would you like to use monorepo? (recommended) … No / Yes
What is the path to the monorepo? … ./workspaces/ui
What is the package name? … @workspaces/ui
Would you like your code inside a `src/` directory? … No / Yes
Would you like to use Prettier? … No / Yes
Would you like to use ESLint? … No / Yes

From v2.x onwards, there are two ways to use components and hooks. One is the new method of downloading components and hooks locally via the CLI, and the other is the conventional method of importing them from the module.

By downloading the source code, you can customize the initial value or logic of the component or hook, and if there is a bug in the logic, you can fix it directly.

pnpm yamada-cli add button

npm yamada-cli add button

yarn yamada-cli add button

bun yamada-cli add button

By downloading the source code and customizing it, you can easily update the source code by checking the Check Differences or Update Components in CLI. If your changes conflict with the updates, they will be displayed in the same way as the HOW CONFLICTS ARE PRESENTED of Git, and you can easily resolve them.

Namespace Import

You can now import components using namespaces.

<Accordion.Root>
  <Accordion.Item>
    <Accordion.Button />
    <Accordion.Panel />
  </Accordion.Item>
</Accordion.Root>

You can still import components individually, but there are components whose names have changed due to the namespace. For example, in the case of Accordion, it has been changed to AccordionRoot.

createComponent

Using createComponent, you can create components that support conditional styles such as variants.

const componentStyle = defineComponentStyle({
  base: {
    /* base style */
  },
  variants: {
    /* variant style */
  },
  sizes: {
    /* size style */
  },
  props: {
    /* props style */
  },
  compounds: {
    /* compound style */
  },
  defaultProps: {
    /* default props */
  },
})

type ComponentStyle = typeof componentStyle

export interface ComponentProps
  extends HTMLStyledProps<"div">,
    ThemeProps<ComponentStyle> {}

const {
  component,
  ComponentContext,
  PropsContext: ComponentPropsContext,
  useComponentContext,
  usePropsContext: useComponentPropsContext,
  withContext,
  useComponentProps,
} = createComponent<ComponentProps, ComponentStyle>("component", componentStyle)

export { ComponentPropsContext, useComponentPropsContext }

export const Component = withContext("div")()

mergeProps

Using mergeProps, you can easily merge props while preventing props from disappearing. Previously, you had to create components while considering the provided props. Using mergeProps, you can focus on creating components without considering the provided props.

Before

export const Component: FC<ComponentProps> = ({
  ref: forwardedRef,
  className,
  onClick: onClickProp,
  ...rest
}) => {
  const ref = useRef<HTMLDivElement>(null)

  const onClick = useCallback(() => {}, [])

  return (
    <Component
      ref={mergeRefs(forwardedRef, ref)}
      onClick={handlerAll(onClickProp, onClick)}
      className={[className, "component"].join(" ")}
      {...rest}
    />
  )
}

After

export const Component: FC<ComponentProps> = (props) => {
  const ref = useRef<HTMLDivElement>(null)

  const onClick = useCallback(() => {}, [])

  return <Component {...mergeProps(props, { ref, onClick })()} />
}

PropsContext

Using the PropsContext provided by each component, you can set the props of the components in the child elements in bulk.

const value = useMemo<BadgeProps>(() => ({ variant: "outline" }), [])

return (
  <BadgePropsContext value={value}>
    <Badge />
    <Badge />
    <Badge />
  </BadgePropsContext>
)

In the above example, the Badge in the child elements of BadgePropsContext will all have variant set to "outline".

Polymorphism

In addition to the traditional as, asChild has been added. as is used to change the element of the component itself, while asChild is used to incorporate the functionality and style of the component into the child elements.

<Box as="button" />

asChild

<Button asChild>
  <CustomComponent />
</Button>

Cascade Layers

Using the Cascade Layers of CSS, Theme and Style Props now have priority. Please refer to Cascade Layers for more details.

Focus Ring

Style Props has been added Focus Ring. Focus Ring is a style used to identify the focused element. Please refer to Focus Ring for more details.

<Box focusRing="outline" />

<Box focusVisibleRing="outline" />

Interpolation

Style Props now allows you to easily reference CSS Custom Properties using its values. Please refer to Interpolation for more details.

<Box {...{ "--custom-bg-color": "#1ba14c" }} bg="{custom-bg-color}" />

CSS Custom Properties

Style Props now allows you to easily set CSS Custom Properties. Please refer to CSS Custom Properties for more details.

<Box css={{ "--bg": "#d4d4d4" }} {...{ "--fg": "black" }} />

You can also reference the tokens of Theme.

<Box
  css={{ "--bg": "colors.bg.contrast" }}
  {...{ "--fg": "colors.fg.contrast" }}
/>

CSS Value Functions

Style Props now allows you to use CSS Value Functions and reference the corresponding Theme tokens. Please refer to CSS Value Functions for more details.

<Box w="calc(lg / 2)" />

<Box bg="color-mix(red.500, blue.500)" />

At-rules

Style Props has been added At-rules. Please refer to At-rules for more details.

<Box _media={[{ type: "print", css: { color: "success" } }]} />

Container Queries are also supported.

<Box containerType="inline-size" resize="horizontal">
  <Box
    _container={[{ minW: "320px", maxW: "560px", css: { color: "success" } }]}
  />
</Box>

Internationalization

To improve accessibility, we have supported 30 or more languages, including strings embedded in all components, date and number formats. Please refer to Internationalization for more details.

Icons

New icons have been added. Please refer to Icons for more details.

Style Props

New CSS properties have been added. Please refer to Style Props for more details.

Theme

New keyframes, aspectRatios, easings, and durations have been added to the theme tokens.
"mono" has been added to the Color Schemes.
New tokens have been added to the Layer Styles.
New tokens have been added to the Text Styles.
New tokens have been added to the Colors.
You can now set className in the style object of the components.

Improvements

styled

ui has been renamed to styled. Also, since only the base style of the component could be set until now, it is now possible to set styles that vary depending on conditions, such as variants and sizes.

Before

const Button = styled("button", {
  base: {
    alignItems: "center",
    appearance: "none",
    cursor: "pointer",
    display: "inline-flex",
    fontWeight: "medium",
    justifyContent: "center",
    overflow: "hidden",
    position: "relative",
    rounded: "l2",
    transitionDuration: "moderate",
    transitionProperty: "common",
    userSelect: "none",
    verticalAlign: "middle",
    whiteSpace: "nowrap",
    _readOnly: { layerStyle: "readOnly" },
    _disabled: { layerStyle: "disabled" },
  },
})

After

const Button = styled("button", {
  base: {
    alignItems: "center",
    appearance: "none",
    cursor: "pointer",
    display: "inline-flex",
    fontWeight: "medium",
    justifyContent: "center",
    overflow: "hidden",
    position: "relative",
    rounded: "l2",
    transitionDuration: "moderate",
    transitionProperty: "common",
    userSelect: "none",
    verticalAlign: "middle",
    whiteSpace: "nowrap",
    _readOnly: { layerStyle: "readOnly" },
    _disabled: { layerStyle: "disabled" },
  },
  variants: {
    outline: {
      layerStyle: "outline",
      _hover: { layerStyle: "outline.hover" },
    },
    solid: {
      layerStyle: "solid",
      _hover: { layerStyle: "solid.hover" },
    },
    subtle: {
      layerStyle: "subtle",
      _hover: { layerStyle: "subtle.hover" },
    },
  },
})

Conditional Styles

Conditional style setting has been simplified. The traditional setting can still be used.

Before

<Box bg="bg.contrast" _hover={{ bg: "success" }} />

After

<Box bg={{ base: "bg.contrast", _hover: "success" }} />

Color Scheme

Previously, the Color Scheme was set as props for each component. By integrating colorScheme into Style Props, it is now available for components other than components.

<Box colorScheme="blue" bg="colorScheme.solid" color="colorScheme.contrast" />

Also, since colorScheme uses CSS Custom Properties to generate a context, it is now also applied to the child elements.

<Box colorScheme="blue">
  <Box bg="colorScheme.solid" color="colorScheme.contrast" />
  <Box colorScheme="green" bg="colorScheme.subtle" color="colorScheme.fg" />
</Box>

Animation

Previously, the Animation used the useAnimation hook. Now, you can set it directly from Style Props.

Before

const animation = useAnimation({
  _keyframes: {
    from: { translate: "0 0" },
    to: { translate: "100% 0" },
  },
  duration: "1s",
  iterationCount: "infinite",
  timingFunction: "linear",
})

return <Box animation={animation} />

After

<Box
  animationDirection="alternate"
  animationDuration="1s"
  animationIterationCount="infinite"
  animationTimingFunction="linear"
  _keyframes={{
    from: { translate: "0 0" },
    to: { translate: "100% 0" },
  }}
/>

Components

The styles of each component have been adjusted.
The slot names of each component have been adjusted.
The class names of each component have been adjusted.
The naming convention of all boolean properties (isOpen, isDisabled, etc.) in the props of each component has been changed. For example, isOpen has been changed to open.

The improvement points of each component are described in the documentation of each component.

Style Props

color-mix has been supported. If the browser does not support color-mix, the fallback value will be applied.
blur and brightness can now be applied without setting filter="auto".
backdropBlur and backdropBrightness can now be applied without setting backdropFilter="auto".
translateX and skewX can now be applied without setting transform="auto" or transform="auto-3d".

Theme

CSS Value Functions can now be used for tokens.
Interpolation can now be used for tokens.
Theme can now be defined using defineTheme.
Tokens can now be defined using defineTokens.
Semantic tokens can now be defined using defineSemanticTokens.
Styles can now be defined using defineStyles.
Config can now be defined using defineConfig.
The slot names of the components have been adjusted and changed.
The global styles have been adjusted.
The reset styles have been adjusted.
The values of the tokens have been adjusted.

Removed Features

Packages

Tree Shaking considerations have made it unnecessary to divide each package, and since there is a possibility that other choices than React will become available in future Yamada UI projects, these packages have been deprecated.

@yamada-ui/input has been deprecated. Use @yamada-ui/react instead.
@yamada-ui/use-disclosure has been deprecated. Use @yamada-ui/react instead.
@yamada-ui/providers has been deprecated. Use @yamada-ui/react instead.
@yamada-ui/theme has been deprecated. Use @yamada-ui/react instead.
@yamada-ui/theme-tools has been deprecated. Use @yamada-ui/react instead.
@yamada-ui/next has been deprecated.

Style Props

fallback has been removed.
keyframes has been removed. Use _keyframes instead.
isTruncated has been removed. Use truncated instead.

Theme

transitions has been removed. Use easings and durations instead.
semantics has been removed. Use semanticTokens instead.
components has been removed. Use CLI to style components.
extendBaseTheme has been removed. Use extendTheme instead.
extendStyle has been removed. Use extendTheme instead.
extendToken has been removed. Use extendTheme instead.
extendComponent has been removed.
extendComponentSize has been removed.
extendComponentVariant has been removed.
extendComponentDefaultProps has been removed.
withDefaultSize has been removed.
withDefaultVariant has been removed.
withDefaultColorScheme has been removed.
withDefaultProps has been removed.
generate has been removed.

Other

forwardRef has been removed. Use forwardRef instead.
memo has been removed. Use memo instead.
ui has been removed. Use styled instead.
sx and __css have been removed. Use css instead.