Cloud UI Getting Started

Cloud UI Components

Cloud UI has 4 layers of components: Cloud UI Primitive, Cloud UI Business, Cloud UI Pro(WIP) and Cloud UI Icons.

Cloud UI Primitive

The fundamental UI library for TiDB Cloud, including layout, typography, color, and so on. Encapsulate the basic UI elements and styles based on Mantine. We’ll customize the styles and components to meet the requirements of TiDB Cloud.

Cloud UI Business

Abstracted business UI components for TiDB Cloud, including Form, Search Area, PhoneInput, TablePro, etc. These components are based on Cloud UI Primitive and encapsulate the business logic and interaction experience of TiDB Cloud.

Cloud UI Pro(WIP)

Cloud UI Pro is a sample pages centering on the business scenarios of TiDB Cloud. It includes a series of business components and pages, such as the Database Console, Database Management, and Database Monitoring. These components are based on Cloud UI Business and encapsulate the business logic and interaction experience of TiDB Cloud. This part is still under development.

Cloud UI Icons

Cloud UI Icons are designed originally by TiDB Cloud design team which includes a set of icons for TiDB Cloud. The icons are SVG format and can be used in any project.

Installation

Inside your React project directory, run the following command to install the package:

npm install @tidbcloud/uikit@latest

pnpm add @tidbcloud/uikit@latest

yarn add @tidbcloud/uikit@latest

bun add @tidbcloud/uikit@latest

Quick Start

Wrap your application root component with ThemeProvider and import the styles:

import { ThemeProvider } from '@tidbcloud/uikit/theme'
import '@tidbcloud/uikit/style.css'
 
function Main() {
  return (
    <ThemeProvider colorScheme="auto">
      <App />
    </ThemeProvider>
  )
}

You can now import and use any components anywhere in your application:

import { Button } from '@tidbcloud/uikit'
 
function Demo() {
  return <Button>Click me!</Button>
}

Color Scheme

If you want to customize the color scheme, you can declare a colorScheme state and pass it to ThemeProvider:

import { ThemeProvider } from '@tidbcloud/uikit/theme'
 
function useColorScheme() {
  const [colorScheme, setColorScheme] = useState<'light' | 'dark' | 'auto'>('auto')
  return { colorScheme, setColorScheme }
}
 
function Main() {
  const { colorScheme, setColorScheme } = useColorScheme()
 
  return (
    <ThemeProvider colorScheme={colorScheme}>
      <App />
    </ThemeProvider>
  )
}

For convenience, we provide a useColorScheme hook to help you manage the color scheme and it will also persist the state in the local storage.

import { useColorScheme } from '@tidbcloud/uikit'
 
const { colorScheme, setColorScheme } = useColorScheme()

Since the color scheme can be set to auto, you can use the useComputedColorScheme hook to get the final color scheme:

import { useComputedColorScheme } from '@tidbcloud/uikit'
 
const computedColorScheme = useComputedColorScheme()

Usage with Next.js Pages router

Assuming you are using the src directory structure, create a emotion cache with createEmotionCache function in your src/lib/emotion.ts:

import { createEmotionCache } from '@tidbcloud/uikit/emotion'
 
export const emotionCache = createEmotionCache({ key: 'css' })

Then pass the emotion cache to ThemeProvider and wrap your application root component in _app.tsx:

import '@/styles/globals.css'
import '@tidbcloud/uikit/style.css'
import type { AppProps } from 'next/app'
import { ThemeProvider } from '@tidbcloud/uikit/theme'
import { emotionCache } from '@/lib/emotion'
 
export default function App({ Component, pageProps }: AppProps) {
  return (
    <ThemeProvider emotionCache={emotionCache} colorScheme="auto">
      <Component {...pageProps} />
    </ThemeProvider>
  )
}

Create a emotion server with createEmotionServer function in _document.tsx:

import NextDocument, { Html, Head, Main, NextScript } from 'next/document'
import { ColorSchemeScript } from '@tidbcloud/uikit'
import { createGetInitialProps } from '@tidbcloud/uikit/emotion'
import { createEmotionServer } from '@tidbcloud/uikit/emotion/server'
import { emotionCache } from '@/lib/emotion'
 
export default function Document() {
  return (
    <Html lang="en">
      <Head>
        <ColorSchemeScript defaultColorScheme="auto" />
      </Head>
      <body className="antialiased">
        <Main />
        <NextScript />
      </body>
    </Html>
  )
}
 
const stylesServer = createEmotionServer(emotionCache)
Document.getInitialProps = createGetInitialProps(NextDocument, stylesServer)

Done! You can now use any components in your pages and using sx, styles props to customize the styles.

Introduction Accordion