Loading

Yamada UI supports the loading animations needed in applications.

Usage

To display loading, use useLoading. useLoading returns instances of screen, page, background, and custom. These instances include several methods.

isLoading: Retrieves whether it is in the loading animation.
start: Starts the loading animation.
update: Updates the information of the loading animation.
finish: Ends the loading animation.

custom is not set in the Default Config. If you want to set up custom loading, please check here.

Editable example

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>
)

Customizing Loading

By passing options to the method, you can customize loading.

Adding a Timeout

In cases such as communication, it is necessary to add a timeout. In that case, use duration.

Editable example

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

return (
  <Wrap gap="md">
    <Button onClick={() => screen.start({ duration: 5000 })}>
      Start screen loading
    </Button>
    <Button onClick={() => page.start({ duration: 5000 })}>
      Start page loading
    </Button>
    <Button onClick={() => background.start({ duration: 5000 })}>
      Start background loading
    </Button>
  </Wrap>
)

Adding a Message

To add a message to the loading, use message.

Editable example

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

return (
  <Wrap gap="md">
    <Button
      onClick={() => screen.start({ message: "Loading", duration: 5000 })}
    >
      Start screen loading
    </Button>
    <Button onClick={() => page.start({ message: "Loading", duration: 5000 })}>
      Start page loading
    </Button>
    <Button
      onClick={() => background.start({ message: "Loading", duration: 5000 })}
    >
      Start background loading
    </Button>
  </Wrap>
)

You can pass a JSX element to message.

Editable example

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

return (
  <Wrap gap="md">
    <Button
      onClick={() =>
        screen.start({
          message: <Text color="primary">Loading</Text>,
          duration: 5000,
        })
      }
    >
      Start screen loading
    </Button>
    <Button
      onClick={() =>
        page.start({
          message: <Text color="primary">Loading</Text>,
          duration: 5000,
        })
      }
    >
      Start page loading
    </Button>
    <Button
      onClick={() =>
        background.start({
          message: <Text color="primary">Loading</Text>,
          duration: 5000,
        })
      }
    >
      Start background loading
    </Button>
  </Wrap>
)

Update the Message

To update the message, pass options to the update method.

Editable example

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

const onLoadingScreen = async () => {
  try {
    screen.start({ message: "Loading" })

    await wait(3000)

    screen.update({ message: "Please wait" })

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

const onLoadingPage = async () => {
  try {
    page.start({ message: "Loading" })

    await wait(3000)

    page.update({ message: "Please wait" })

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

const onLoadingBackground = async () => {
  try {
    background.start({ message: "Loading" })

    await wait(3000)

    background.update({ message: "Please wait" })

    await wait(3000)
  } 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>
)

Customize from Config

If you want to set the loading settings for the entire application, customize the config.

For example, if you want to change the loading icon for the entire application, pass an option to loading.

Editable example

const customConfig = extendConfig({
  loading: {
    screen: {
      icon: {
        variant: "grid",
      },
    },
    page: {
      icon: {
        variant: "grid",
      },
    },
    background: {
      icon: {
        variant: "grid",
      },
    },
  },
})

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

  return (
    <Wrap gap="md">
      <Button onClick={() => screen.start({ duration: 5000 })}>
        Start screen loading
      </Button>
      <Button onClick={() => page.start({ duration: 5000 })}>
        Start page loading
      </Button>
      <Button onClick={() => background.start({ duration: 5000 })}>
        Start background loading
      </Button>
    </Wrap>
  )
}

return (
  <UIProvider config={customConfig}>
    <App />
  </UIProvider>
)

Using `initialState`

By using initialState, a loading display will be shown when the application is loaded.

This is suitable for communication during loading (such as obtaining user information).

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

const customConfig = extendConfig({
  loading: {
    screen: {
      initialState: true,
    },
  },
})

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

If you set initialState to true, you need to call finish of the useLoading instance at the end of the function in the application (the function that is communicating). If you don't, the loading will not end.

Using Custom Components

Depending on the scenario, you may need to implement a loading animation that fits your project.

In that case, you can utilize custom.

Editable example

const customConfig = extendConfig({
  loading: {
    custom: {
      component: ({ initialState, message, duration, onFinish }) => {
        useTimeout(onFinish, duration)

        return (
          <Motion
            initial={!initialState ? "initial" : false}
            animate="animate"
            exit="exit"
            variants={{
              initial: {
                opacity: 0,
              },
              animate: {
                opacity: 1,
                transition: {
                  duration: 0.4,
                  ease: [0.4, 0, 0.2, 1],
                },
              },
              exit: {
                opacity: 0,
                transition: {
                  duration: 0.4,
                  ease: [0.4, 0, 1, 1],
                },
              },
            }}
            sx={{
              position: "fixed",
              top: 0,
              right: 0,
              bottom: 0,
              left: 0,
              zIndex: 9999,
              bg: "blackAlpha.600",
              w: "100vw",
              h: "100vh",
              p: "md",
              display: "flex",
              justifyContent: "center",
              alignItems: "center",
            }}
          >
            <Motion
              initial={!initialState ? "initial" : false}
              animate="animate"
              exit="exit"
              variants={{
                initial: {
                  opacity: 0,
                  scale: 0.95,
                },
                animate: {
                  opacity: 1,
                  scale: 1,
                  transition: {
                    duration: 0.4,
                    ease: [0.4, 0, 0.2, 1],
                  },
                },
                exit: {
                  opacity: 0,
                  scale: 0.95,
                  transition: {
                    duration: 0.4,
                    ease: [0.4, 0, 1, 1],
                  },
                },
              }}
              sx={{
                bg: ["white", "black"],
                maxW: "md",
                p: "md",
                display: "flex",
                flexDirection: "column",
                justifyContent: "center",
                alignItems: "center",
                gap: "sm",
                rounded: "md",
                boxShadow: ["lg", "dark-lg"],
              }}
            >
              <Loading variant="dots" size="6xl" />

              <VStack align="center" mb="md" gap="sm">
                <Text>Downloading files…</Text>
                {message ? (
                  isValidElement(message) ? (
                    message
                  ) : (
                    <Text lineClamp={3}>{message}</Text>
                  )
                ) : null}
              </VStack>

              <Button size="sm" onClick={onFinish}>
                Play to background
              </Button>
            </Motion>
          </Motion>
        )
      },
    },
  },
})

function App() {
  const { custom } = useLoading()

  return (
    <Button onClick={() => custom.start({ duration: 5000 })}>
      Start custom loading
    </Button>
  )
}

return (
  <UIProvider config={customConfig}>
    <App />
  </UIProvider>
)

If you want to learn more about the config, please check Customize Config.

Edit this page on GitHub

PreviousText and Layer Styles NextNotification

Loading

Customizing Loading

Adding a Timeout

Adding a Message

Update the Message

Customize from Config

Using initialState

Using Custom Components

Using `initialState`