import Docs from 'src/templates/Docs'
import { Spacer } from 'core'

export const meta = {
  title: 'About Bolio UI',
  description:
    'Bolio UI is a dedicated library designed to enhance both user and developer experiences.',
  sidebar: 'guide',
  group: 'Guide'
}

## About Bolio UI

<Spacer h={2} />

### Components library

Bolio UI is a dedicated library designed to enhance both user and developer experiences.
The development of Bolio UI commenced in july 2022, and its 1.0 version was officially launched on september, 2022,
and since then, more releases have been published.

<Spacer h={2} />

### Browser support

Bolio UI is tested on actual devices across various browsers, including: Chrome, Safari, Firefox, Edge, Safari for iOS, Chrome for Android.
Testing in other browsers is not performed.

All components and hooks were tested to work in the following browsers:

- • Chromium browsers 108+ – Chrome, Edge, Chrome for Android, etc.
- • Firefox 101+
- • Safari 15.4+
- • IE (any version) is not supported

<Spacer h={2} />

### Releases cycle

All `@bolio-ui/*` packages follow semver:

- • Patches (1.0.X) are typically released at intervals of one to two weeks.
- • Minor versions (1.X.0) are generally released on the first Monday of each month or bi-monthly.
- • Major versions (X.0.0) are deployed when there are significant changes that necessitate breaking compatibility.
  Usually, a new major version is released approximately every 6 months to 1 year.

<Spacer h={2} />

### Project maintenance

Bolio UI is make and overseen by <a href="https://github.com/brunnoandrade" rel="noreferrer" target="_blank">Bruno Andrade</a>.
The inclusion of new features and components/hooks in the library is largely influenced by community feedback.
You're welcome to engage in discussions about upcoming features on <a href="https://github.com/bolio-ui/bolio-ui/discussions" rel="noreferrer" target="_blank">Github</a>.

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { PackageTabs } from 'src/components'
import { Spacer } from 'core'

export const meta = {
  title: 'Agent Skills',
  description:
    'Teach AI assistants to build interfaces with Bolio UI components, setup and theming using the Bolio UI Skill.',
  sidebar: 'guide',
  group: 'Guide'
}

## Agent Skills

<Spacer h={2} />

### Installation

The Bolio UI Skill gives your AI assistant the setup, rules and docs links it needs to build with `@bolio-ui/core`. Install it with the skills package:

<PackageTabs
  pnpm="pnpm dlx skills add bolio-ui/bolio-ui"
  npm="npx skills add bolio-ui/bolio-ui"
  yarn="yarn dlx skills add bolio-ui/bolio-ui"
  bun="bunx skills add bolio-ui/bolio-ui"
/>

The Skill goes to `.agents/skills/bolio-ui` in your project, which Cursor, Codex, GitHub Copilot and other tools read, and is linked for Claude Code. Run the command at the root of your project.

<Spacer h={2} />

### Manual install

Copy the [skills/bolio-ui](https://github.com/bolio-ui/bolio-ui/tree/master/skills/bolio-ui) folder to the skills directory of your tool. Use your project to load the Skill only where Bolio UI is used, or your home directory to load it in every project:

- • `.agents/skills/` for Cursor, Codex, GitHub Copilot and Antigravity
- • `.claude/skills/` for Claude Code
- • `.opencode/skills/` for OpenCode

<Spacer h={2} />

### Usage

Your assistant discovers the Skill by itself when you work with `@bolio-ui/core`, or you can call it by name with `/bolio-ui`.

Ask your assistant to:

- • Build components using Bolio UI
- • Create pages with Bolio UI components
- • Customize themes and colors
- • Read the documentation of a component

<Spacer h={2} />

### What's included

- • Installation with the CLI or by hand, for every supported framework
- • Rules for building with the components, such as theme colors instead of hex values
- • Links to the [LLMs.txt](/docs/guide/llms-txt) files, so props and examples come from the docs and not from memory
- • The path to the [migration guide](/docs/guide/migration-v2-to-v3) for projects coming from v2

<Spacer h={2} />

### Structure

```text
skills/bolio-ui/
└── SKILL.md    # Main skill documentation
```

<Spacer h={2} />

### Related documentation

- • [Agent Skills specification](https://agentskills.io): the format of a Skill
- • [Claude Agent Skills](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview): Skills in Claude
- • [Cursor Skills](https://cursor.com/docs/context/skills): Skills in Cursor
- • [OpenCode Skills](https://opencode.ai/docs/skills): Skills in OpenCode

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { PackageTabs } from 'src/components'
import { Spacer } from 'core'

export const meta = {
  title: 'AGENTS.md',
  description:
    'Add the Bolio UI docs to the AGENTS.md of your project, so AI coding agents read them before writing UI code.',
  sidebar: 'guide',
  group: 'Guide'
}

## AGENTS.md

<Spacer h={2} />

### Usage

Run the command at the root of your project. It adds a Bolio UI section to `AGENTS.md`, and creates the file when it does not exist:

<PackageTabs
  pnpm="pnpm dlx @bolio-ui/cli@latest agents-md"
  npm="npx @bolio-ui/cli@latest agents-md"
  yarn="yarn dlx @bolio-ui/cli@latest agents-md"
  bun="bunx --bun @bolio-ui/cli@latest agents-md"
/>

Or give the file to write, for example `CLAUDE.md`:

<PackageTabs
  pnpm="pnpm dlx @bolio-ui/cli@latest agents-md CLAUDE.md"
  npm="npx @bolio-ui/cli@latest agents-md CLAUDE.md"
  yarn="yarn dlx @bolio-ui/cli@latest agents-md CLAUDE.md"
  bun="bunx --bun @bolio-ui/cli@latest agents-md CLAUDE.md"
/>

<Spacer h={2} />

### What it does

- • Adds a Bolio UI section between `<!-- bolio-ui -->` markers, keeping the rest of the file as it is
- • Links the [LLMs.txt](/docs/guide/llms-txt) files, so the agent reads the real props and examples of each component
- • Updates the section when you run it again, without repeating it

Nothing is downloaded to your project. The agent reads the docs from [bolio-ui.com](https://bolio-ui.com) when it needs them.

<Spacer h={2} />

### Options

| Argument | What it does                                              |
| -------- | --------------------------------------------------------- |
| `[file]` | file to write, relative to the current folder (AGENTS.md) |

<Spacer h={2} />

### Related documentation

- • [AGENTS.md](https://agents.md): the format of instructions for coding agents
- • [CLAUDE.md](https://docs.claude.com/en/docs/claude-code/memory): the Claude equivalent of AGENTS.md
- • [Agent Skills](/docs/guide/agent-skills): the Bolio UI Skill, for tools that load Skills

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { PackageTabs } from 'src/components'
import { Link, Spacer } from 'core'

export const meta = {
  title: 'Example with Astro',
  description: 'Set up Bolio UI in an Astro application.',
  sidebar: 'guide',
  group: 'Guide'
}

## Example with Astro

<Spacer h={2} />

### Get started with an example

To begin, the most straightforward approach is to utilize one of the provided templates.
These templates come pre-configured with the necessary settings, such as CssBaseline and other fundamental components.

If you're new to GitHub and need guidance on initiating a project using a template,
you can access comprehensive instructions on how to get started on <Link target="_blank" rel="nofollow" color icon href="https://github.com/bolio-ui/bolio-ui/tree/master/examples/create-astro">this example</Link>.

<Spacer h={2} />

### Generate new application

Follow <Link target="_blank" rel="nofollow" color icon href="https://docs.astro.build/en/install-and-setup/">Astro installation</Link> guide to create new application:

<PackageTabs pnpm="pnpm create astro@latest" npm="npm create astro@latest" yarn="yarn create astro" bun="bun create astro@latest" />

Then add the React integration:

<PackageTabs pnpm="pnpm astro add react" npm="npx astro add react" yarn="yarn astro add react" bun="bunx astro add react" />

<Spacer h={2} />

### Installation

Install dependencies:

<PackageTabs pnpm="pnpm add @bolio-ui/core" npm="npm i @bolio-ui/core" yarn="yarn add @bolio-ui/core" bun="bun add @bolio-ui/core" />

<Spacer h={2} />

### Setup

Astro renders React only in islands, so there is no single root to wrap. Create a component with the `BolioUIProvider`, `CssBaseline` and styles import in `src/components/BolioUI.tsx`:

```jsx
import type { ReactNode } from 'react'
import { BolioUIProvider, CssBaseline } from '@bolio-ui/core'
import '@bolio-ui/core/styles.css'

export default function BolioUI({ children }: { children: ReactNode }) {
  return (
    <BolioUIProvider>
      <CssBaseline />
      {children}
    </BolioUIProvider>
  )
}
```

Then wrap the content of each island with it in an `.astro` file:

```jsx
---
import BolioUI from '../components/BolioUI'
import Counter from '../components/Counter'
---

<BolioUI client:load>
  <Counter />
</BolioUI>
```

Ready to go! Start the development server:

<PackageTabs pnpm="pnpm dev" npm="npm run dev" yarn="yarn dev" bun="bun run dev" />

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { PackageTabs } from 'src/components'
import { Link, Spacer } from 'core'

export const meta = {
  title: 'Example with Gatsby',
  description: 'Set up Bolio UI in a Gatsby application.',
  sidebar: 'guide',
  group: 'Guide'
}

## Example with Gatsby

<Spacer h={2} />

### Get started with an example

To begin, the most straightforward approach is to utilize one of the provided templates.
These templates come pre-configured with the necessary settings, such as CssBaseline and other fundamental components.

If you're new to GitHub and need guidance on initiating a project using a template,
you can access comprehensive instructions on how to get started on <Link target="_blank" rel="nofollow" color icon href="https://github.com/bolio-ui/bolio-ui/tree/master/examples/create-gatsby">this example</Link>.

<Spacer h={2} />

### Generate new application

Follow <Link target="_blank" rel="nofollow" color icon href="https://www.gatsbyjs.com/docs/quick-start/"> Gatsby quick start</Link> guide to create new Gatsby application:

<PackageTabs pnpm="pnpm create gatsby" npm="npm init gatsby" yarn="yarn create gatsby" bun="bun create gatsby" />

<Spacer h={2} />

### Installation

Install dependencies:

<PackageTabs pnpm="pnpm add @bolio-ui/core" npm="npm i @bolio-ui/core" yarn="yarn add @bolio-ui/core" bun="bun add @bolio-ui/core" />

<Spacer h={2} />

### Setup

Gatsby has no root component, so wrap the app with `wrapRootElement` to set up the `BolioUIProvider` and the `CssBaseline` on every page.

Create `gatsby-browser.tsx` (or `.js`):

```jsx
import * as React from 'react'
import { BolioUIProvider, CssBaseline } from '@bolio-ui/core'
import '@bolio-ui/core/styles.css'

export const wrapRootElement = ({ element }) => (
  <BolioUIProvider>
    <CssBaseline />
    {element}
  </BolioUIProvider>
)
```

Then create `gatsby-ssr.tsx` (or `.js`) to render the same wrapper on the server:

```jsx
export { wrapRootElement } from './gatsby-browser'
```

Ready to go! Start the development server:

<PackageTabs pnpm="pnpm develop" npm="npm run develop" yarn="yarn develop" bun="bun run develop" />

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Link, Spacer } from 'core'

export const meta = {
  title: 'Example with Next.js',
  description:
    'Bolio UI is totally compatible with Next.js you just need to customize the _app.jsx entry file to load the provider.',
  sidebar: 'guide',
  group: 'Guide'
}

## Example with Next.js

<Spacer h={2} />

### Get started with an example

To begin, the most straightforward approach is to utilize one of the provided templates.
These templates come pre-configured with the necessary settings, such as CssBaseline and other fundamental components.

If you're new to GitHub and need guidance on initiating a project using a template,
you can access comprehensive instructions on how to get started on <Link target="_blank" rel="nofollow" color icon href="https://github.com/bolio-ui/bolio-ui/tree/master/examples/create-nextjs-ts-app">this example</Link>.

<Spacer h={2} />

### Server Render

All Components of `@bolio-ui/core` are compatible with **Server Render**. In fact, the page you see now is rendered by the server.

Server-side rendering (SSR) is the process of rendering web pages on a server and passing them to the browser (client-side),
instead of rendering them in the browser. SSR sends a fully rendered page to the client; the client's JavaScript
bundle takes over and enables the SPA framework to operate, the best option to use server side render in React.js is using <Link target="_blank" rel="nofollow" color icon href="https://nextjs.org">Next.js</Link>.

If you are worried about losing the advantages of a Single Page Application by implementing server-side rendering, you can use the `hybrid render` application.
Please read <Link target="_blank" rel="nofollow" color icon href="https://nextjs.org/blog/next-9-3#next-gen-static-site-generation-ssg-support">
the post from the Next.js team</Link> to learn more.

<Spacer h={2} />

### Next.js

Bolio UI works with the Pages Router and with the App Router.

#### Pages Router

Next.js already adds the styles to the HTML, so you don't need a custom `_document`. Import the stylesheet once and set up the `BolioUIProvider` and `CssBaseline` in `pages/_app.js`:

```jsx
import '@bolio-ui/core/styles.css'
import { BolioUIProvider, CssBaseline } from '@bolio-ui/core'

function MyApp({ Component, pageProps }) {
  return (
    <BolioUIProvider>
      <CssBaseline />
      <Component {...pageProps} />
    </BolioUIProvider>
  )
}

export default MyApp
```

<Spacer h={2} />

#### App Router

Import the stylesheet once in `app/layout.js`:

```jsx
import '@bolio-ui/core/styles.css'
import { BolioUIProvider, CssBaseline } from '@bolio-ui/core'

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <BolioUIProvider>
          <CssBaseline />
          {children}
        </BolioUIProvider>
      </body>
    </html>
  )
}
```

The components are Client Components, so you can use them in Server Components without adding `'use client'`.

<Spacer h={2} />

### Custom Server

The stylesheet is a plain CSS file, not injected at render time, so a custom server needs nothing beyond serving `@bolio-ui/core/styles.css` (or letting your bundler include it) and rendering the app normally:

```jsx
import React from 'react'
import ReactDOM from 'react-dom/server'
import App from './app'

export default (req, res) => {
  const app = ReactDOM.renderToString(<App />)
  const html = ReactDOM.renderToStaticMarkup(
    <html>
      <body>
        <div id="root" dangerouslySetInnerHTML={{ __html: app }} />
      </body>
    </html>
  )
  res.end('<!doctype html>' + html)
}
```

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { PackageTabs } from 'src/components'
import { Link, Spacer, Snippet } from 'core'

export const meta = {
  title: 'Example with RedwoodJS',
  description: 'Set up Bolio UI in a RedwoodJS application.',
  sidebar: 'guide',
  group: 'Guide'
}

## Example with RedwoodJS

<Spacer h={2} />

### Get started with an example

To begin, the most straightforward approach is to utilize one of the provided templates.
These templates come pre-configured with the necessary settings, such as CssBaseline and other fundamental components.

If you're new to GitHub and need guidance on initiating a project using a template,
you can access comprehensive instructions on how to get started on <Link target="_blank" rel="nofollow" color icon href="https://github.com/bolio-ui/bolio-ui/tree/master/examples/create-redwoodjs">this example</Link>.

<Spacer h={2} />

### Generate new application

Follow <Link target="_blank" rel="nofollow" color icon href="https://redwoodjs.com/docs/quick-start"> Redwood getting started</Link> guide to create new Redwood application:

<Spacer h={2} />

<Snippet text="yarn create redwood-app my-redwood-project" />

Redwood needs Node 20. Switch with `nvm use 20` before creating the project, and run `corepack enable` if `yarn` is not found.

<Spacer h={2} />

### Installation

Open web directory before installing dependencies:

<Spacer h={2} />

<Snippet text="cd web" />

<Spacer h={2} />

Install dependencies:

<PackageTabs pnpm="pnpm add @bolio-ui/core" npm="npm i @bolio-ui/core" yarn="yarn add @bolio-ui/core" bun="bun add @bolio-ui/core" />

<Spacer h={2} />

### Setup

Add styles imports, BolioUIProvider and CssBaseline to web/src/App.tsx:

```jsx
import { BolioUIProvider, CssBaseline } from '@bolio-ui/core'
import '@bolio-ui/core/styles.css'

import { FatalErrorBoundary, RedwoodProvider } from '@redwoodjs/web'
import { RedwoodApolloProvider } from '@redwoodjs/web/apollo'

import FatalErrorPage from 'src/pages/FatalErrorPage'
import Routes from 'src/Routes'

const App = () => (
  <FatalErrorBoundary page={FatalErrorPage}>
    <RedwoodProvider titleTemplate="%PageTitle | %AppTitle">
      <BolioUIProvider>
        <RedwoodApolloProvider>
          <CssBaseline />
          <Routes />
        </RedwoodApolloProvider>
      </BolioUIProvider>
    </RedwoodProvider>
  </FatalErrorBoundary>
)

export default App
```

Ready to go! Start the development server:

<Snippet text="yarn rw dev" />

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { PackageTabs } from 'src/components'
import { Link, Spacer } from 'core'

export const meta = {
  title: 'Example with RedwoodSDK',
  description: 'Set up Bolio UI in a RedwoodSDK application.',
  sidebar: 'guide',
  group: 'Guide'
}

## Example with RedwoodSDK

<Spacer h={2} />

### Get started with an example

To begin, the most straightforward approach is to utilize one of the provided templates.
These templates come pre-configured with the necessary settings, such as CssBaseline and other fundamental components.

If you're new to GitHub and need guidance on initiating a project using a template,
you can access comprehensive instructions on how to get started on <Link target="_blank" rel="nofollow" color icon href="https://github.com/bolio-ui/bolio-ui/tree/master/examples/create-rwsdk">this example</Link>.

<Spacer h={2} />

### Generate new application

Follow <Link target="_blank" rel="nofollow" color icon href="https://docs.rwsdk.com/getting-started/quick-start/">RedwoodSDK quick start</Link> guide to create new application:

<PackageTabs pnpm="pnpm dlx create-rwsdk@latest create my-app" npm="npx create-rwsdk@latest create my-app" yarn="yarn dlx create-rwsdk@latest create my-app" bun="bunx create-rwsdk@latest create my-app" />

<Spacer h={2} />

### Installation

Install dependencies:

<PackageTabs pnpm="pnpm add @bolio-ui/core" npm="npm i @bolio-ui/core" yarn="yarn add @bolio-ui/core" bun="bun add @bolio-ui/core" />

<Spacer h={2} />

### Setup

RedwoodSDK is not RedwoodJS. It runs on Cloudflare Workers with React Server Components, and `BolioUIProvider` is already a client component. The document is a server component, so it cannot import CSS directly. Import the stylesheet as a URL and link it in the `<head>`, then add BolioUIProvider and CssBaseline to `src/app/document.tsx`:

```jsx
import { BolioUIProvider, CssBaseline } from '@bolio-ui/core'
import bolioStyles from '@bolio-ui/core/styles.css?url'

export const Document: React.FC<{ children: React.ReactNode }> = ({
  children
}) => (
  <html lang="en">
    <head>
      <link rel="stylesheet" href={bolioStyles} />
      <meta charSet="utf-8" />
      <meta name="viewport" content="width=device-width, initial-scale=1" />
      <title>My app</title>
      <link rel="modulepreload" href="/src/client.tsx" />
    </head>
    <body>
      <BolioUIProvider>
        <CssBaseline />
        {children}
      </BolioUIProvider>
      <script>import("/src/client.tsx")</script>
    </body>
  </html>
)
```

Ready to go! Start the development server:

<PackageTabs pnpm="pnpm dev" npm="npm run dev" yarn="yarn dev" bun="bun run dev" />

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { PackageTabs } from 'src/components'
import { Link, Spacer } from 'core'

export const meta = {
  title: 'Example with Remix',
  description: 'Set up Bolio UI in a Remix application.',
  sidebar: 'guide',
  group: 'Guide'
}

## Example with Remix

<Spacer h={2} />

### Get started with an example

To begin, the most straightforward approach is to utilize one of the provided templates.
These templates come pre-configured with the necessary settings, such as CssBaseline and other fundamental components.

If you're new to GitHub and need guidance on initiating a project using a template,
you can access comprehensive instructions on how to get started on <Link target="_blank" rel="nofollow" color icon href="https://github.com/bolio-ui/bolio-ui/tree/master/examples/create-remix">this example</Link>.

<Spacer h={2} />

### Generate new application

Follow <Link target="_blank" rel="nofollow" color icon href="https://remix.run/">Remix getting started</Link> guide to create new Remix application:

<PackageTabs pnpm="pnpm create remix@latest" npm="npx create-remix@latest" yarn="yarn create remix" bun="bunx create-remix@latest" />

<Spacer h={2} />

### Installation

Install dependencies:

<PackageTabs pnpm="pnpm add @bolio-ui/core" npm="npm i @bolio-ui/core" yarn="yarn add @bolio-ui/core" bun="bun add @bolio-ui/core" />

<Spacer h={2} />

### Setup

Add styles imports, BolioUIProvider and CssBaseline to app/root.tsx:

```jsx
import {
  Links,
  LiveReload,
  Meta,
  Outlet,
  Scripts,
  ScrollRestoration
} from '@remix-run/react'
import { BolioUIProvider, CssBaseline } from '@bolio-ui/core'
import '@bolio-ui/core/styles.css'

export default function App() {
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <Meta />
        <Links />
      </head>
      <body>
        <BolioUIProvider>
          <CssBaseline />
          <Outlet />
          <ScrollRestoration />
          <Scripts />
          <LiveReload />
        </BolioUIProvider>
      </body>
    </html>
  )
}
```

Ready to go! Start the development server:

<PackageTabs pnpm="pnpm dev" npm="npm run dev" yarn="yarn dev" bun="bun run dev" />

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { PackageTabs } from 'src/components'
import { Link, Spacer } from 'core'

export const meta = {
  title: 'Example with TanStack Start',
  description: 'Set up Bolio UI in a TanStack Start application.',
  sidebar: 'guide',
  group: 'Guide'
}

## Example with TanStack Start

<Spacer h={2} />

### Get started with an example

To begin, the most straightforward approach is to utilize one of the provided templates.
These templates come pre-configured with the necessary settings, such as CssBaseline and other fundamental components.

If you're new to GitHub and need guidance on initiating a project using a template,
you can access comprehensive instructions on how to get started on <Link target="_blank" rel="nofollow" color icon href="https://github.com/bolio-ui/bolio-ui/tree/master/examples/create-tanstack-start">this example</Link>.

<Spacer h={2} />

### Generate new application

Follow <Link target="_blank" rel="nofollow" color icon href="https://tanstack.com/start/latest/docs/framework/react/getting-started">TanStack Start getting started</Link> guide to create new application:

<PackageTabs pnpm="pnpm dlx @tanstack/cli@latest create my-app" npm="npx @tanstack/cli@latest create my-app" yarn="yarn dlx @tanstack/cli@latest create my-app" bun="bunx @tanstack/cli@latest create my-app" />

<Spacer h={2} />

### Installation

Install dependencies:

<PackageTabs pnpm="pnpm add @bolio-ui/core" npm="npm i @bolio-ui/core" yarn="yarn add @bolio-ui/core" bun="bun add @bolio-ui/core" />

<Spacer h={2} />

### Setup

Add styles imports, BolioUIProvider and CssBaseline to `src/routes/__root.tsx`:

```jsx
import { HeadContent, Scripts, createRootRoute } from '@tanstack/react-router'
import { BolioUIProvider, CssBaseline } from '@bolio-ui/core'
import '@bolio-ui/core/styles.css'

export const Route = createRootRoute({
  shellComponent: RootDocument
})

function RootDocument({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        <HeadContent />
      </head>
      <body>
        <BolioUIProvider>
          <CssBaseline />
          {children}
        </BolioUIProvider>
        <Scripts />
      </body>
    </html>
  )
}
```

Ready to go! Start the development server:

<PackageTabs pnpm="pnpm dev" npm="npm run dev" yarn="yarn dev" bun="bun run dev" />

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { PackageTabs } from 'src/components'
import { Link, Spacer } from 'core'

export const meta = {
  title: 'Example with Vite',
  description: 'Set up Bolio UI in a Vite application.',
  sidebar: 'guide',
  group: 'Guide'
}

## Example with Vite

<Spacer h={2} />

### Get started with an example

To begin, the most straightforward approach is to utilize one of the provided templates.
These templates come pre-configured with the necessary settings, such as CssBaseline and other fundamental components.

If you're new to GitHub and need guidance on initiating a project using a template,
you can access comprehensive instructions on how to get started on <Link target="_blank" rel="nofollow" color icon href="https://github.com/bolio-ui/bolio-ui/tree/master/examples/create-vite">this example</Link>.

<Spacer h={2} />

### Generate new application

Follow <Link target="_blank" rel="nofollow" color icon href="https://vitejs.dev/guide/">Vite getting started</Link> guide to create new Vite application:

<PackageTabs pnpm="pnpm create vite" npm="npm create vite@latest" yarn="yarn create vite" bun="bun create vite" />

<Spacer h={2} />

### Installation

Install dependencies:

<PackageTabs pnpm="pnpm add @bolio-ui/core" npm="npm i @bolio-ui/core" yarn="yarn add @bolio-ui/core" bun="bun add @bolio-ui/core" />

<Spacer h={2} />

### Setup

Add styles imports, BolioUIProvider and CssBaseline to src/App.tsx:

```jsx
import { BolioUIProvider, CssBaseline, Text } from '@bolio-ui/core'
import '@bolio-ui/core/styles.css'

export default function App() {
  return (
    <BolioUIProvider>
      <CssBaseline />
      <Text p>Your app page here</Text>
    </BolioUIProvider>
  )
}
```

Ready to go! Start the development server:

<PackageTabs pnpm="pnpm dev" npm="npm run dev" yarn="yarn dev" bun="bun run dev" />

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { PackageTabs } from 'src/components'
import { Link, Spacer } from 'core'

export const meta = {
  title: 'Example with Waku',
  description: 'Set up Bolio UI in a Waku application.',
  sidebar: 'guide',
  group: 'Guide'
}

## Example with Waku

<Spacer h={2} />

### Get started with an example

To begin, the most straightforward approach is to utilize one of the provided templates.
These templates come pre-configured with the necessary settings, such as CssBaseline and other fundamental components.

If you're new to GitHub and need guidance on initiating a project using a template,
you can access comprehensive instructions on how to get started on <Link target="_blank" rel="nofollow" color icon href="https://github.com/bolio-ui/bolio-ui/tree/master/examples/create-waku">this example</Link>.

<Spacer h={2} />

### Generate new application

Follow <Link target="_blank" rel="nofollow" color icon href="https://waku.gg/">Waku</Link> guide to create new application:

<PackageTabs pnpm="pnpm create waku@latest" npm="npm create waku@latest" yarn="yarn create waku" bun="bun create waku@latest" />

<Spacer h={2} />

### Installation

Install dependencies:

<PackageTabs pnpm="pnpm add @bolio-ui/core" npm="npm i @bolio-ui/core" yarn="yarn add @bolio-ui/core" bun="bun add @bolio-ui/core" />

With Yarn, the Waku template also needs `@babel/core`, which Yarn does not install as a peer dependency. Add it with `yarn add @babel/core`.

<Spacer h={2} />

### Setup

Waku renders layouts as React Server Components, and `BolioUIProvider` is already a client component, so it can be used in the layout directly. Add styles imports, BolioUIProvider and CssBaseline to `src/pages/_layout.tsx`:

```jsx
import '../styles.css'
import '@bolio-ui/core/styles.css'

import type { ReactNode } from 'react'
import { BolioUIProvider, CssBaseline } from '@bolio-ui/core'

export default async function RootLayout({ children }: { children: ReactNode }) {
  return (
    <BolioUIProvider>
      <CssBaseline />
      {children}
    </BolioUIProvider>
  )
}

export const getConfig = async () => {
  return {
    render: 'static'
  } as const
}
```

Ready to go! Start the development server:

<PackageTabs pnpm="pnpm dev" npm="npm run dev" yarn="yarn dev" bun="bun run dev" />

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Text, Spacer } from 'core'

export const meta = {
  title: 'Contribute',
  description:
    'Ways to contribute to Bolio UI, from documentation to code.',
  sidebar: 'guide',
  group: 'Guide'
}

## Contribute

<Spacer h={2} />

### Ways to contribute

First and foremost, we appreciate your interest in contributing to Bolio UI! Your contributions play a crucial role in enhancing the project.
Here are various ways you can get involved

- • <Text b>Enhance documentation:</Text> Address incomplete or missing documentation,
  improve wording, examples, or explanations.

- • <Text b>Provide feedback:</Text> We are continually striving to improve Bolio UI. Please share your usage experiences, highlight missing features, and let us know what works well through <a href="https://github.com/bolio-ui/bolio-ui/discussions" rel="noreferrer" target="_blank">GitHub Discussions</a>.

- • <Text b>Promote Bolio UI:</Text> Share links to the Bolio UI documentation with anyone who might find it useful.

- • <Text b>Contribute to the codebase:</Text> Propose new features by opening <a href="https://github.com/bolio-ui/bolio-ui/issues/new" rel="noreferrer" target="_blank">GitHub Issues</a>, or take on <a href="https://github.com/bolio-ui/bolio-ui/labels/" rel="noreferrer" target="_blank">existing issues</a> that align with your interests.

- • <Text b>Conduct a code review:</Text> Help us identify issues in the <a href="https://github.com/bolio-ui/bolio-ui/tree/master/src" rel="noreferrer" target="_blank">source code</a> or suggest improvements to make Bolio UI more efficient.

<Spacer h={2} />

### How to contribute?

- • Decide on the contribution you want to make.

- • For new features, discuss your ideas with the maintainer (via <a href="https://github.com/bolio-ui/bolio-ui/discussions" rel="noreferrer" target="_blank">GitHub Discussions</a>) before starting the coding process.

- • Once issue details are finalized, adhere to commit conventions as you work on the code.

- • Run tests using `npm test` and submit a pull request (pull request) after ensuring all tests pass.

- • Undergo a code review, addressing any issues identified by the maintainer.

- • If you're unable to complete the task or have a change of plans, no worries! Just inform us in the GitHub issue you initially created.
  The Bolio UI community is understanding – no judgment or questions if you decide to cancel your submission.

- • Your pull request gets merged!"

<Spacer h={2} />

### npm scripts

All npm scripts can be found in the <a href="https://github.com/bolio-ui/bolio-ui/blob/master/package.json" rel="noreferrer" target="_blank">main package.json</a> file. Dedicated scripts are not assigned to individual packages.

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Spacer } from 'core'
import { ThemeGenerator, PackageTabs } from 'src/components'

export const meta = {
  title: 'Customize Themes',
  description:
    'Support a variety of themes, and it is very easy to create or inherit modifications.',
  sidebar: 'guide',
  group: 'Theme'
}

## Customize Themes

<Spacer h={2} />

### Usage

**Bolio UI** now offers support for a variety of themes, and it is incredibly easy to create or inherit modifications,
without the need for third-party styles or configurations. As a basic choice, there are two themes available: `light` and `dark`.

<Spacer h={2} />

### Theme Generator

Not sure which colors to pick? Try them below. Bolio UI derives the shades it actually uses
(light, lighter and dark) from a primary and a secondary color, and gives you the code to drop
into `Themes.createFromLight`. For the full version, with a live preview of every `Button`
variant in light and dark, open the [Theme Generator](/theme-generator) page.

<ThemeGenerator compact />

<Spacer h={2} />

### Switch themes

To change between the default themes, you simply need to adjust the value of `themeType`. You can follow the steps below:

1. Ensure that `BolioUIProvider` and `CssBaseline` are already placed in the root component.

2. Modify the `themeType` value, and all components will automatically adapt to the new theme.

```jsx
// NAME:src/app.js
import { CssBaseline, BolioUIProvider } from '@bolio-ui/core'

const App = () => {
  const [themeType, setThemeType] = useState('light')

  const switchThemes = () => {
    setThemeType((last) => (last === 'dark' ? 'light' : 'dark'))
  }

  return (
    <BolioUIProvider themeType={themeType}>
      <CssBaseline />
      <YourComponent onClick={switchThemes} />
    </BolioUIProvider>
  )
}
```

<Spacer h={2} />

### Customizing theme

Modifying a theme in Bolio UI is straightforward. You only need to supply a new theme `Object`,
and all the components will seamlessly adjust.
Here is a complete [sample](https://github.com/bolio-ui/bolio-ui/tree/master/examples/custom-themes) for your reference.

```jsx
import { CssBaseline, BolioUIProvider, Themes } from '@bolio-ui/core'

const myNewTheme1 = Themes.createFromLight({
  type: 'newTheme',
  palette: {
    success: '#000'
  }
})

const App = () => (
  <BolioUIProvider themes={[myNewTheme1]} themeType="newTheme">
    <CssBaseline />
    <YourAppComponent onClick={switchThemes} />
  </BolioUIProvider>
)
```

The `Themes.createFromLight` function enables you to derive a new theme from the Light Theme.
Likewise, you have the option to create a theme rooted in the dark style using : `Themes.createFromDark`.
Alternatively, you can craft a theme based on your custom preferences:

```jsx
const myBaseTheme = { ... }

const myNewTheme2 = Themes.create(myBaseTheme, {
  type: 'newTheme2',
  palette: {
    success: '#000',
  },
})
```

<Spacer h={2} />

### Get types

If you require a comprehensive type definition while making theme adjustments,
you can consult the [type file](https://github.com/bolio-ui/bolio-ui/blob/master/core/Themes/Presets/index.ts)
already available. For projects that support TypeScript, you can directly access the type within the package.

```ts
import {
  BolioUIThemes,
  BolioUIThemesFont,
  BolioUIThemesPalette,
  BolioUIThemesExpressiveness,
  BolioUIThemesLayout
} from '@bolio-ui/core'

// usage:
const myStyles: BolioUIThemes = {
  /* ... */
}
const myPalette: Partial<BolioUIThemesPalette> = {
  /* ... */
}
```

<Spacer h={2} />

### Customizer

<Spacer h={1} />

#### ClassName

You have the ability to customize the style by specifying a `className` for the component.

```jsx
import { Button, Row } from '@bolio-ui/core'

const MyPage = () => (
  <Row>
    <Button className="my-page-button">Click here!</Button>
  </Row>
)

// in css file:
.my-page-button {
  padding: 0;
}
```

<Spacer h={2} />

#### Inline styles

Using an inline style will effectively supersede the component's default styling.

```jsx
const MyPage = () => (
  <Row>
    <Button style={{ margin: '20px' }}>Click me!</Button>
  </Row>
)
```

<Spacer h={2} />

### Build components

You can utilize the Bolio UI preset Hooks to access theme states and craft your own components. For additional details,
please consult the [useTheme](/docs/hooks/use-theme) documentation.

```jsx
import { useTheme } from '@bolio-ui/core'

const MyComponent = () => {
  const theme = useTheme()

  return (
    <div style={{ color: theme.palette.success }}>
      <span>hello world!</span>
    </div>
  )
}
```

<Spacer h={2} />

### Fonts

In Web applications, certain fonts may not display optimally on Windows, or you might find that font rendering for specific character sets not satisfactory.
If this occurs, you have the option to enhance the rendering by adding extra font packages

> You're not required to make any changes to CSS files or specify font declarations.

<Spacer h={2} />

#### Install `inter-ui`

<PackageTabs pnpm="pnpm add inter-ui" npm="npm i inter-ui" yarn="yarn add inter-ui" bun="bun add inter-ui" />

<Spacer h={3} />

#### Add `Inter Font` to your project:

```jsx
import 'inter-ui/inter.css'
```

<Spacer h={2} />

### Themes APIs

`Themes` offer a range of static methods that prove valuable when dealing with custom themes:

- • `Themes.create` - Create a new theme object.
- • `Themes.createFromDark` - Generate a new theme object based on the Dark Theme.
- • `Themes.createFromLight` - Construct a new theme object based on the Light Theme.
- • `Themes.isPresetTheme` - Verify if a theme serves as the foundation for Bolio UI.
- • `Themes.isAvailableThemeType` - Determine if a theme name is available.
- • `Themes.hasUserCustomTheme` - Check for the presence of custom themes within a list.
- • `Themes.getPresets` - Retrieve a default list of themes.
- • `Themes.getPresetStaticTheme` - Access the theme loaded by Bolio UI as the default.

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Spacer } from 'core'
import { Colors } from 'src/components'

export const meta = {
  title: 'Default Theme',
  description:
    'You can use any color anywhere, all colors change with the theme.',
  sidebar: 'guide',
  group: 'Theme'
}

## Default Theme

<Spacer h={2} />

### Usage

You can use any color anywhere, all colors change with the theme.
If you want to customize your colors, please read [use-theme](/docs/hooks/use-theme) to learn more.

```jsx
import { useTheme, Text } from '@bolio-ui/core'

const TextCustomComponent = () => {
  const { palette } = useTheme()

  return <Text style={{ color: palette.accents_1 }}>TextCustomComponent</Text>
}
```

<Spacer h={2} />

### Colors

<Colors />

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Attributes, CodeTabs, PackageTabs } from 'src/components'
import { Spacer } from 'core'

export const meta = {
  title: 'Getting Started',
  description:
    'Welcome to the Bolio UI documentation! Bolio UI allows you to make beautiful, modern, and fast websites/applications regardless of your design experience.',
  sidebar: 'guide',
  group: 'Guide'
}

## Getting Started

<Spacer h={2} />

#### Welcome to the Bolio UI documentation!

Bolio UI allows you to make beautiful, modern, and fast websites/applications regardless of your design experience, created with <a href="https://reactjs.org/" rel="noreferrer" target="_blank">React.js</a>.

<Spacer h={2} />

### New project

Create a project with Bolio UI already set up. The command makes the project with the generator of the framework, installs `@bolio-ui/core` and wraps the app in `BolioUIProvider`:

<PackageTabs
  pnpm="pnpm dlx @bolio-ui/cli@latest init my-app -t next"
  npm="npx @bolio-ui/cli@latest init my-app -t next"
  yarn="yarn dlx @bolio-ui/cli@latest init my-app -t next"
  bun="bunx --bun @bolio-ui/cli@latest init my-app -t next"
/>

Pick the framework with `-t`. Without it, the command asks which one you want.

| Template       | Creates                                  | Guide                                                      |
| -------------- | ---------------------------------------- | ---------------------------------------------------------- |
| `next`         | Next.js, App Router and TypeScript       | [Next.js](/docs/guide/bolio-ui-plus-nextjs)                |
| `vite`         | Vite, React and TypeScript               | [Vite](/docs/guide/bolio-ui-plus-vite)                     |
| `react-router` | React Router in framework mode           | [Remix](/docs/guide/bolio-ui-plus-remix)                   |
| `gatsby`       | Gatsby and TypeScript                    | [Gatsby](/docs/guide/bolio-ui-plus-gatsby)                 |
| `redwood`      | RedwoodJS and TypeScript, needs Corepack | [RedwoodJS](/docs/guide/bolio-ui-plus-redwoodjs)           |
| `tanstack`     | TanStack Start and TypeScript            | [TanStack Start](/docs/guide/bolio-ui-plus-tanstack-start) |
| `waku`         | Waku and TypeScript                      | [Waku](/docs/guide/bolio-ui-plus-waku)                     |
| `rwsdk`        | RedwoodSDK and TypeScript                | [RedwoodSDK](/docs/guide/bolio-ui-plus-redwoodsdk)         |
| `astro`        | Astro with React, needs Node 22          | [Astro](/docs/guide/bolio-ui-plus-astro)                   |

Add `-y` to skip every question and `--icons` to also install `@bolio-ui/icons`. The generators run with `npx`, so Node needs npm.

<Spacer h={2} />

### Existing project

Run it at the root of a project you already have. It detects Next.js, Vite, React Router, Remix, Gatsby, RedwoodJS, TanStack Start, Waku, RedwoodSDK or Astro, installs `@bolio-ui/core` with the package manager of your lockfile, and edits the root file of the app:

<PackageTabs
  pnpm="pnpm dlx @bolio-ui/cli@latest init"
  npm="npx @bolio-ui/cli@latest init"
  yarn="yarn dlx @bolio-ui/cli@latest init"
  bun="bunx --bun @bolio-ui/cli@latest init"
/>

If a file does not look the way the command expects, it leaves the file alone and prints the lines to add. Running it again changes nothing. To do the same by hand, follow the next two steps.

<Spacer h={2} />

### Install

Inside your React project directory, install Bolio UI by running any of the following:

<PackageTabs
  pnpm="pnpm add @bolio-ui/core"
  npm="npm i @bolio-ui/core"
  yarn="yarn add @bolio-ui/core"
  bun="bun add @bolio-ui/core"
/>

<Spacer h={2} />

### Setup

For Bolio UI to work correctly, you need to set up the `BolioUIProvider` and the `CssBaseline` at the root of your application.

<Spacer h={1} />

#### React

Go to the root of your application and do this:

```tsx
// NAME: /src/app.js
import * as React from 'react'

// 1. import the styles once, `BolioUIProvider` and `CssBaseline`
import '@bolio-ui/core/styles.css'
import { BolioUIProvider, CssBaseline } from '@bolio-ui/core'

function App({ Component }) {
  // 2. Use at the root of your app
  return (
    <BolioUIProvider>
      <CssBaseline />
      <Component />
    </BolioUIProvider>
  )
}
```

<Spacer h={2} />

#### Next.js

Add this to the root of your app. Use the file of the router you have: `pages/_app` (create it if it doesn't exist) or `app/layout`.

<CodeTabs>

```tsx
// NAME: pages/_app.tsx
// 1. import the styles once, `BolioUIProvider` and `CssBaseline`
import '@bolio-ui/core/styles.css'
import { BolioUIProvider, CssBaseline } from '@bolio-ui/core'

function MyApp({ Component, pageProps }) {
  return (
    // 2. Use at the root of your app
    <BolioUIProvider>
      <CssBaseline />
      <Component {...pageProps} />
    </BolioUIProvider>
  )
}

export default MyApp
```

```tsx
// NAME: app/layout.tsx
// 1. import the styles once, `BolioUIProvider` and `CssBaseline`
import '@bolio-ui/core/styles.css'
import { BolioUIProvider, CssBaseline } from '@bolio-ui/core'

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <BolioUIProvider>
          <CssBaseline />
          {children}
        </BolioUIProvider>
      </body>
    </html>
  )
}
```

</CodeTabs>

Neither router needs a custom `_document` or a styles registry: the CSS ships as a plain stylesheet, not injected at render time.

> For more information about Next.js + Bolio UI check out the [documentation](/docs/guide/bolio-ui-plus-nextjs).

<Spacer h={2} />

### Using Bolio UI components

Once Bolio UI is installed you can use any of the components as follows.
Bolio UI uses tree-shaking so the unused modules will not be included in the bundle during the build process and
each component is exported separately.

```tsx
import { Button } from '@bolio-ui/core'

const Component = () => <Button>Click me</Button>
```

<Spacer h={2} />

<Attributes edit="/content/docs/guide/getting-started.mdx">
<Attributes.Title>BolioUIProvider.Props</Attributes.Title>

| Attribute     | Type                   | Accepted values                                 | Description                                                  | Default |
| ------------- | ---------------------- | ----------------------------------------------- | ------------------------------------------------------------ | ------- |
| **themes**    | `Array<BolioUIThemes>` | -                                               | Custom themes added to the default `light` and `dark` themes | -       |
| **themeType** | `string`               | `light`, `dark` or the `type` of a custom theme | Theme applied to every component                             | `light` |

</Attributes>

<Spacer h={2} />

### Community

We're excited to see the community adopt Bolio UI, raise issues, and provide feedback.
Whether it's a feature request, bug report, or a project to showcase, please get involved!

- • [Instagram](https://instagram.com/bolio.ui)
- • [GitHub](https://github.com/bolio-ui/bolio-ui)

<Spacer h={2} />

### Contributing

PR's on Bolio UI are always welcome, please see our [contribution guidelines](https://github.com/bolio-ui/bolio-ui/blob/main/CONTRIBUTING.MD) to learn how you can contribute to this project.

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Text, Spacer } from 'core'

export const meta = {
  title: 'LLMs.txt',
  description:
    'Enable AI assistants like Claude Code, Cursor and Windsurf to understand Bolio UI, with the docs published as Markdown.',
  sidebar: 'guide',
  group: 'Guide'
}

## LLMs.txt

<Spacer h={2} />

### Available files

We provide LLMs.txt files to make the Bolio UI documentation accessible to AI coding assistants. Every page is also available alone as Markdown, so an assistant reads the real props and examples instead of guessing them.

<Text b>Core documentation:</Text>

- • [`/llms.txt`](/llms.txt): quick reference index, with one line per page
- • [`/llms-full.txt`](/llms-full.txt): complete Bolio UI documentation

<Text b>For limited context windows:</Text>

- • [`/llms-components.txt`](/llms-components.txt): components and hooks only
- • [`/llms-guide.txt`](/llms-guide.txt): guides only, such as setup, themes and page structure

<Text b>A single page:</Text>

- • `/md/components/button`: one page as Markdown. Use any section (`guide`, `components` or `hooks`) and page name.

<Spacer h={2} />

### Claude Code

Tell Claude to reference the documentation:

```text
Use the Bolio UI documentation from https://bolio-ui.com/llms.txt
```

Or add the links to your project with [AGENTS.md](/docs/guide/agents-md), so Claude loads them on every session.

<Spacer h={2} />

### Cursor

Use the `@Docs` feature:

```text
@Docs https://bolio-ui.com/llms-full.txt
```

<Spacer h={2} />

### Windsurf

Add this line to your `.windsurfrules` file:

```text
#docs https://bolio-ui.com/llms-full.txt
```

<Spacer h={2} />

### Other AI tools

Most AI assistants can reference documentation by URL. Simply provide:

```text
https://bolio-ui.com/llms.txt
```

For component and hook documentation only:

```text
https://bolio-ui.com/llms-components.txt
```

For setup and guides only:

```text
https://bolio-ui.com/llms-guide.txt
```

<Spacer h={2} />

### Contributing

Found an issue with AI-generated code? Help us improve the LLMs.txt files by [opening an issue on GitHub](https://github.com/bolio-ui/bolio-ui/issues/new).

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Spacer } from 'core'

export const meta = {
  title: 'MCP Server',
  description:
    'Access the Bolio UI documentation directly in your AI assistant, with the Bolio UI MCP Server.',
  sidebar: 'guide',
  group: 'Guide'
}

## MCP Server

The Bolio UI MCP Server gives AI assistants direct access to the documentation of every component, hook and guide, so they build with the real props and examples.

It is published as `@bolio-ui/mcp` on npm and uses the stdio transport. It reads the same pages as [LLMs.txt](/docs/guide/llms-txt), so it needs no API key.

<Spacer h={2} />

### Cursor

Add to `.cursor/mcp.json`, or to `~/.cursor/mcp.json` to use it in every project:

```json
{
  "mcpServers": {
    "bolio-ui": {
      "command": "npx",
      "args": ["-y", "@bolio-ui/mcp@latest"]
    }
  }
}
```

<Spacer h={2} />

### Claude Code

Run this command in your terminal:

```bash
claude mcp add bolio-ui -- npx -y @bolio-ui/mcp@latest
```

Or add to the `.mcp.json` file of your project:

```json
{
  "mcpServers": {
    "bolio-ui": {
      "command": "npx",
      "args": ["-y", "@bolio-ui/mcp@latest"]
    }
  }
}
```

Restart Claude Code and run `/mcp`. When the server shows Connected, it is ready to use.

<Spacer h={2} />

### Windsurf

Add to `.windsurf/mcp.json`, then restart Windsurf:

```json
{
  "mcpServers": {
    "bolio-ui": {
      "command": "npx",
      "args": ["-y", "@bolio-ui/mcp@latest"]
    }
  }
}
```

<Spacer h={2} />

### Zed

Add to your `settings.json`, then restart Zed. In the Agent Panel settings, the dot next to the server turns green when it is active:

```json
{
  "context_servers": {
    "bolio-ui": {
      "command": "npx",
      "args": ["-y", "@bolio-ui/mcp@latest"],
      "env": {}
    }
  }
}
```

<Spacer h={2} />

### VS Code

Add to `.vscode/mcp.json`, then click Start next to the server:

```json
{
  "servers": {
    "bolio-ui": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@bolio-ui/mcp@latest"]
    }
  }
}
```

<Spacer h={2} />

### Codex

Add to `~/.codex/config.toml`, or to `.codex/config.toml` in your project, then restart Codex and run `/mcp` to check it:

```toml
[mcp_servers.bolio-ui]
command = "npx"
args = ["-y", "@bolio-ui/mcp@latest"]
```

<Spacer h={2} />

### OpenCode

Add to `opencode.json`, then restart OpenCode:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "bolio-ui": {
      "type": "local",
      "command": ["npx", "-y", "@bolio-ui/mcp@latest"]
    }
  }
}
```

<Spacer h={2} />

### Usage

Once configured, ask your AI assistant questions like:

- • "Show me all Bolio UI components"
- • "What props does the Button component have?"
- • "Give me an example of using the Modal component"
- • "Help me install Bolio UI in my Vite app"
- • "How do I customize the theme?"
- • "Which hooks does Bolio UI have?"
- • "What are the theme colors for dark mode?"

<Spacer h={2} />

### Available tools

| Tool                  | Description                                                                                                            |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `list_components`     | List all Bolio UI components, with a summary of each                                                                   |
| `list_hooks`          | List all Bolio UI hooks, with a summary of each                                                                        |
| `get_component_docs`  | Get the documentation of one or more components, including props, examples and usage                                   |
| `get_theme_variables` | Get the theme tokens (colors, font, layout, breakpoints and shadows) of the light theme, the dark theme or both        |
| `get_docs`            | Get one page by path, such as `guide/getting-started` or `hooks/use-theme`. Without a path, returns the index of pages |

<Spacer h={2} />

### Troubleshooting

Requirements: Node.js 18 or higher. The package is downloaded by `npx` the first time the server starts.

Something not working? Open an issue on [GitHub](https://github.com/bolio-ui/bolio-ui/issues/new).

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { PackageTabs } from 'src/components'
import { Spacer } from 'core'

export const meta = {
  title: 'Migrating to v3',
  description: 'What changes in v3 and what to do about it, coming from v1 or from a v2 alpha.',
  sidebar: 'guide',
  group: 'Guide'
}

## Migrating to v3

Version 3 drops the styled-jsx runtime: every component now ships plain, static CSS instead of injecting `<style>` tags at render time.
This page lists what changes and what to do about it. The documentation of v2 stays available at <a href="https://v2.bolio-ui.com" rel="noreferrer" target="_blank">v2.bolio-ui.com</a>.

Version 2 was only published as alphas, so most projects come from 1.x or from a v2 alpha. Coming from 1.x, read the <a href="https://v2.bolio-ui.com/docs/guide/migration-v1-to-v2" rel="noreferrer" target="_blank">migration guide to v2</a> first, then this page. Install v3 with:

<PackageTabs pnpm="pnpm add @bolio-ui/core" npm="npm i @bolio-ui/core" yarn="yarn add @bolio-ui/core" bun="bun add @bolio-ui/core" />

<Spacer h={2} />

### Breaking changes

#### Import the stylesheet once

Styling used to be injected by styled-jsx on every render. Now it ships as a real `.css` file, so every app needs one import, once, anywhere before the components render:

```jsx
import '@bolio-ui/core/styles.css'
```

Without it, components render unstyled. Add it next to your other top-level imports (`pages/_app.js`, `app/layout.js`, `src/main.tsx`, and so on). See <a href="/docs/guide/getting-started">Getting Started</a> for the setup of each router and framework.

#### `StyledJsxRegistry` and `@bolio-ui/core/next` are gone

The App Router no longer needs a styles registry, because nothing is rendered into the HTML at request time anymore. Remove the wrapper:

```jsx
// v2: app/layout.js
import { BolioUIProvider, CssBaseline } from '@bolio-ui/core'
import { StyledJsxRegistry } from '@bolio-ui/core/next'

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <StyledJsxRegistry>
          <BolioUIProvider>
            <CssBaseline />
            {children}
          </BolioUIProvider>
        </StyledJsxRegistry>
      </body>
    </html>
  )
}

// v3: no registry, just the stylesheet import
import '@bolio-ui/core/styles.css'
import { BolioUIProvider, CssBaseline } from '@bolio-ui/core'

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <BolioUIProvider>
          <CssBaseline />
          {children}
        </BolioUIProvider>
      </body>
    </html>
  )
}
```

A custom server needs nothing beyond serving the stylesheet (or letting your bundler include it) and rendering the app normally: no registry to collect styles from.

#### `styled-jsx` is no longer a dependency

The package does not depend on `styled-jsx` anymore. If nothing else in your app uses it, you can remove it too.

#### Package entry points

`@bolio-ui/core/next` was removed from the `exports` map. These paths work:

| Path | What it is |
| ---- | ---------- |
| `@bolio-ui/core` | All components and hooks |
| `@bolio-ui/core/styles.css` | The stylesheet. Import it once |
| `@bolio-ui/core/css/*` | One stylesheet per component, for apps that want to import only what they use instead of the combined file |
| `@bolio-ui/core/dist/*` | Deep imports of the CommonJS build, as before. They work in Node and in bundlers |
| `@bolio-ui/core/esm/*` | Deep imports of the ES modules build, as before. They are for bundlers: Node cannot load them as they are, so in Node import the package root or `dist/*` |

Other paths are no longer resolved.

#### `Rating` was rebuilt

The old Rating changed its value on hover and then locked on click. Now the value only changes on click or with the arrow keys, and hover shows a preview.

- • `onValueChange` is now `onChange`.
- • `locked` and `onLockedChange` are gone. Use `readOnly` or `disabled`.
- • `initialValue` now defaults to `0`, not `1`.
- • The default color is the warning color, not gray.
- • The types `RatingCount` and `RatingValue` are gone: `count` and `value` are plain numbers.
- • New props: `precision`, `variant`, `emptyIcon`, `clearable`, `highlightSelectedOnly`, `onHoverChange` and `getLabel`.

<Spacer h={2} />

### Changes in behavior

- • **CSS specificity**: every component's styles are now wrapped in a CSS `@layer`, all of them below any unlayered CSS you write. A plain, unlayered selector in your own stylesheet always wins over a component's default style now, with no need for `!important` or extra specificity.
- • **Class names**: internal class names generated by CSS Modules (a hash like `Button-module_root__a1b2c`) replace the old styled-jsx hash. Neither was ever meant to be targeted directly; use the documented props and CSS custom properties instead.
- • **Box sizing**: `CssBaseline` now sets `box-sizing: border-box` on the page, and every element inherits it. A width or a height now includes the padding and the border. If your own styles assumed `content-box`, check the elements that have both a size and a border or padding.
- • **Collapse**: the title is now a heading with a native button inside, in place of a `div` with `role="button"`. A selector that targeted that `div` needs to change. `Collapse.Group` also moves the focus between the titles with the arrow keys, Home and End.
- • **Select**: the dropdown and its options take the colors of the field, so they follow its `type` and variant, in place of the fixed gray.
- • **Dropdown**: Menu, Select, Popover and the other dropdowns open upwards when there is not enough room below. A Menu no longer scrolls the page when it opens.
- • **Native controls follow the theme**: `CssBaseline` sets `color-scheme` on the page, so the clock of a time field, the scrollbars and the pickers of the browser are drawn for a dark page on the dark theme.

<Spacer h={2} />

### New components

These are in v3 and were not in `2.0.0-alpha.2`, or in 1.x. Nothing was removed.

- • <a href="/docs/components/carousel">Carousel</a>, <a href="/docs/components/color-input">Color Input</a> and <a href="/docs/components/color-picker">Color Picker</a>
- • <a href="/docs/components/command">Command</a>, <a href="/docs/components/context-menu">Context Menu</a> and <a href="/docs/components/date-range-picker">DateRangePicker</a>
- • <a href="/docs/components/dropzone">Dropzone</a>, <a href="/docs/components/empty-state">Empty State</a> and <a href="/docs/components/image-zoom">Image Zoom</a>
- • <a href="/docs/components/marquee">Marquee</a>, <a href="/docs/components/pin-input">Pin Input</a> and <a href="/docs/components/segmented-control">Segmented Control</a>
- • <a href="/docs/components/splitter">Splitter</a>, <a href="/docs/components/stat">Stat</a> and <a href="/docs/components/tags-input">Tags Input</a>
- • <a href="/docs/components/timeline">Timeline</a>, <a href="/docs/components/tour">Tour</a> and <a href="/docs/components/tree">Tree</a>
- • <a href="/docs/components/alert">Alert</a>, <a href="/docs/components/chip">Chip</a>, <a href="/docs/components/mention">Mention</a> and <a href="/docs/components/toolbar">Toolbar</a>

Existing components also got new props: `Collapse` has `visible`, `onVisibleChange` and `disabled`, `Calendar` has `numberOfMonths`, and `Table` has sortable columns (`sortable` and `sorter`), `sort`, `selectable`, `rowKey` and `selectedKeys`.

<Spacer h={2} />

### Checklist

1. Install `@bolio-ui/core` 3.0.0 or later.
2. Add `import '@bolio-ui/core/styles.css'` once, near your other top-level imports.
3. Remove `StyledJsxRegistry` and the `@bolio-ui/core/next` import from your App Router layout, if you had one.
4. Remove `styled-jsx` from your own dependencies if nothing else in your app uses it.
5. Search your own CSS for selectors that relied on beating a component's specificity; they may no longer need `!important`.

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground } from 'src/components'
import {
  Section,
  Container,
  Row,
  Col,
  Display,
  Card,
  Text,
  Spacer,
  useTheme
} from 'core'

export const meta = {
  title: 'Page structure',
  description:
    'Build the layout of a page with Section, Container, Row and Col.',
  sidebar: 'guide',
  group: 'Guide'
}

## Page structure

Four components build the layout of a page, one inside the other:

| Component | What it does |
| --------- | ------------ |
| <a href="/docs/components/section">Section</a> | A band of the page. It can have a background that goes from edge to edge |
| <a href="/docs/components/container">Container</a> | Limits the width and centers the content |
| <a href="/docs/components/row">Row</a> | A flex row |
| <a href="/docs/components/col">Col</a> | A column of the row, sized in twelfths |

<Spacer h={2} />

<Playground
  desc="Section, Container, Row and Col, with a Display and Cards as the content."
  scope={{ Section, Container, Row, Col, Display, Card, Text, useTheme }}
  code={`
() => {
  const theme = useTheme()
  return (
    <>
      <Section bg={theme.palette.accents_1} style={{ padding: '32px 0' }}>
        <Container>
          <Row align="middle">
            <Col span={6}>
              <Text h3>A page with Bolio UI</Text>
              <Text>The layout components hold the other components.</Text>
            </Col>
            <Col span={6}>
              <Display caption="A caption">
                <img src="/logo-colored.svg" alt="Bolio UI logo" width={80} height={80} />
              </Display>
            </Col>
          </Row>
        </Container>
      </Section>
      <Section style={{ padding: '32px 0' }}>
        <Container>
          <Row>
            <Col span={4}><Card><Text b>One third</Text></Card></Col>
            <Col span={4}><Card><Text b>One third</Text></Card></Col>
            <Col span={4}><Card><Text b>One third</Text></Card></Col>
          </Row>
        </Container>
      </Section>
    </>
  )
}
`}
/>

<Spacer h={2} />

### Rules that keep it working

- • Put the `Container` inside the `Section`, not the other way. The band goes from edge to edge and the content stays narrow.
- • The spans in a `Row` should add up to 12 or less. A `Row` does not wrap, so more than 12 makes the columns narrower.
- • Use a new `Row` for each line. If you need items that wrap to the next line by themselves, use <a href="/docs/components/grid">Grid</a>.
- • `Col` needs a `Row` around it. The space set by `gap` on the `Row` is what the columns use.

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Spacer } from 'core'

export const meta = {
  title: 'Refs and accessibility',
  description:
    'How refs work in every component and how to make controls accessible.',
  sidebar: 'guide',
  group: 'Guide'
}

## Refs and accessibility

<Spacer h={2} />

### Refs

Every component forwards its `ref`. The ref points at the element that receives the native props, such as `className`, event handlers and `data-*` attributes.

```tsx
import { useRef } from 'react'
import { Button, Input } from '@bolio-ui/core'

function Form() {
  const input = useRef<HTMLInputElement>(null)

  return (
    <>
      <Input ref={input} placeholder="Name" />
      <Button onClick={() => input.current?.focus()}>Focus the input</Button>
    </>
  )
}
```

| Component | The ref points at |
| --------- | ----------------- |
| Most components, such as Card, Text, Badge, Tag, Grid, Tabs, Calendar and Pagination | The root element |
| Input, Textarea, Combobox, DatePicker, Checkbox, Radio and Toggle | The native `input` or `textarea` |
| Button, Link and Image | The `button`, the `a` and the `img` |
| Table | The `table` |
| Modal and Drawer | The element with `role="dialog"` |
| Popover and Tooltip | The wrapper around the trigger |
| Select | A `SelectRef` with `focus`, `blur` and `scrollTo` |

<Spacer h={2} />

### Accessibility

#### Give a name to controls without visible text

Select, Combobox, DatePicker, Slider and Toggle can be used without a visible label. Name them with `aria-label`, or with `aria-labelledby` pointing at a text on the page:

```tsx
<Slider aria-label="Volume" initialValue={20} />
<Toggle aria-label="Notifications" />
<Select aria-label="Country" placeholder="Pick one">
  <Select.Option value="br">Brazil</Select.Option>
</Select>
```

Select uses its `placeholder` as the name when you do not pass one. A Button that only has an icon also needs an `aria-label`.

#### Keyboard

| Component | Keys |
| --------- | ---- |
| Tabs | Left and Right arrows move between tabs, Home and End go to the first and last |
| Slider | Arrows change the value by `step`, Page Up and Page Down by ten steps, Home and End go to the minimum and the maximum |
| Collapse | Enter and Space open and close it |
| Toggle, Checkbox and Radio | Tab reaches them and Space changes them, with a visible focus ring |
| Combobox | Arrow keys open the list and move between the options, Enter chooses, Escape closes |
| Calendar and DatePicker | Arrow keys move by day and week, Home and End by week, Page Up and Down by month, Enter and Space pick the day |
| Tooltip | Opens when the trigger gets the focus and closes with Escape |
| Popover | Escape closes it. The trigger has to be focusable, for example a Button |
| Modal and Drawer | Escape closes them, and Tab stays inside |

#### Roles and states

- • Toggle is a `switch`, Slider has `role="slider"` with `aria-valuemin`, `aria-valuemax` and `aria-valuenow`.
- • Tabs use `tablist`, `tab` and `tabpanel`, and mark the selected tab with `aria-selected`.
- • Collapse exposes `aria-expanded`, and Pagination marks the current page with `aria-current="page"`.
- • Modal and Drawer are `aria-modal` dialogs, Spinner and Loading have `role="status"`, and Tooltip is described by its content through `aria-describedby`.

#### How it is checked

The tests run <a href="https://github.com/dequelabs/axe-core" rel="noreferrer" target="_blank">axe-core</a> on the default render of every component, and check the keyboard behavior above.
The tests do not check color contrast, which depends on the theme, and they were not run with a real screen reader or in a browser.

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Alert, Button, Grid, useTheme } from 'core'

export const meta = {
  title: 'Alert',
  description: 'Show a message that stays in the page, with an optional title, icon and close button.',
  sidebar: 'components',
  group: 'Components',
  index: 54
}

## Alert

Show a message that stays in the page, with an optional title, icon and close button.

<Playground
  title="General"
  desc="The basic `Alert` usage. Errors and warnings are announced right away by a screen reader, the other types wait for a pause."
  scope={{ Alert, Grid }}
  code={`
<Grid.Container gap={2} direction="column">
  <Grid>
    <Alert title="Trial ending">Your trial ends in 3 days. Pick a plan to keep your projects.</Alert>
  </Grid>
  <Grid>
    <Alert type="success" title="Payment received">Invoice 2041 is paid.</Alert>
  </Grid>
  <Grid>
    <Alert type="warning" title="Storage almost full">You used 92% of your 10 GB.</Alert>
  </Grid>
  <Grid>
    <Alert type="error" title="Card declined">Your bank refused the payment. Update the card to retry.</Alert>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Variants"
  desc="Use `filled`, `light` or `subtle` to change how much the color takes over."
  scope={{ Alert, Grid }}
  code={`
<Grid.Container gap={2} direction="column">
  <Grid><Alert type="info" title="Outline">New features are on the way.</Alert></Grid>
  <Grid><Alert type="info" light title="Light">New features are on the way.</Alert></Grid>
  <Grid><Alert type="info" subtle title="Subtle">New features are on the way.</Alert></Grid>
  <Grid><Alert type="info" filled title="Filled">New features are on the way.</Alert></Grid>
</Grid.Container>
`}
/>

<Playground
  title="Dismissible"
  desc="`onClose` shows a close button. Hide the alert in your state, and bring it back when the cause returns."
  scope={{ Alert, Button }}
  code={`
() => {
  const [open, setOpen] = React.useState(true)
  return open ? (
    <Alert type="info" light title="New version" onClose={() => setOpen(false)}>
      Reload the page to get the latest changes.
    </Alert>
  ) : (
    <Button auto scale={0.75} onClick={() => setOpen(true)}>Show the alert again</Button>
  )
}
`}
/>

<Playground
  title="With an icon and an action"
  desc="Put an `icon` before the text, and any element, such as a button, after it."
  scope={{ Alert, Button, useTheme }}
  code={`
() => {
  const theme = useTheme()
  const icon = (
    <svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
      <path d="M12 9v4M12 17h.01M10.3 3.9 1.8 18a2 2 0 0 0 1.7 3h17a2 2 0 0 0 1.7-3L13.7 3.9a2 2 0 0 0-3.4 0Z" />
    </svg>
  )
  return (
    <Alert type="warning" light icon={icon} title="Unsaved changes">
      <div style={{ display: 'flex', alignItems: 'center', gap: 12, flexWrap: 'wrap' }}>
        <span>Leave now and the last 4 edits are lost.</span>
        <Button auto scale={0.6} type="warning">Save draft</Button>
      </div>
    </Alert>
  )
}
`}
/>

<Attributes edit="/content/docs/components/alert.mdx">
<Attributes.Title>Alert.Props</Attributes.Title>

| Attribute      | Description                                   | Type                                                                          | Accepted values | Default   |
| -------------- | --------------------------------------------- | ----------------------------------------------------------------------------- | --------------- | --------- |
| **type**       | color of the alert                            | `'default' \| 'primary' \| 'secondary' \| 'success' \| 'warning' \| 'error' \| 'info'` | -               | `default` |
| **title**      | bold first line                               | `ReactNode`                                                                   | -               | -         |
| **icon**       | element before the text                       | `ReactNode`                                                                   | -               | -         |
| **filled**     | solid color                                   | `boolean`                                                                     | -               | `false`   |
| **light**      | tinted background                             | `boolean`                                                                     | -               | `false`   |
| **subtle**     | text only, no border                          | `boolean`                                                                     | -               | `false`   |
| **onClose**    | shows a close button and calls it on click    | `() => void`                                                                  | -               | -         |
| **closeLabel** | accessible name of the close button           | `string`                                                                      | -               | `Close`   |
| **role**       | defaults to `alert` for errors and warnings, `status` otherwise | `string`                                                    | -               | -         |
| ...            | native props                                  | `HTMLAttributes`                                                              | -               | -         |

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Avatar, Grid, Text, Tag, Card } from 'core'

export const meta = {
  title: 'Avatar',
  description:
    'Avatars represent a user or a team. Stacked avatars represent a group of people.',
  sidebar: 'components',
  group: 'Components',
  index: 1
}

## Avatar

Avatars represent a user or a team. Stacked avatars represent a group of people.

<Playground
  desc="The `Avatar` contains circle and square."
  scope={{ Avatar, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Avatar
      src="https://i.pravatar.cc/150?img=60"
      isSquare
      width={1.5}
      height={1.5}
    />
  </Grid>
  <Grid>
    <Avatar text="Bill" isSquare width={1.5} height={1.5} />
  </Grid>
  <Grid>
    <Avatar
      src="https://i.pravatar.cc/150?img=30"
      isSquare
      width={1.5}
      height={1.5}
    />
  </Grid>
  <Grid>
    <Avatar text="Max" isSquare width={1.5} height={1.5} />
  </Grid>
  <Grid>
    <Avatar
      src="https://i.pravatar.cc/150?img=20"
      isSquare
      width={1.5}
      height={1.5}
    />
  </Grid>
  <Grid>
    <Avatar text="Jane" isSquare width={1.5} height={1.5} />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Text"
  desc="Display text in the avatar box."
  scope={{ Avatar, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Avatar text="BA" width={1.5} height={1.5} />
  </Grid>
  <Grid>
    <Avatar text="ES" width={1.5} height={1.5} />
  </Grid>
  <Grid>
    <Avatar text="MB" width={1.5} height={1.5} />
  </Grid>
  <Grid>
    <Avatar text="WL" width={1.5} height={1.5} />
  </Grid>
  <Grid>
    <Avatar text="ML" width={1.5} height={1.5} />
  </Grid>
  <Grid>
    <Avatar text="TR" width={1.5} height={1.5} />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Group"
  desc="Multiple avatars can overlap and stack together."
  scope={{ Avatar, Grid }}
  code={`
<Grid.Container gap={2} direction="column">
  <Grid>
    <Avatar.Group>
      <Avatar
        src="https://i.pravatar.cc/150?img=60"
        width={1.5}
        height={1.5}
        stacked
      />
      <Avatar
        src="https://i.pravatar.cc/150?img=30"
        width={1.5}
        height={1.5}
        stacked
      />
      <Avatar
        src="https://i.pravatar.cc/150?img=20"
        width={1.5}
        height={1.5}
        stacked
      />
      <Avatar
        src="https://i.pravatar.cc/150?img=10"
        width={1.5}
        height={1.5}
        stacked
      />
    </Avatar.Group>
  </Grid>
  <Grid>
    <Avatar.Group count={6}>
      <Avatar
        src="https://i.pravatar.cc/150?img=60"
        width={1.5}
        height={1.5}
        stacked
      />
      <Avatar text="C" width={1.5} height={1.5} stacked />
      <Avatar text="Mag" width={1.5} height={1.5} stacked />
    </Avatar.Group>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Team members"
  desc="Pair each `Avatar` with a name and a role, so a list of people reads in one pass."
  scope={{ Avatar, Card, Text, Tag }}
  code={`
<Card bordered width="100%">
  {[
    ['AL', 'Ada Lovelace', 'Owner'],
    ['GH', 'Grace Hopper', 'Editor'],
    ['LT', 'Linus Torvalds', 'Viewer']
  ].map(([text, name, role]) => (
    <div key={name} style={{ display: 'flex', alignItems: 'center', gap: 12, padding: '6px 0' }}>
      <Avatar text={text} />
      <Text b style={{ flex: 1 }}>{name}</Text>
      <Tag>{role}</Tag>
    </div>
  ))}
</Card>
`}
/>

<Attributes edit="/content/docs/components/avatar.mdx">
<Attributes.Title>Avatar.Props</Attributes.Title>

| Attribute    | Description                        | Type                | Accepted values                          | Default |
| ------------ | ---------------------------------- | ------------------- | ---------------------------------------- | ------- |
| **src**      | image src                          | `string`            | -                                        | -       |
| **stacked**  | stacked display group              | `boolean`           | -                                        | `false` |
| **text**     | display text when image is missing | `string`            | -                                        | -       |
| **isSquare** | avatar shape                       | `boolean`           | -                                        | `false` |
| ...          | native props                       | `ImgHTMLAttributes` | `'alt', 'crossOrigin', 'className', ...` | -       |

<Attributes.Title>Avatar.Group.Props</Attributes.Title>

| Attribute | Description        | Type             | Accepted values                  | Default |
| --------- | ------------------ | ---------------- | -------------------------------- | ------- |
| **count** | show total members | `number`         | -                                | -       |
| ...       | native props       | `HTMLAttributes` | `'id', 'name', 'className', ...` | -       |

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Badge, Grid, Avatar, Button, Link, useTheme } from 'core'

export const meta = {
  title: 'Badge',
  description: 'Display an indicator that requires attention.',
  sidebar: 'components',
  group: 'Components',
  index: 2
}

## Badge

Display an indicator that requires attention.

<Playground
  scope={{ Badge, Grid }}
  desc="Show number or text."
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Badge>Default</Badge>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Type"
  desc="Express state in different colors."
  scope={{ Badge, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Badge>Default</Badge>
  </Grid>
  <Grid>
    <Badge type="primary">Primary</Badge>
  </Grid>
  <Grid>
    <Badge type="secondary">Secondary</Badge>
  </Grid>
  <Grid>
    <Badge type="success">Success</Badge>
  </Grid>
  <Grid>
    <Badge type="warning">Warning</Badge>
  </Grid>
  <Grid>
    <Badge type="error">Error</Badge>
  </Grid>
  <Grid>
    <Badge type="info">Info</Badge>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Custom color"
  desc={
    <>
      For more colors, please refer to the{' '}
      <Link color href="/docs/guide/default-theme#colors">
        color section
      </Link>
      .
    </>
  }
  scope={{ Grid, Badge, useTheme }}
  code={`
() => {
  const theme = useTheme()
  return (
    <Grid.Container gap={2}>
      <Grid>
        <Badge style={{ backgroundColor: theme.palette.successDark }}>
          Success Light
        </Badge>
      </Grid>
      <Grid>
        <Badge style={{ backgroundColor: theme.palette.alert }}>Alert</Badge>
      </Grid>
      <Grid>
        <Badge style={{ backgroundColor: theme.palette.purple }}>Purple</Badge>
      </Grid>
      <Grid>
        <Badge style={{ backgroundColor: theme.palette.secondary }}>Violet</Badge>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Playground
  title="Pulse"
  desc="Use `pulse` for a live status. The ring follows the badge color and stops when the user prefers reduced motion."
  scope={{ Grid, Badge }}
  code={`
<Grid.Container gap={2} alignItems="center">
  <Grid>
    <Badge dot pulse type="success" />
  </Grid>
  <Grid>
    <Badge pulse type="error">
      Recording
    </Badge>
  </Grid>
  <Grid>
    <Badge pulse type="primary">
      Live
    </Badge>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Anchor"
  desc="Fix the `Badge` in the designated position."
  scope={{ Grid, Badge, Avatar, Button, Link }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Badge.Anchor>
      <Badge scale={0.5}>10</Badge>
      <Avatar src="https://i.pravatar.cc/150?img=60" />
    </Badge.Anchor>
  </Grid>
  <Grid>
    <Badge.Anchor placement="bottomRight">
      <Badge scale={0.5} type="success">
        10
      </Badge>
      <Avatar scale={1.5} isSquare src="https://i.pravatar.cc/150?img=30" />
    </Badge.Anchor>
  </Grid>
  <Grid>
    <Badge.Anchor>
      <Badge scale={0.5} type="warning">
        99+
      </Badge>
      <Button scale={0.5} auto>
        Action
      </Button>
    </Badge.Anchor>
  </Grid>
  <Grid>
    <Badge.Anchor>
      <Badge scale={0.5} type="error" dot />
      <Link target="_blank" href="https://github.com/bolio-ui/bolio-ui/">
        Bolio UI
      </Link>
    </Badge.Anchor>
  </Grid>
  <Grid>
    <Badge.Anchor>
      <Badge type="error" dot padding="5px" />
      <Link target="_blank" href="https://github.com/bolio-ui/bolio-ui/">
        Share Link
      </Link>
    </Badge.Anchor>
  </Grid>
</Grid.Container>
`}
/>

<Attributes edit="/content/docs/components/badge.mdx">
<Attributes.Title>Badge.Props</Attributes.Title>

| Attribute | Description                 | Type             | Accepted values                 | Default   |
| --------- | --------------------------- | ---------------- | ------------------------------- | --------- |
| **type**  | badge type                       | `BadgeTypes`      | [BadgeTypes](#badgetypes)       | `default` |
| **dot**   | show dot and ignore content      | `boolean`         | -                                | `false`   |
| **pulse** | animated ring for live status    | `boolean`         | -                                | `false`   |
| **ghost** | outline variant: opposite color  | `boolean`         | -                                | `false`   |
| **light** | light variant: tinted background | `boolean`         | -                                | `false`   |
| **subtle**| subtle variant: no background    | `boolean`         | -                                | `false`   |
| ...       | native props                     | `HTMLAttributes`  | `'alt', 'id', 'className', ...` | -         |

<Attributes.Title>Badge.Anchor.Props</Attributes.Title>

| Attribute     | Description            | Type              | Accepted values                     | Default    |
| ------------- | ---------------------- | ----------------- | ----------------------------------- | ---------- |
| **placement** | fixe position of Badge | `AnchorPlacement` | [AnchorPlacement](#anchorplacement) | `topRight` |
| ...           | native props           | `HTMLAttributes`  | `'alt', 'id', 'className', ...`     | -          |

<Attributes.Title>BadgeTypes</Attributes.Title>

```ts
type BadgeTypes =
  | 'default'
  | 'primary'
  | 'secondary'
  | 'success'
  | 'warning'
  | 'error'
  | 'info'
```

<Attributes.Title>AnchorPlacement</Attributes.Title>

```ts
type AnchorPlacement = 'topLeft' | 'topRight' | 'bottomLeft' | 'bottomRight'
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Breadcrumbs, Grid } from 'core'
import { useRouter } from 'next/navigation'
import { Home, Settings } from '@bolio-ui/icons'

export const meta = {
  title: 'Breadcrumbs',
  description: 'Show where users are in the application.',
  sidebar: 'components',
  group: 'Components',
  index: 3
}

## Breadcrumbs

Show where users are in the application.

<Playground
  scope={{ Breadcrumbs, Grid }}
  desc="The basic `Breadcrumbs` usage."
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Breadcrumbs>
      <Breadcrumbs.Item>Home</Breadcrumbs.Item>
      <Breadcrumbs.Item href="">Settings</Breadcrumbs.Item>
      <Breadcrumbs.Item>General</Breadcrumbs.Item>
    </Breadcrumbs>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Separator"
  desc="Custom separator in characters."
  scope={{ Breadcrumbs, Grid }}
  code={`
<Grid.Container gap={2} direction="column">
  <Grid>
    <Breadcrumbs separator="-">
      <Breadcrumbs.Item>Home</Breadcrumbs.Item>
      <Breadcrumbs.Item href="">Categories</Breadcrumbs.Item>
      <Breadcrumbs.Item>Add</Breadcrumbs.Item>
    </Breadcrumbs>
  </Grid>
  <Grid>
    <Breadcrumbs separator=">">
      <Breadcrumbs.Item>Home</Breadcrumbs.Item>
      <Breadcrumbs.Separator>:</Breadcrumbs.Separator>
      <Breadcrumbs.Item href="">Pages</Breadcrumbs.Item>
      <Breadcrumbs.Item href="">Default</Breadcrumbs.Item>
      <Breadcrumbs.Item>Index</Breadcrumbs.Item>
    </Breadcrumbs>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Icons"
  desc="Show more information with icons."
  scope={{ Breadcrumbs, Home, Settings, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Breadcrumbs>
      <Breadcrumbs.Item>
        <Home />
      </Breadcrumbs.Item>
      <Breadcrumbs.Item href="">
        <Settings /> Settings
      </Breadcrumbs.Item>
      <Breadcrumbs.Item>General</Breadcrumbs.Item>
    </Breadcrumbs>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="With NextJS"
  desc="Example for use with `next.js`: keep the `href` and navigate with the router on click."
  scope={{ Breadcrumbs, Grid, useRouter }}
  code={`
() => {
  const router = useRouter()
  const go = (url) => (event) => {
    event.preventDefault()
    router.push(url)
  }
  return (
    <Grid.Container gap={2}>
      <Grid>
        <Breadcrumbs>
          <Breadcrumbs.Item href="/" onClick={go('/')}>Home</Breadcrumbs.Item>
          <Breadcrumbs.Item href="/settings" onClick={go('/settings')}>Settings</Breadcrumbs.Item>
          <Breadcrumbs.Item>General</Breadcrumbs.Item>
        </Breadcrumbs>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Attributes edit="/content/docs/components/breadcrumbs.mdx">
<Attributes.Title>Breadcrumbs.Props</Attributes.Title>

| Attribute     | Description      | Type             | Accepted values          | Default |
| ------------- | ---------------- | ---------------- | ------------------------ | ------- |
| **separator** | separator string | `string`         | -                        | `/`     |
| ...           | native props     | `HTMLAttributes` | `'id', 'className', ...` | -       |

<Attributes.Title>Breadcrumbs.Item.Props</Attributes.Title>

| Attribute    | Description        | Type                          | Accepted values          | Default |
| ------------ | ------------------ | ----------------------------- | ------------------------ | ------- |
| **href**     | link address       | `string`                      | -                        | -       |
| **nextLink** | render as a link even without `href` | `boolean`                     | -                        | `false` |
| **onClick**  | click event        | `(event: MouseEvent) => void` | -                        | -       |
| ...          | native props       | `AnchorHTMLAttributes`        | `'id', 'className', ...` | -       |

<Attributes.Title>Breadcrumbs.Separator.Props</Attributes.Title>

| Attribute | Description  | Type             | Accepted values          | Default |
| --------- | ------------ | ---------------- | ------------------------ | ------- |
| ...       | native props | `HTMLAttributes` | `'id', 'className', ...` | -       |

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { ButtonDropdown, Grid } from 'core'
import { Playground, Attributes } from 'src/components'
import { Plus, Copy, FileText } from '@bolio-ui/icons'

export const meta = {
  title: 'Button Dropdown',
  description: 'Display related but alternate actions for a button.',
  sidebar: 'components',
  group: 'Components',
  index: 5
}

## Button Dropdown

Display related but alternate actions for a button.

<Playground
  title="General"
  desc="The basic `ButtonDropdown` usage."
  scope={{ ButtonDropdown, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <ButtonDropdown>
      <ButtonDropdown.Item main>Default Button</ButtonDropdown.Item>
      <ButtonDropdown.Item>Secondary Button</ButtonDropdown.Item>
      <ButtonDropdown.Item>Tertiary Button</ButtonDropdown.Item>
    </ButtonDropdown>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Loading"
  desc="Show friendly load indicator."
  scope={{ ButtonDropdown, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <ButtonDropdown loading>
      <ButtonDropdown.Item main>Default Button</ButtonDropdown.Item>
      <ButtonDropdown.Item>Secondary Button</ButtonDropdown.Item>
      <ButtonDropdown.Item>Tertiary Button</ButtonDropdown.Item>
    </ButtonDropdown>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Disabled"
  desc="Disable all buttons."
  scope={{ ButtonDropdown, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <ButtonDropdown disabled>
      <ButtonDropdown.Item main>Default Button</ButtonDropdown.Item>
      <ButtonDropdown.Item>Secondary Button</ButtonDropdown.Item>
      <ButtonDropdown.Item>Tertiary Button</ButtonDropdown.Item>
    </ButtonDropdown>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Types"
  desc="You can change the color of the `ButtonDropdown` with the property `type`."
  scope={{ ButtonDropdown, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid xs={12} sm={6} md={4}>
    <ButtonDropdown type="primary">
      <ButtonDropdown.Item main>Primary Button</ButtonDropdown.Item>
      <ButtonDropdown.Item>Secondary Button</ButtonDropdown.Item>
      <ButtonDropdown.Item>Tertiary Button</ButtonDropdown.Item>
    </ButtonDropdown>
  </Grid>
  <Grid xs={12} sm={6} md={4}>
    <ButtonDropdown type="secondary">
      <ButtonDropdown.Item main>Secondary Button</ButtonDropdown.Item>
      <ButtonDropdown.Item>Secondary Button</ButtonDropdown.Item>
      <ButtonDropdown.Item>Tertiary Button</ButtonDropdown.Item>
    </ButtonDropdown>
  </Grid>
  <Grid xs={12} sm={6} md={4}>
    <ButtonDropdown type="success">
      <ButtonDropdown.Item main>Success Button</ButtonDropdown.Item>
      <ButtonDropdown.Item>Secondary Button</ButtonDropdown.Item>
      <ButtonDropdown.Item>Tertiary Button</ButtonDropdown.Item>
    </ButtonDropdown>
  </Grid>
  <Grid xs={12} sm={6} md={4}>
    <ButtonDropdown type="warning">
      <ButtonDropdown.Item main>Warning Button</ButtonDropdown.Item>
      <ButtonDropdown.Item>Secondary Button</ButtonDropdown.Item>
      <ButtonDropdown.Item>Tertiary Button</ButtonDropdown.Item>
    </ButtonDropdown>
  </Grid>
  <Grid xs={12} sm={6} md={4}>
    <ButtonDropdown type="error">
      <ButtonDropdown.Item main>Error Button</ButtonDropdown.Item>
      <ButtonDropdown.Item>Secondary Button</ButtonDropdown.Item>
      <ButtonDropdown.Item>Tertiary Button</ButtonDropdown.Item>
    </ButtonDropdown>
  </Grid>
  <Grid xs={12} sm={6} md={4}>
    <ButtonDropdown type="info">
      <ButtonDropdown.Item main>Info Button</ButtonDropdown.Item>
      <ButtonDropdown.Item>Secondary Button</ButtonDropdown.Item>
      <ButtonDropdown.Item>Tertiary Button</ButtonDropdown.Item>
    </ButtonDropdown>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Multiple Type"
  desc="Specify the status of a button individually."
  scope={{ ButtonDropdown, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <ButtonDropdown scale={2 / 3} auto>
      <ButtonDropdown.Item main>Check</ButtonDropdown.Item>
      <ButtonDropdown.Item>Block</ButtonDropdown.Item>
      <ButtonDropdown.Item>Lock</ButtonDropdown.Item>
      <ButtonDropdown.Item type="error">Destroy</ButtonDropdown.Item>
    </ButtonDropdown>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Custom Right Icon"
  desc="The `color` and `size` of the right icon will be set automatically."
  scope={{ ButtonDropdown, Grid, Plus }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <ButtonDropdown scale={2 / 3} auto icon={<Plus />}>
      <ButtonDropdown.Item main>Check User</ButtonDropdown.Item>
      <ButtonDropdown.Item>Block User</ButtonDropdown.Item>
      <ButtonDropdown.Item>Lock User</ButtonDropdown.Item>
      <ButtonDropdown.Item type="error">Destroy User</ButtonDropdown.Item>
    </ButtonDropdown>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Item Icons"
  desc="Use `icon` on an item to show an icon before its label. Items in the list align to the left and the list grows to fit them."
  scope={{ ButtonDropdown, Grid, Copy, FileText }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <ButtonDropdown scale={2 / 3} auto>
      <ButtonDropdown.Item main icon={<Copy />}>Copy Markdown</ButtonDropdown.Item>
      <ButtonDropdown.Item icon={<FileText />}>View as Markdown</ButtonDropdown.Item>
    </ButtonDropdown>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Alignment"
  desc="Use `align` to place the label of the main button at the `start`, `center` or `end`. It shows when the button is wider than its text."
  scope={{ ButtonDropdown, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid xs={24} sm={8}>
    <ButtonDropdown align="start" style={{ width: '100%' }}>
      <ButtonDropdown.Item main>Start</ButtonDropdown.Item>
      <ButtonDropdown.Item>Secondary Button</ButtonDropdown.Item>
    </ButtonDropdown>
  </Grid>
  <Grid xs={24} sm={8}>
    <ButtonDropdown align="center" style={{ width: '100%' }}>
      <ButtonDropdown.Item main>Center</ButtonDropdown.Item>
      <ButtonDropdown.Item>Secondary Button</ButtonDropdown.Item>
    </ButtonDropdown>
  </Grid>
  <Grid xs={24} sm={8}>
    <ButtonDropdown align="end" style={{ width: '100%' }}>
      <ButtonDropdown.Item main>End</ButtonDropdown.Item>
      <ButtonDropdown.Item>Secondary Button</ButtonDropdown.Item>
    </ButtonDropdown>
  </Grid>
</Grid.Container>
`}
/>

<Attributes edit="/content/docs/components/button-dropdown.mdx">
<Attributes.Title>ButtonDropdown.Props</Attributes.Title>

| Attribute    | Description                 | Type                           | Accepted values                             | Default              |
| ------------ | --------------------------- | ------------------------------ | ------------------------------------------- | -------------------- |
| **type**     | button type                 | `ButtonDropdownTypes`          | [ButtonDropdownTypes](#buttondropdowntypes) | `default`            |
| **loading**  | display loading indicator   | `boolean`                      | -                                           | `false`              |
| **auto**     | autoscale width             | `boolean`                      | -                                           | `false`              |
| **align**    | main button label alignment | `'start' \| 'center' \| 'end'` | -                                           | `center`             |
| **disabled** | disable button              | `boolean`                      | -                                           | `false`              |
| **icon**     | custom right icon           | `ReactNode`                    | -                                           | `ButtonDropdownIcon` |
| ...          | native props                | `HTMLAttributes`               | `'autoFocus', 'name', 'className', ...`     | -                    |

<Attributes.Title>ButtonDropdown.Item.Props</Attributes.Title>

| Attribute   | Description           | Type                   | Accepted values                             | Default   |
| ----------- | --------------------- | ---------------------- | ------------------------------------------- | --------- |
| **type**    | button type           | `ButtonDropdownTypes`  | [ButtonDropdownTypes](#buttondropdowntypes) | `default` |
| **main**    | the main action       | `boolean`              | -                                           | `false`   |
| **icon**    | icon before the label | `ReactNode`            | -                                           | -         |
| **onClick** | event handler         | `MouseEventHandler`    | -                                           | -         |
| ...         | native props          | `ButtonHTMLAttributes` | `'id', 'name', 'className', ...`            | -         |

<Attributes.Title>ButtonDropdownTypes</Attributes.Title>

```ts
type ButtonDropdownTypes =
  | 'default'
  | 'primary'
  | 'secondary'
  | 'success'
  | 'warning'
  | 'error'
  | 'info'
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Button, Grid, ButtonGroup } from 'core'
import { Bold, Italic, Underline } from '@bolio-ui/icons'

export const meta = {
  title: 'Button Group',
  description: 'A set of related buttons.',
  sidebar: 'components',
  group: 'Components',
  index: 6
}

## Button Group

A set of related buttons.

<Playground
  title="General"
  desc="The basic `ButtonGroup` usage."
  scope={{ Button, ButtonGroup, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <ButtonGroup>
      <Button>One</Button>
      <Button>Two</Button>
      <Button>Three</Button>
    </ButtonGroup>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Variant"
  desc="set the type or styles of all buttons in the group."
  scope={{ Button, ButtonGroup, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <ButtonGroup type="success">
      <Button>One</Button>
      <Button>Two</Button>
      <Button>Three</Button>
    </ButtonGroup>
  </Grid>
  <Grid>
    <ButtonGroup type="abort">
      <Button>Action1</Button>
      <Button>Action2</Button>
    </ButtonGroup>
  </Grid>
  <Grid>
    <ButtonGroup type="warning" ghost>
      <Button>Action1</Button>
      <Button>Action2</Button>
    </ButtonGroup>
  </Grid>
  <Grid>
    <ButtonGroup type="success-light">
      <Button>One</Button>
      <Button>Two</Button>
      <Button>Three</Button>
    </ButtonGroup>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Sizes"
  desc="Change the size of the entire group button including the property `type`."
  scope={{ Button, ButtonGroup, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <ButtonGroup scale={2 / 3}>
      <Button scale={2 / 3}>One</Button>
      <Button scale={2 / 3}>Two</Button>
      <Button scale={2 / 3}>Three</Button>
    </ButtonGroup>
  </Grid>
  <Grid>
    <ButtonGroup scale={1 / 3}>
      <Button scale={1 / 3}>Action1</Button>
      <Button scale={1 / 3}>Action2</Button>
    </ButtonGroup>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Vertical"
  desc="You can use the `vertical` property to sort the buttons vertically."
  scope={{ Button, ButtonGroup, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <ButtonGroup vertical>
      <Button>One</Button>
      <Button>Two</Button>
      <Button>Three</Button>
      <Button>Four</Button>
    </ButtonGroup>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Disabled"
  desc="disable all buttons in the group."
  scope={{ Button, ButtonGroup, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <ButtonGroup scale={0.5} disabled>
      <Button scale={0.5}>One</Button>
      <Button scale={0.5}>Two</Button>
      <Button scale={0.5}>Three</Button>
    </ButtonGroup>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Editor toolbar"
  desc="Icon only buttons need a name for screen readers, so give each one an `aria-label`."
  scope={{ Button, ButtonGroup, Bold, Italic, Underline }}
  code={`
() => {
  const [on, setOn] = React.useState({ bold: true, italic: false, underline: false })
  const toggle = (key) => () => setOn((last) => ({ ...last, [key]: !last[key] }))
  const style = (key) => (on[key] ? 'primary' : 'default')
  return (
    <ButtonGroup>
      <Button icon={<Bold />} aria-label="Bold" aria-pressed={on.bold} type={style('bold')} onClick={toggle('bold')} />
      <Button icon={<Italic />} aria-label="Italic" aria-pressed={on.italic} type={style('italic')} onClick={toggle('italic')} />
      <Button icon={<Underline />} aria-label="Underline" aria-pressed={on.underline} type={style('underline')} onClick={toggle('underline')} />
    </ButtonGroup>
  )
}
`}
/>

<Attributes edit="/content/docs/components/button-group.mdx">
<Attributes.Title>ButtonGroup.Props</Attributes.Title>

| Attribute    | Description                 | Type                   | Accepted values             | Default   |
| ------------ | --------------------------- | ---------------------- | --------------------------- | --------- |
| **type**     | button type                 | `ButtonTypes`          | [ButtonTypes](#buttontypes) | `default` |
| **ghost**    | the opposite color          | `boolean`              | -                           | `false`   |
| **vertical** | show all buttons vertically | `boolean`              | -                           | `false`   |
| **disabled** | disable all buttons         | `boolean`              | -                           | `false`   |
| ...          | native props                | `ButtonHTMLAttributes` | `'id', 'className', ...`    | -         |

<Attributes.Title>ButtonTypes</Attributes.Title>

```ts
type ButtonTypes =
  | 'default'
  | 'secondary'
  | 'success'
  | 'warning'
  | 'error'
  | 'abort'
  | 'secondary-light'
  | 'success-light'
  | 'warning-light'
  | 'error-light'
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Button, Grid, Row, Code } from 'core'
import { Zap, ZapOff, AlertCircle, XSquare } from '@bolio-ui/icons'

export const meta = {
  title: 'Button',
  description: 'A set of related buttons.',
  sidebar: 'components',
  group: 'Components',
  index: 4
}

## Button

Used to trigger an operation.

<Playground
  title="General"
  desc="The basic `Button` contains an animation effect."
  scope={{ Button, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Button>Button</Button>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Loading"
  desc="Show running status."
  scope={{ Button, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Button loading>Button</Button>
  </Grid>
  <Grid>
    <Button loading scale={0.75}>
      Button
    </Button>
  </Grid>
  <Grid>
    <Button loading auto type="primary" scale={2 / 3}>
      Button
    </Button>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Disabled"
  desc="Do not respond to any action."
  scope={{ Button, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Button disabled>Button</Button>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Shadow"
  desc="The shadow highlights the level of the button."
  scope={{ Button, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Button shadow type="secondary">
      Button Shadow
    </Button>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Type Colors"
  desc="You can change the color of the `Button` with the property `type`."
  scope={{ Button, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Button auto type="primary">
      Primary
    </Button>
  </Grid>
  <Grid>
    <Button auto type="secondary">
      Secondary
    </Button>
  </Grid>
  <Grid>
    <Button auto type="success">
      Success
    </Button>
  </Grid>
  <Grid>
    <Button auto type="warning">
      Warning
    </Button>
  </Grid>
  <Grid>
    <Button auto type="error">
      Error
    </Button>
  </Grid>
  <Grid>
    <Button auto type="info">
      Info
    </Button>
  </Grid>
  <Grid>
    <Button auto type="abort">
      Abort
    </Button>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Lighted"
  desc="Different state."
  scope={{ Button, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Button auto type="primary-light">
      Primary Light
    </Button>
  </Grid>
  <Grid>
    <Button auto type="secondary-light">
      Secondary Light
    </Button>
  </Grid>
  <Grid>
    <Button auto type="success-light">
      Success Light
    </Button>
  </Grid>
  <Grid>
    <Button auto type="warning-light">
      Warning Light
    </Button>
  </Grid>
  <Grid>
    <Button auto type="error-light">
      Error Light
    </Button>
  </Grid>
  <Grid>
    <Button auto type="info-light">
      Info Light
    </Button>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Ghost"
  desc="The opposite color."
  scope={{ Button, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Button type="primary" ghost auto>
      Primary
    </Button>
  </Grid>
  <Grid>
    <Button type="secondary" ghost auto>
      Secondary
    </Button>
  </Grid>
  <Grid>
    <Button type="success" ghost auto>
      Success
    </Button>
  </Grid>
  <Grid>
    <Button type="warning" ghost auto>
      Warning
    </Button>
  </Grid>
  <Grid>
    <Button type="error" ghost auto>
      Error
    </Button>
  </Grid>
  <Grid>
    <Button type="info" ghost auto>
      Info
    </Button>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Subtle"
  desc="No background until you look at the color of the text, the quietest of the four variants."
  scope={{ Button, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Button type="primary" subtle auto>
      Primary
    </Button>
  </Grid>
  <Grid>
    <Button type="secondary" subtle auto>
      Secondary
    </Button>
  </Grid>
  <Grid>
    <Button type="success" subtle auto>
      Success
    </Button>
  </Grid>
  <Grid>
    <Button type="warning" subtle auto>
      Warning
    </Button>
  </Grid>
  <Grid>
    <Button type="error" subtle auto>
      Error
    </Button>
  </Grid>
  <Grid>
    <Button type="info" subtle auto>
      Info
    </Button>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Spotlight"
  desc="The `spotlight` prop adds a glow that follows the pointer on hover."
  scope={{ Button, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Button spotlight auto>
      Default
    </Button>
  </Grid>
  <Grid>
    <Button spotlight type="primary" auto>
      Primary
    </Button>
  </Grid>
  <Grid>
    <Button spotlight ghost type="secondary" auto>
      Ghost
    </Button>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Rounded"
  desc="You can completely round the corners of any type of `Button` with the `rounded` property."
  scope={{ Button, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Button type="primary" rounded auto>
      Primary
    </Button>
  </Grid>
  <Grid>
    <Button type="secondary" rounded auto>
      Secondary
    </Button>
  </Grid>
  <Grid>
    <Button type="success" rounded auto>
      Success
    </Button>
  </Grid>
  <Grid>
    <Button type="warning" rounded auto>
      Warning
    </Button>
  </Grid>
  <Grid>
    <Button type="error" rounded auto>
      Error
    </Button>
  </Grid>
  <Grid>
    <Button type="info" rounded auto>
      Info
    </Button>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Scale"
  desc="Buttons of different sizes."
  scope={{ Button, Grid, Row }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Button auto scale={0.25}>
      0.25
    </Button>
  </Grid>
  <Grid>
    <Button auto scale={0.35}>
      0.35
    </Button>
  </Grid>
  <Grid>
    <Button auto scale={1 / 2}>
      1 / 2
    </Button>
  </Grid>
  <Grid>
    <Button auto scale={0.75}>
      0.75
    </Button>
  </Grid>
  <Grid>
    <Button auto padding={0}>
      NoPadding
    </Button>
  </Grid>
  <Grid>
    <Button auto font={0.25}>
      Small Font
    </Button>
  </Grid>
  <Grid>
    <Button auto pl={0} ml="25px">
      Offset
    </Button>
  </Grid>
  <Grid xs={12}>
    <Button width="100%">Full Width</Button>
  </Grid>
  <Grid xs={12}>
    <Row>
      <Button auto width="30%" mx="5px">
        proportion
      </Button>
      <Button auto width="30%" mx="5px">
        proportion
      </Button>
      <Button auto width="30%" mx="5px">
        proportion
      </Button>
    </Row>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="With Icons"
  desc="The `color` and `size` of the icon will be set automatically."
  scope={{ Button, Grid, Zap, ZapOff, AlertCircle, XSquare }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Button iconRight={<Zap />} auto scale={2 / 3} />
  </Grid>
  <Grid>
    <Button iconRight={<ZapOff />} auto scale={2 / 3} px={0.6} />
  </Grid>
  <Grid>
    <Button icon={<AlertCircle />} auto>
      Button
    </Button>
  </Grid>
  <Grid>
    <Button iconRight={<AlertCircle />} type="success" scale={0.85}>
      Button
    </Button>
  </Grid>
  <Grid>
    <Button icon={<AlertCircle />} type="warning" scale={0.85}>
      Button
    </Button>
  </Grid>
  <Grid>
    <Button icon={<AlertCircle />} type="secondary">
      Button
    </Button>
  </Grid>
  <Grid>
    <Button icon={<XSquare />} type="error" ghost>
      Remove Button
    </Button>
  </Grid>
  <Grid>
    <Button icon={<XSquare />} disabled>
      Remove Button
    </Button>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Save with feedback"
  desc="Show progress while the action runs and the result when it ends. The button is disabled after saving so it cannot run twice."
  scope={{ Button, Grid }}
  code={`
() => {
  const [state, setState] = React.useState('idle')
  const save = () => {
    setState('saving')
    setTimeout(() => setState('saved'), 1500)
  }
  return (
    <Grid.Container gap={2} alignItems="center">
      <Grid>
        <Button auto type="primary" loading={state === 'saving'} disabled={state === 'saved'} onClick={save}>
          {state === 'saved' ? 'Saved' : 'Save changes'}
        </Button>
      </Grid>
      <Grid>
        <Button auto onClick={() => setState('idle')}>Reset</Button>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Attributes edit="/content/docs/components/button.mdx">
<Attributes.Title>Button.Props</Attributes.Title>

| Attribute     | Description                               | Type                                            | Accepted values             | Default   |
| ------------- | ----------------------------------------- | ----------------------------------------------- | --------------------------- | --------- |
| **type**      | button type                               | `ButtonTypes`                                   | [ButtonTypes](#buttontypes) | `default` |
| **ghost**     | the opposite color                        | `boolean`                                       | -                           | `false`   |
| **subtle**    | no background, only the type's color      | `boolean`                                       | -                           | `false`   |
| **rounded**   | rounded button                            | `boolean`                                       | -                           | `false`   |
| **loading**   | display loading indicator                 | `boolean`                                       | -                           | `false`   |
| **shadow**    | display shadow                            | `boolean`                                       | -                           | `false`   |
| **auto**      | autoscale width                           | `boolean`                                       | -                           | `false`   |
| **effect**    | display animation                         | `boolean`                                       | -                           | `true`    |
| **spotlight** | glow that follows the pointer on hover    | `boolean`                                       | -                           | `false`   |
| **disabled**  | disable button                            | `boolean`                                       | -                           | `false`   |
| **onClick**   | click handler                             | `MouseEventHandler`                             | -                           | -         |
| **icon**      | show icon in button                       | `ReactNode`                                     | -                           | -         |
| **iconRight** | show icon on the other side of the button | `ReactNode`                                     | -                           | -         |
| **htmlType**  | native type of button element             | `ButtonHTMLAttributes.type`                     | -                           | `button`  |
| **ref**       | forwardRef                                | <Code>Ref&lt;HTMLButtonElement &#124; null&gt;</Code> | -                           | -         |
| ...           | native props                              | `ButtonHTMLAttributes`                          | `'id', 'className', ...`    | -         |

<Attributes.Title>ButtonTypes</Attributes.Title>

```ts
type ButtonTypes =
  | 'default'
  | 'primary'
  | 'secondary'
  | 'success'
  | 'warning'
  | 'error'
  | 'info'
  | 'abort'
  | 'primary-light'
  | 'secondary-light'
  | 'success-light'
  | 'warning-light'
  | 'error-light'
  | 'info-light'
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Calendar, Grid } from 'core'

export const meta = {
  title: 'Calendar',
  description: 'A month grid to pick a day with the mouse or the keyboard.',
  sidebar: 'components',
  group: 'Components',
  index: 43
}

## Calendar

A month grid to pick a day with the mouse or the keyboard. `DatePicker` uses it, and you can use it alone when the calendar should always be visible.

In Next.js 16 with `cacheComponents` on, wrap a `Calendar` that is always visible in `<Suspense>`. It reads today's date while it renders, and Next does not prerender that. A `DatePicker` does not need it, because its calendar opens on a click.

<Playground
  desc="Pass the selected day with `value` and listen to `onChange`."
  scope={{ Calendar, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Calendar value={new Date(2026, 0, 15)} />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Min and max"
  desc="Days outside the range are disabled and the keyboard does not go there."
  scope={{ Calendar, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Calendar
      value={new Date(2026, 0, 15)}
      min={new Date(2026, 0, 10)}
      max={new Date(2026, 0, 20)}
    />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Locale and first day of the week"
  desc="`locale` sets the names of the month and of the weekdays, and `weekStartsOn` the first column (0 is Sunday)."
  scope={{ Calendar, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Calendar value={new Date(2026, 0, 15)} locale="pt-BR" weekStartsOn={1} />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Multiple"
  desc="With `mode` set to `multiple` each click adds or removes a day, and `value` is an array. Use `maxSelected` to limit how many."
  scope={{ Calendar, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Calendar mode="multiple" defaultMonth={new Date(2026, 0, 1)} maxSelected={5} />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Range"
  desc="With `mode` set to `range` the first click sets the start and the second the end. `value` is `[start, end]`."
  scope={{ Calendar, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Calendar mode="range" defaultMonth={new Date(2026, 0, 1)} />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Disable dates"
  desc="`shouldDisableDate` receives each day and returns `true` to block it, like weekends or holidays."
  scope={{ Calendar, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Calendar defaultMonth={new Date(2026, 0, 1)} shouldDisableDate={(date) => date.getDay() === 0 || date.getDay() === 6} />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Outside days and week numbers"
  desc="`showOutsideDays` fills the grid with days of the neighbor months, and `showWeekNumbers` adds the ISO week of each row."
  scope={{ Calendar, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Calendar defaultMonth={new Date(2026, 0, 1)} weekStartsOn={1} showOutsideDays showWeekNumbers />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Several months"
  desc="`numberOfMonths` shows the months side by side. A range can cross from one to the next, and the days of the neighbor months are hidden."
  scope={{ Calendar, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Calendar mode="range" numberOfMonths={2} defaultMonth={new Date(2026, 0, 1)} />
  </Grid>
</Grid.Container>
`}
/>

<Attributes edit="/content/docs/components/calendar.mdx">
<Attributes.Title>Calendar.Props</Attributes.Title>

| Attribute             | Description                                               | Type                                        | Accepted values                 | Default          |
| --------------------- | --------------------------------------------------------- | ------------------------------------------- | ------------------------------- | ---------------- |
| **value**             | selected day, days or range, to control the component     | `Date` / `null`, `Date[]` or `[Date, Date]` | -                               | -                |
| **onChange**          | called with what the user picked, in the shape of `value` | `(value) => void`                           | -                               | -                |
| **min**               | first day that can be picked                              | `Date`                                      | -                               | -                |
| **max**               | last day that can be picked                               | `Date`                                      | -                               | -                |
| **locale**            | language of the month and weekday names                   | `string`                                    | any `Intl` locale               | `en-US`          |
| **weekStartsOn**      | first day of the week, 0 is Sunday                        | `number`                                    | `0` to `6`                      | `0`              |
| **mode**              | how many days can be picked                               | `string`                                    | `'single', 'multiple', 'range'` | `single`         |
| **maxSelected**       | most days in `multiple` mode                              | `number`                                    | -                               | -                |
| **shouldDisableDate** | disable the days where it returns `true`                  | `(date: Date) => boolean`                   | -                               | -                |
| **showOutsideDays**   | show days of the neighbor months                          | `boolean`                                   | -                               | `false`          |
| **numberOfMonths**    | months shown side by side; hides the neighbor days if more than one | `number`                          | -                               | `1`              |
| **showWeekNumbers**   | show the ISO week of each row                             | `boolean`                                   | -                               | `false`          |
| **month**             | visible month, to control it                              | `Date`                                      | -                               | -                |
| **defaultMonth**      | visible month at the start                                | `Date`                                      | -                               | the selected day |
| **onMonthChange**     | called with the first day of the new month                | `(month: Date) => void`                     | -                               | -                |
| **weekLabel**         | name of the week number column                            | `string`                                    | -                               | `Week`           |
| **autoFocus**         | move the focus to the day when it is shown                | `boolean`                                   | -                               | `false`          |
| **previousLabel**     | name of the previous month button                         | `string`                                    | -                               | `Previous month` |
| **nextLabel**         | name of the next month button                             | `string`                                    | -                               | `Next month`     |
| ...                   | native props                                              | `HTMLAttributes`                            | `'id', 'className', ...`        | -                |

<Attributes.Title>Ref</Attributes.Title>

The `ref` points at the root element.

<Attributes.Title>Accessibility</Attributes.Title>

The days are a `grid` named by the month, with a single tab stop on the focused day. The selected day has `aria-selected` and today has `aria-current="date"`.

| Key                       | Action                                          |
| ------------------------- | ----------------------------------------------- |
| Arrow keys                | Move by one day, or one week                    |
| Home and End              | Go to the first and to the last day of the week |
| Page Up and Page Down     | Go to the previous and to the next month        |
| Shift and Page Up or Down | Go to the previous and to the next year         |
| Enter and Space           | Pick the day                                    |

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Capacity, Grid, Card, Text, useTheme } from 'core'

export const meta = {
  title: 'Capacity',
  description: 'Display an capacity indicator.',
  sidebar: 'components',
  group: 'Components',
  index: 7
}

## Capacity

Display an capacity indicator.

<Playground
  title="General"
  desc="The basic `Capacity` usage."
  scope={{ Capacity, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid xs={4} md={4}>
    <Capacity value={15} width="200px" />
  </Grid>
  <Grid xs={4} md={4}>
    <Capacity value={45} width="200px" />
  </Grid>
  <Grid xs={4} md={4}>
    <Capacity value={95} width="200px" />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Fixed Color"
  desc="Specify a color to override the default."
  scope={{ Capacity, Grid, useTheme }}
  code={`
() => {
  const theme = useTheme()
  return (
    <Grid.Container gap={2}>
      <Grid xs={6} md={4}>
        <Capacity value={75} color={theme.palette.foreground} width="200px" />
      </Grid>
      <Grid xs={6} md={4}>
        <Capacity value={75} color={theme.palette.primary} width="200px" />
      </Grid>
      <Grid xs={6} md={4}> 
        <Capacity value={75} color={theme.palette.secondary} width="200px" />
      </Grid>
      <Grid xs={6} md={4}>
        <Capacity value={75} color={theme.palette.success} width="200px" />
      </Grid>
      <Grid xs={6} md={4}>
        <Capacity value={75} color={theme.palette.warning} width="200px" />
      </Grid>
      <Grid xs={6} md={4}>
        <Capacity value={75} color={theme.palette.error} width="200px" />
      </Grid>
      <Grid xs={6} md={4}>
        <Capacity value={75} color={theme.palette.info} width="200px" />
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Playground
  title="Plan usage"
  desc="Pair each `Capacity` with a label and the numbers. `limit` is the full bar, and the color changes by itself as it fills."
  scope={{ Capacity, Grid, Card, Text }}
  code={`
<Card bordered width="100%">
  <Grid.Container direction="column" gap={1.5}>
    {[
      ['Projects', 3, 10],
      ['Members', 7, 10],
      ['Storage (GB)', 9.4, 10]
    ].map(([label, value, limit]) => (
      <Grid key={label}>
        <Grid.Container justify="space-between">
          <Grid>
            <Text small>{label}</Text>
          </Grid>
          <Grid>
            <Text small type="secondary">{value} of {limit}</Text>
          </Grid>
        </Grid.Container>
        <Capacity value={value} limit={limit} width="100%" />
      </Grid>
    ))}
  </Grid.Container>
</Card>
`}
/>

<Attributes edit="/content/docs/components/capacity.mdx">
<Attributes.Title>Capacity.Props</Attributes.Title>

| Attribute | Description      | Type             | Accepted values    | Default |
| --------- | ---------------- | ---------------- | ------------------ | ------- |
| **value** | value number     | `number`         | -                  | 0       |
| **limit** | max value        | `number`         | -                  | 100     |
| **color** | css color string | `string`         | -                  | -       |
| ...       | native props     | `HTMLAttributes` | `'className', ...` | -       |

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Card, Link, Image, Text, Divider, Code, Grid, Avatar, Button } from 'core'

export const meta = {
  title: 'Card',
  description: 'A common container component.',
  sidebar: 'components',
  group: 'Components',
  index: 8
}

## Card

A common container component.

<Playground
  title="General"
  desc="The basic `Card` usage."
  scope={{ Card, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Card>A default card.</Card>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Hoverable"
  desc="You can apply a fancy hover animation with the `hoverable` prop."
  scope={{ Card, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid xs={12} md={4}>
    <Card hoverable>A hoverable default card.</Card>
  </Grid>
  <Grid xs={12} md={4}>
    <Card hoverable type="primary">A hoverable primary card.</Card>
  </Grid>
  <Grid xs={12} md={4}>
    <Card hoverable type="secondary">A hoverable secondary card.</Card>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Bordered"
  desc="You can apply a fancy hover animation with the `bordered` prop."
  scope={{ Card, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid xs={12} md={4}>
    <Card bordered>A bordered default card.</Card>
  </Grid>
  <Grid xs={12} md={4}>
    <Card bordered type="primary">A bordered primary card.</Card>
  </Grid>
  <Grid xs={12} md={4}>
    <Card bordered type="secondary">A bordered secondary card.</Card>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Shadow"
  desc="You can apply shadow with the `shadow` prop."
  scope={{ Card, Grid, Text }}
  code={`
<Grid.Container gap={2}>
  <Grid xs={12} md={4}>
    <Card shadow>A shadow default card.</Card>
  </Grid>
  <Grid xs={12} md={4}>
    <Card shadow type="primary">A shadow primary card.</Card>
  </Grid>
  <Grid xs={12} md={4}>
    <Card shadow type="secondary">A shadow secondary card.</Card>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Types"
  desc="Show different states with colors."
  scope={{ Card, Grid, Text }}
  code={`
() => {
  const types = ['default', 'primary', 'secondary', 'success', 'warning', 'error', 'info', 'dark', 'lite']
  return (
    <Grid.Container gap={2}>
      {types.map((type) => (
        <Grid xs={6} md={4} key={type}>
          <Card type={type} width="100%">
            <Text h4 my={0} style={{ textTransform: 'uppercase' }}>
              {type}
            </Text>
            <Text>{type}</Text>
          </Card>
        </Grid>
      ))}
    </Grid.Container>
  )
}
`}
/>

<Playground
  title="With Footer"
  desc="You can use the `Card.Footer` component to add actions, details or another information to the `Card`."
  scope={{ Card, Link, Grid, Text }}
  code={`
<Grid.Container gap={2}>
  <Grid xs={12} md={6} justify="center">
    <Card width="100%">
      <Text h4 my={0}>
        Bolio UI
      </Text>
      <Text>More creative and fun with amazing features for React.</Text>
      <Card.Footer>
        <Link
          color
          target="_blank"
          href="https://github.com/bolio-ui/bolio-ui"
        >
          Visit source code on GitHub.
        </Link>
      </Card.Footer>
    </Card>
  </Grid>
  <Grid xs={12} md={6} justify="center">
    <Card width="100%" type="dark">
      <Text h4 my={0}>
        Bolio UI
      </Text>
      <Text>More creative and fun with amazing features for React.</Text>
      <Card.Footer>
        <Link target="_blank" href="https://github.com/bolio-ui/bolio-ui">
          Visit source code on GitHub.
        </Link>
      </Card.Footer>
    </Card>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="With Image"
  desc="You can use the `Image` component to add an image to the `Card`."
  scope={{ Card, Link, Text, Image, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Card width="350px">
      <Image
        src="https://images.pexels.com/photos/1779487/pexels-photo-1779487.jpeg"
        width="350px"
        draggable={false}
      />
      <Text h4 mb={0} mt={0}>
        Bolio UI
      </Text>
      <Text type="primary" small>
        More creative and fun with amazing features for React.
      </Text>
      <Card.Footer>
        <Link
          block
          target="_blank"
          href="https://github.com/bolio-ui/bolio-ui"
        >
          Visit source code on GitHub.
        </Link>
      </Card.Footer>
    </Card>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="With Divider"
  desc="Show different types of content using `Divider`."
  scope={{ Card, Text, Divider, Code, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Card width="400px">
      <Card.Content>
        <Text b my={0}>
          A Simple Component
        </Text>
      </Card.Content>
      <Divider h="1px" my={0} />
      <Card.Content>
        <Text>
          React components implement a <Code>render()</Code> method that takes
          input data and returns what to display. This example uses an
          XML-like syntax called JSX. Input data that is passed into the
          component can be accessed by <Code>render()</Code> via{' '}
          <Code>this.props</Code>.
        </Text>
      </Card.Content>
    </Card>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Spotlight"
  desc="The `spotlight` prop adds a glow that follows the pointer. It uses the card text color, so it fits every `type`."
  scope={{ Card, Grid, Text }}
  code={`
<Grid.Container gap={2}>
  <Grid xs={12} md={4}>
    <Card spotlight bordered width="100%">
      <Text h4 my={0}>Default</Text>
      <Text>Move the pointer over the card.</Text>
    </Card>
  </Grid>
  <Grid xs={12} md={4}>
    <Card spotlight type="primary" width="100%">
      <Text h4 my={0}>Primary</Text>
      <Text>The glow follows the card color.</Text>
    </Card>
  </Grid>
  <Grid xs={12} md={4}>
    <Card spotlight type="dark" width="100%">
      <Text h4 my={0}>Dark</Text>
      <Text>Works on solid backgrounds too.</Text>
    </Card>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Glass"
  desc="The `glass` prop makes the background translucent with a blur. Use it over images or gradients."
  scope={{ Card, Grid, Text }}
  code={`
<div
  style={{
    padding: 24,
    borderRadius: 12,
    background: 'linear-gradient(135deg, #60A5FA, #A78BFA 60%, #F472B6)'
  }}
>
  <Grid.Container gap={2}>
    <Grid xs={12} md={6}>
      <Card glass bordered width="100%">
        <Text h4 my={0}>Frosted</Text>
        <Text>The gradient shows through the card.</Text>
      </Card>
    </Grid>
    <Grid xs={12} md={6}>
      <Card glass type="dark" width="100%">
        <Text h4 my={0}>Frosted dark</Text>
        <Text>Same effect with a dark tint.</Text>
      </Card>
    </Grid>
  </Grid.Container>
</div>
`}
/>

<Playground
  title="Interactive"
  desc="The `interactive` prop makes the card behave like a button: pointer cursor, lift on hover and a visible focus ring for keyboard users."
  scope={{ Card, Grid, Text }}
  code={`
<Grid.Container gap={2}>
  <Grid xs={12} md={6}>
    <Card interactive bordered width="100%" onClick={() => alert('Opened')}>
      <Text h4 my={0}>Open project</Text>
      <Text>Click, or focus with Tab.</Text>
    </Card>
  </Grid>
  <Grid xs={12} md={6}>
    <Card interactive spotlight bordered width="100%">
      <Text h4 my={0}>With spotlight</Text>
      <Text>Combine variants freely.</Text>
    </Card>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Metric"
  desc="A compact card for a number and its trend."
  scope={{ Card, Grid, Text }}
  code={`
<Grid.Container gap={2}>
  <Grid xs={12} md={4}>
    <Card bordered width="100%">
      <Text small type="secondary" my={0}>Revenue</Text>
      <Text h2 my={0}>$48,200</Text>
      <Text small type="success" my={0}>+12.4% this month</Text>
    </Card>
  </Grid>
  <Grid xs={12} md={4}>
    <Card bordered width="100%">
      <Text small type="secondary" my={0}>Active users</Text>
      <Text h2 my={0}>3,842</Text>
      <Text small type="success" my={0}>+4.1% this week</Text>
    </Card>
  </Grid>
  <Grid xs={12} md={4}>
    <Card bordered width="100%">
      <Text small type="secondary" my={0}>Churn</Text>
      <Text h2 my={0}>1.8%</Text>
      <Text small type="error" my={0}>+0.3% this month</Text>
    </Card>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Pricing"
  desc="Highlight the recommended plan with `filled` and `spotlight`, and keep the others quiet."
  scope={{ Card, Grid, Text, Divider }}
  code={`
<Grid.Container gap={2}>
  <Grid xs={12} md={6}>
    <Card bordered width="100%">
      <Text h4 my={0}>Free</Text>
      <Text h2 my={0}>$0</Text>
      <Divider h="1px" my={1} />
      <Text my={0}>1 project</Text>
      <Text my={0}>Community support</Text>
    </Card>
  </Grid>
  <Grid xs={12} md={6}>
    <Card filled spotlight type="primary" width="100%">
      <Text h4 my={0}>Pro</Text>
      <Text h2 my={0}>$12</Text>
      <Divider h="1px" my={1} />
      <Text my={0}>Unlimited projects</Text>
      <Text my={0}>Priority support</Text>
    </Card>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Profile"
  desc="A person with their contact and the two actions people take next."
  scope={{ Card, Avatar, Text, Divider, Button, Grid }}
  code={`
<Card bordered width="320px">
  <Grid.Container gap={1} alignItems="center">
    <Grid>
      <Avatar text="AL" />
    </Grid>
    <Grid>
      <Text h5 my={0}>Ada Lovelace</Text>
      <Text small type="secondary">ada@example.com</Text>
    </Grid>
  </Grid.Container>
  <Divider />
  <Grid.Container gap={1}>
    <Grid>
      <Button auto scale={0.75} type="primary">Message</Button>
    </Grid>
    <Grid>
      <Button auto scale={0.75}>View profile</Button>
    </Grid>
  </Grid.Container>
</Card>
`}
/>

<Attributes edit="/content/docs/components/card.mdx">
<Attributes.Title>Card.Props</Attributes.Title>

| Attribute     | Description         | Type                  | Accepted values         | Default   |
| ------------- | ------------------- | --------------------- | ----------------------- | --------- |
| **hoverable** | add effect on hover                        | `boolean`              | -                       | `false`   |
| **shadow**    | show shadow                                | `boolean`              | -                       | `false`   |
| **type**      | card type                                  | [CardType](#cardtype)  | -                       | `default` |
| **filled**    | filled variant, solid background           | `boolean`              | -                       | `false`   |
| **ghost**     | outline variant, always shows a border     | `boolean`              | -                       | `false`   |
| **subtle**    | subtle variant, no background              | `boolean`              | -                       | `false`   |
| **spotlight** | glow that follows the pointer on hover     | `boolean`              | -                       | `false`   |
| **glass**     | translucent background with blur           | `boolean`              | -                       | `false`   |
| **interactive** | pointer cursor, lift on hover and focus ring | `boolean`          | -                       | `false`   |
| ...           | native props                               | `HTMLAttributes`       | `'id', className', ...` | -         |

<Attributes.Title alias="Card.Body">Card.Content.Props</Attributes.Title>

| Attribute | Description  | Type             | Accepted values         | Default |
| --------- | ------------ | ---------------- | ----------------------- | ------- |
| ...       | native props | `HTMLAttributes` | `'id', className', ...` | -       |

<Attributes.Title alias="Card.Actions">Card.Footer.Props</Attributes.Title>

| Attribute             | Description                   | Type             | Accepted values         | Default |
| --------------------- | ----------------------------- | ---------------- | ----------------------- | ------- |
| **disableAutoMargin** | cancel automatic margin value | `boolean`        | -                       | `false` |
| ...                   | native props                  | `HTMLAttributes` | `'id', className', ...` | -       |

<Attributes.Title>CardType</Attributes.Title>

```ts
type CardType =
  | 'default'
  | 'primary'
  | 'secondary'
  | 'success'
  | 'warning'
  | 'error'
  | 'info'
  | 'dark'
  | 'lite'
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Carousel, Card, Text, Avatar, Button, Grid, Image, useTheme } from 'core'

export const meta = {
  title: 'Carousel',
  description:
    'A row of slides that scrolls and snaps, with buttons and dots to move between them.',
  sidebar: 'components',
  group: 'Components',
  index: 64
}

## Carousel

A row of slides that scrolls and snaps into place. It is plain scrolling with
`scroll-snap`, so touch, trackpad and keyboard work as the browser does them,
and the buttons and dots move the same scroll.

<Playground
  desc="Each child is a slide. Name the carousel with `aria-label`."
  scope={{ Carousel, Card, Text }}
  code={`
<Carousel aria-label="Product highlights">
  {[
    ['Themes', 'Dark and light, and your brand color in one line.'],
    ['Accessible', 'Keyboard and screen reader support in every component.'],
    ['Typed', 'Props and refs are typed for TypeScript.']
  ].map(([title, text]) => (
    <Card key={title} bordered width="100%" style={{ minHeight: 120 }}>
      <Text h4 my={0}>{title}</Text>
      <Text p type="secondary">{text}</Text>
    </Card>
  ))}
</Carousel>
`}
/>

<Playground
  title="Several slides"
  desc="`slidesToShow` sets how many are in view, and `gap` the space between them. The dots count the positions the first slide can take."
  scope={{ Carousel, Card, Text }}
  code={`
<Carousel aria-label="Plans" slidesToShow={3} gap="0.75rem">
  {['Free', 'Starter', 'Pro', 'Team', 'Business'].map((name, index) => (
    <Card key={name} bordered width="100%">
      <Text p my={0}><b>{name}</b></Text>
      <Text small type="secondary">{'$' + index * 12 + ' a month'}</Text>
    </Card>
  ))}
</Carousel>
`}
/>

<Playground
  title="Photo gallery"
  desc="Use `Image` with a fixed height and `objectFit: 'cover'` so every photo fills its slide the same way, and describe each one in `alt`."
  scope={{ Carousel, Image, Text, useTheme }}
  code={`
() => {
  const theme = useTheme()
  const photos = [
    ['/img/jpg/docs/lake-sunrise.jpg', 'A mountain lake at sunrise', 'Lake at sunrise'],
    ['/img/jpg/docs/forest-lake.jpg', 'A forest lake under the clouds', 'Forest lake'],
    ['/img/jpg/docs/autumn-canyon.jpg', 'A river in a canyon in autumn', 'Autumn canyon'],
    ['/img/jpg/docs/mountain-reflection.jpg', 'Snowy mountains reflected in a lake', 'Mountain reflection'],
    ['/img/jpg/docs/moonlit-peaks.jpg', 'Snowy mountains under the moon', 'Moonlit peaks']
  ]
  return (
    <Carousel aria-label="Photo gallery">
      {photos.map(([src, alt, caption]) => (
        <div key={src}>
          <Image
            src={src}
            alt={alt}
            width="100%"
            height="240px"
            style={{ objectFit: 'cover', borderRadius: theme.layout.radius }}
          />
          <Text small type="secondary">{caption}</Text>
        </div>
      ))}
    </Carousel>
  )
}
`}
/>

<Playground
  title="Several photos"
  desc="Show a few photos at once and let the rest scroll in. A smaller height keeps the row compact."
  scope={{ Carousel, Image, useTheme }}
  code={`
() => {
  const theme = useTheme()
  const photos = [
    ['/img/jpg/docs/lake-sunrise.jpg', 'A mountain lake at sunrise'],
    ['/img/jpg/docs/forest-lake.jpg', 'A forest lake under the clouds'],
    ['/img/jpg/docs/autumn-canyon.jpg', 'A river in a canyon in autumn'],
    ['/img/jpg/docs/mountain-reflection.jpg', 'Snowy mountains reflected in a lake'],
    ['/img/jpg/docs/moonlit-peaks.jpg', 'Snowy mountains under the moon']
  ]
  return (
    <Carousel aria-label="More photos" slidesToShow={3} gap="0.75rem">
      {photos.map(([src, alt]) => (
        <Image
          key={src}
          src={src}
          alt={alt}
          width="100%"
          height="140px"
          style={{ objectFit: 'cover', borderRadius: theme.layout.radius }}
        />
      ))}
    </Carousel>
  )
}
`}
/>

<Playground
  title="Destination cards"
  desc="A photo, a name and a price in each `Card`, with two cards in view. Put the name and the price on separate lines."
  scope={{ Carousel, Card, Image, Text, useTheme }}
  code={`
() => {
  const theme = useTheme()
  const places = [
    ['/img/jpg/docs/lake-sunrise.jpg', 'A mountain lake at sunrise', 'Lake at sunrise', 'From $420'],
    ['/img/jpg/docs/forest-lake.jpg', 'A forest lake under the clouds', 'Forest lake', 'From $380'],
    ['/img/jpg/docs/autumn-canyon.jpg', 'A river in a canyon in autumn', 'Autumn canyon', 'From $510'],
    ['/img/jpg/docs/mountain-reflection.jpg', 'Snowy mountains reflected in a lake', 'Mountain reflection', 'From $460']
  ]
  return (
    <Carousel aria-label="Trips" slidesToShow={2}>
      {places.map(([src, alt, name, price]) => (
        <Card key={name} bordered width="100%">
          <Image
            src={src}
            alt={alt}
            width="100%"
            height="140px"
            style={{ objectFit: 'cover', borderRadius: theme.layout.radius }}
          />
          <Text p my={0} style={{ marginTop: 12 }}><b>{name}</b></Text>
          <Text small type="secondary">{price}</Text>
        </Card>
      ))}
    </Carousel>
  )
}
`}
/>

<Playground
  title="Controlled"
  desc="Use `value` for the first slide in view and `onChange` to hear about it, both from the buttons and from the scroll."
  scope={{ Carousel, Card, Text, Button, Grid }}
  code={`
() => {
  const [index, setIndex] = React.useState(0)
  return (
    <Grid.Container direction="column" gap={1}>
      <Grid>
        <Carousel aria-label="Steps" value={index} onChange={setIndex}>
          {['Create an account', 'Invite your team', 'Deploy', 'Share the link'].map((step) => (
            <Card key={step} bordered width="100%" style={{ minHeight: 96 }}>
              <Text b>{step}</Text>
            </Card>
          ))}
        </Carousel>
      </Grid>
      <Grid>
        <Grid.Container gap={1} alignItems="center">
          <Grid>
            <Text small type="secondary">Slide {index + 1} of 4</Text>
          </Grid>
          <Grid>
            <Button auto scale={0.6} onClick={() => setIndex(3)}>Jump to the last</Button>
          </Grid>
        </Grid.Container>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Playground
  title="Customer quotes"
  desc="One quote at a time, with who said it. Hide the buttons with `controls` when the dots are enough."
  scope={{ Carousel, Card, Text, Avatar }}
  code={`
<Carousel aria-label="What customers say" controls={false}>
  {[
    ['AL', 'Ada Lovelace', 'We shipped our dashboard in a week.'],
    ['GH', 'Grace Hopper', 'The best defaults I have used.'],
    ['LT', 'Linus Torvalds', 'Easy to theme, and the docs are clear.']
  ].map(([text, name, quote]) => (
    <Card key={name} bordered width="100%">
      <Text p my={0}>{quote}</Text>
      <div style={{ display: 'flex', alignItems: 'center', gap: 8, marginTop: 12 }}>
        <Avatar text={text} />
        <Text small b>{name}</Text>
      </div>
    </Card>
  ))}
</Carousel>
`}
/>

<Attributes edit="/content/docs/components/carousel.mdx">
<Attributes.Title>Carousel.Props</Attributes.Title>

| Attribute          | Description                                                       | Type                                          | Accepted values           | Default             |
| ------------------ | ----------------------------------------------------------------- | --------------------------------------------- | ------------------------- | ------------------- |
| **slidesToShow**   | slides in view at once                                            | `number`                                      | -                         | `1`                 |
| **gap**            | space between the slides                                          | `string`                                      | any CSS length            | `1rem`              |
| **controls**       | show the previous and next buttons                                | `boolean`                                     | -                         | `true`              |
| **indicators**     | show a dot for each position                                      | `boolean`                                     | -                         | `true`              |
| **value**          | index of the first slide in view, to control it                   | `number`                                      | -                         | -                   |
| **initialValue**   | index of the first slide in view on the first render              | `number`                                      | -                         | `0`                 |
| **onChange**       | called with the index of the slide the scroll rests on            | `(index: number) => void`                     | -                         | -                   |
| **previousLabel**  | name of the previous button                                       | `string`                                      | -                         | `Previous slide`    |
| **nextLabel**      | name of the next button                                           | `string`                                      | -                         | `Next slide`        |
| **slideLabel**     | name of each slide for screen readers                             | `(index: number, count: number) => string`    | -                         | `1 of 5`            |
| **indicatorLabel** | name of each dot                                                  | `(index: number) => string`                   | -                         | `Go to slide 1`     |
| ...                | native props, passed to the root `div`                            | `HTMLAttributes`                              | `'aria-label', 'id', ...` | -                   |

<Attributes.Title>Behavior</Attributes.Title>

- • **Scroll**: swiping, the trackpad, the arrow keys on the focused list and the buttons all move the same scroll. `onChange` is called once the scroll stops, not on every pixel.
- • **Motion**: the scroll is smooth, unless the user asked for less motion in the system.
- • **Ends**: the buttons are disabled on the first and the last position. There is no loop.
- • **Controls**: when every slide fits, the buttons and dots are not shown.

<Attributes.Title>Ref</Attributes.Title>

The `ref` points at the root `div`.

<Attributes.Title>Accessibility</Attributes.Title>

The root is a `region` with `aria-roledescription="carousel"`, and each slide is a `group` named by its position, like "2 of 5". Name the carousel with `aria-label`. The scrolling list can be focused, so the keyboard can scroll it, and the buttons and dots are real buttons with names you can translate. The dot of the current position has `aria-current`.

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Checkbox, Grid, Code, Button } from 'core'

export const meta = {
  title: 'Checkbox',
  description: 'Displays a boolean value.',
  sidebar: 'components',
  group: 'Components',
  index: 9
}

## Checkbox

Displays a boolean value.

<Playground
  desc="Change state with `checked` props."
  scope={{ Checkbox, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Checkbox checked={true}>Check option</Checkbox>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Sizes"
  desc="Checkbox of different sizes."
  scope={{ Checkbox, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Checkbox mr="15px" checked={true} scale={0.25}>
      scale-0.25
    </Checkbox>
  </Grid>
  <Grid>
    <Checkbox mr="15px" checked={true} scale={0.5}>
      scale-0.5
    </Checkbox>
  </Grid>
  <Grid>
    <Checkbox mr="15px" checked={true} scale={0.75}>
      scale-0.75
    </Checkbox>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Type"
  desc="Differentiate states by color."
  scope={{ Checkbox, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Checkbox checked={true} type="default">
      Checkbox Default
    </Checkbox>
  </Grid>
  <Grid>
    <Checkbox checked={true} type="primary">
      Checkbox Primary
    </Checkbox>
  </Grid>
  <Grid>
    <Checkbox checked={true} type="secondary">
      Checkbox Secondary
    </Checkbox>
  </Grid>
  <Grid>
    <Checkbox checked={true} type="success">
      Checkbox Success
    </Checkbox>
  </Grid>
  <Grid>
    <Checkbox checked={true} type="warning">
      Checkbox Warning
    </Checkbox>
  </Grid>
  <Grid>
    <Checkbox checked={true} type="error">
      Checkbox Error
    </Checkbox>
  </Grid>
  <Grid>
    <Checkbox checked={true} type="info">
      Checkbox Info
    </Checkbox>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Disable"
  desc="Unusable and un-clickable `Checkbox`."
  scope={{ Checkbox, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Checkbox>Checkbox option</Checkbox>
  </Grid>
  <Grid>
    <Checkbox disabled checked={true}>
      Checkbox option disabled
    </Checkbox>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Group"
  desc="Manage a set of `Checkbox`."
  scope={{ Checkbox, Grid }}
  code={`
() => {
  const handler = value => {
    console.log(value)
  }
  return (
    <Grid.Container gap={2}>
      <Grid>
        <Checkbox.Group value={['check3']} onChange={handler}>
          <Checkbox value="check1">Checkbox option 1</Checkbox>
          <Checkbox value="check2">Checkbox option 2</Checkbox>
          <Checkbox value="check3">Checkbox option 3</Checkbox>
          <Checkbox value="check4">Checkbox option 4</Checkbox>
        </Checkbox.Group>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Playground
  title="Accept terms"
  desc="Keep the action disabled until the box is checked, so the next step is clear."
  scope={{ Checkbox, Grid, Button }}
  code={`
() => {
  const [accepted, setAccepted] = React.useState(false)
  return (
    <Grid.Container direction="column" gap={1}>
      <Grid>
        <Checkbox checked={accepted} onChange={(event) => setAccepted(event.target.checked)}>
          I accept the terms of use
        </Checkbox>
      </Grid>
      <Grid>
        <Button auto type="primary" disabled={!accepted}>Create account</Button>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Attributes edit="/content/docs/components/checkbox.mdx">
<Attributes.Title>Checkbox.Props</Attributes.Title>

| Attribute          | Description                                 | Type                                           | Accepted values                 | Default   |
| ------------------ | ------------------------------------------- | ---------------------------------------------- | ------------------------------- | --------- |
| **checked**        | checked or not                              | `boolean`                                      | -                               | -         |
| **initialChecked** | checked or not on initial                   | `boolean`                                      | -                               | `false`   |
| **onChange**       | change event handler                        | `CheckboxEvent`                                | -                               | -         |
| **value**          | unique identification value (only in group) | `string`                                       | -                               | -         |
| **disabled**       | disable checkbox                            | `boolean`                                      | -                               | `false`   |
| **type**           | current type                                | `CheckboxTypes`                                | [CheckboxTypes](#checkboxtypes) | `default` |
| **ref**            | forwardRef                                  | <Code>Ref&lt;HTMLInputElement &#124; null&gt;</Code> | -                               | -         |
| ...                | native props                                | `LabelHTMLAttributes`                          | `'form' ...`                    | -         |

<Attributes.Title>Checkbox.Group.Props</Attributes.Title>

| Attribute    | Description            | Type                         | Accepted values | Default |
| ------------ | ---------------------- | ---------------------------- | --------------- | ------- |
| **value**    | checked children       | `Array<string>`              | -               | `[]`    |
| **disabled** | disable checkbox group | `boolean`                    | -               | `false` |
| **onChange** | change event handler   | `(values: string[]) => void` | -               | -       |
| ...          | native props           | `HTMLAttributes`             | `'id', ...`     | -       |

<Attributes.Title>CheckboxTypes</Attributes.Title>

```ts
type CheckboxTypes =
  | 'default'
  | 'primary'
  | 'secondary'
  | 'success'
  | 'warning'
  | 'error'
  | 'info'
```

<Attributes.Title>CheckboxEvent</Attributes.Title>

```ts
interface CheckboxEventTarget {
  checked: boolean
}

export interface CheckboxEvent {
  target: CheckboxEventTarget
  stopPropagation: () => void
  preventDefault: () => void
  nativeEvent: React.ChangeEvent
}
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Chip, Card, Text, Grid } from 'core'

export const meta = {
  title: 'Chip',
  description: 'Pick options from a row of pills, one or several at a time.',
  sidebar: 'components',
  group: 'Components',
  index: 55
}

## Chip

Pick options from a row of pills, one or several at a time.

<Playground
  title="General"
  desc="A `Chip` alone works as a checkbox. Control it with `checked` and `onChange`, or let it keep its own state."
  scope={{ Chip }}
  code={`
<Chip initialChecked>Free shipping</Chip>
`}
/>

<Playground
  title="Multiple"
  desc="`Chip.Group` with `multiple` lets the user check several chips. `onChange` receives the values of the checked ones."
  scope={{ Chip, Text }}
  code={`
() => {
  const [stack, setStack] = React.useState(['react'])
  return (
    <>
      <Chip.Group multiple value={stack} onChange={setStack} aria-label="Stack">
        <Chip value="react">React</Chip>
        <Chip value="vue">Vue</Chip>
        <Chip value="svelte">Svelte</Chip>
        <Chip value="solid">Solid</Chip>
      </Chip.Group>
      <Text small type="secondary">
        {stack.length ? stack.length + ' selected: ' + stack.join(', ') : 'Pick at least one framework.'}
      </Text>
    </>
  )
}
`}
/>

<Playground
  title="Single"
  desc="Without `multiple`, checking a chip unchecks the other, the way a radio group does."
  scope={{ Chip }}
  code={`
() => {
  const [size, setSize] = React.useState(['m'])
  return (
    <Chip.Group value={size} onChange={setSize} aria-label="Size">
      <Chip value="s">S</Chip>
      <Chip value="m">M</Chip>
      <Chip value="l">L</Chip>
      <Chip value="xl" disabled>XL, sold out</Chip>
    </Chip.Group>
  )
}
`}
/>

<Playground
  title="Filtering a list"
  desc="Use the checked values to filter what is shown. Here the list narrows to the topics you picked."
  scope={{ Chip, Card, Text }}
  code={`
() => {
  const posts = [
    ['Ship a Tour in an afternoon', 'product'],
    ['Why we dropped styled-jsx', 'engineering'],
    ['Dark mode without gray mush', 'design'],
    ['Splitting a layout with CSS grid', 'engineering'],
    ['Reading an empty state', 'design']
  ]
  const [topics, setTopics] = React.useState([])
  const shown = topics.length ? posts.filter(([, topic]) => topics.includes(topic)) : posts
  return (
    <>
      <Chip.Group multiple value={topics} onChange={setTopics} aria-label="Topics">
        <Chip value="product">Product</Chip>
        <Chip value="engineering">Engineering</Chip>
        <Chip value="design">Design</Chip>
      </Chip.Group>
      <div style={{ marginTop: 16, display: 'grid', gap: 8 }}>
        {shown.map(([title, topic]) => (
          <Card key={title} bordered width="100%">
            <Text b>{title}</Text>
            <Text small type="secondary" style={{ textTransform: 'capitalize' }}>{topic}</Text>
          </Card>
        ))}
      </div>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/components/chip.mdx">
<Attributes.Title>Chip.Props</Attributes.Title>

| Attribute          | Description                                              | Type                                                              | Accepted values | Default   |
| ------------------ | -------------------------------------------------------- | ----------------------------------------------------------------- | --------------- | --------- |
| **value**          | value the chip adds to or takes from its `Chip.Group`    | `string`                                                          | -               | -         |
| **checked**        | checked state, to control the chip                       | `boolean`                                                         | -               | -         |
| **initialChecked** | checked state at the start                               | `boolean`                                                         | -               | `false`   |
| **onChange**       | called with the new state when the chip is alone         | `(checked: boolean) => void`                                      | -               | -         |
| **type**           | color of a checked chip                                  | `'primary' \| 'secondary' \| 'success' \| 'warning' \| 'error' \| 'info'` | -         | `primary` |
| **disabled**       | block the chip                                           | `boolean`                                                         | -               | `false`   |
| ...                | native props of the input                                | `InputHTMLAttributes`                                             | -               | -         |

<Attributes.Title>Chip.Group.Props</Attributes.Title>

| Attribute        | Description                                 | Type                          | Accepted values | Default |
| ---------------- | ------------------------------------------- | ----------------------------- | --------------- | ------- |
| **value**        | values of the checked chips, to control it  | `string[]`                    | -               | -       |
| **initialValue** | values checked at the start                 | `string[]`                    | -               | `[]`    |
| **onChange**     | called with the values of the checked chips | `(value: string[]) => void`   | -               | -       |
| **multiple**     | allow several checked chips                 | `boolean`                     | -               | `false` |
| **disabled**     | block every chip of the group               | `boolean`                     | -               | `false` |
| ...              | native props                                | `HTMLAttributes`              | -               | -       |

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Code, Text, Grid } from 'core'
import { Playground, Attributes, ParsedCodes } from 'src/components'
import WaitTime from 'core/MdxWidgets/ParsedCodes/WaitTime'

export const meta = {
  title: 'Code',
  description: 'Show source code in a standardized way.',
  sidebar: 'components',
  group: 'Components',
  index: 10
}

## Code

Show source code in a standardized way. Want to display shell code snippets? try [Snippet](/docs/components/snippet).

<Playground
  desc="Basic inline codes."
  scope={{ Code, Text, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Text my={0}>
      Run <Code>npm i @bolio-ui/core</Code> to install.
    </Text>
    <Text my={0}>
      Or run <Code>yarn add @bolio-ui/core</Code> to install.
    </Text>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Code Block"
  desc="Multi line code display."
  scope={{ Code, WaitTime, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Code block my={0}>
      <WaitTime />
    </Code>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Width"
  desc="Specify width manually, or other styles."
  scope={{ Code, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid xs={24}>
    <Code block width="50%" my={0}>
      {'yarn add @bolio-ui/core'}
    </Code>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Name"
  desc="Specify the file name for the code block."
  scope={{ Code, WaitTime, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Code block name="/Components/WaitTime.jsx" my={0}>
      <WaitTime />
    </Code>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Tabs"
  desc="Show more than one code in the same block. Set the names in `tabs` and change the code when `onTabChange` is called."
  scope={{ Code, Grid }}
  code={`
() => {
  const [active, setActive] = React.useState(0)
  const codes = [
    "import { Button } from '@bolio-ui/core'",
    "import { Text } from '@bolio-ui/core'"
  ]
  return (
    <Grid.Container gap={2}>
      <Grid>
        <Code
          block
          tabs={['/src/button.js', '/src/text.js']}
          activeTab={active}
          onTabChange={setActive}
          my={0}
        >
          {codes[active]}
        </Code>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Playground
  title="Classic Style"
  desc="The classic design style with a line border instead of a background."
  scope={{ Code, WaitTime, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Code block classic name="/Components/WaitTime.jsx" my={0}>
      <WaitTime />
    </Code>
  </Grid>
</Grid.Container>
`}
/>

<Attributes edit="/content/docs/components/code.mdx">
<Attributes.Title>Code.Props</Attributes.Title>

| Attribute       | Description                                 | Type                      | Accepted values    | Default |
| --------------- | ------------------------------------------- | ------------------------- | ------------------ | ------- |
| **block**       | show code in `pre`                          | `boolean`                 | -                  | `false` |
| **name**        | text displayed at the top of the code block | `string`                  | -                  | -       |
| **classic**     | display with classic style                  | `boolean`                 | -                  | `false` |
| **tabs**        | names of the tabs, in place of `name`       | `string[]`                | -                  | `[]`    |
| **activeTab**   | index of the active tab                     | `number`                  | -                  | `0`     |
| **onTabChange** | called with the index of the chosen tab     | `(index: number) => void` | -                  | -       |
| ...             | native props                                | `HTMLAttributes`          | `'className', ...` | -       |

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Row, Col, Card, Text } from 'core'

export const meta = {
  title: 'Col',
  description: 'A column inside a Row, sized in twelfths.',
  sidebar: 'components',
  group: 'Components',
  index: 47
}

## Col

A column inside a <a href="/docs/components/row">Row</a>, sized in twelfths of the row.

<Playground
  desc="`span` is the number of twelfths, from 1 to 12."
  scope={{ Row, Col, Card, Text }}
  code={`
<Row>
  <Col span={4}><Card><Text small>span 4</Text></Card></Col>
  <Col span={8}><Card><Text small>span 8</Text></Card></Col>
</Row>
`}
/>

<Playground
  title="Offset"
  desc="`offset` leaves empty twelfths before the column."
  scope={{ Row, Col, Card, Text }}
  code={`
<Row>
  <Col span={4} offset={4}><Card><Text small>span 4, offset 4</Text></Card></Col>
</Row>
`}
/>

<Playground
  title="Sidebar layout"
  desc="A narrow column for navigation and a wide one for the content, side by side."
  scope={{ Row, Col, Card, Text }}
  code={`
<Row gap={1}>
  <Col span={3}>
    <Card bordered width="100%">
      <Text b>Settings</Text>
      <Text small type="secondary">Profile</Text>
      <Text small type="secondary">Billing</Text>
      <Text small type="secondary">Team</Text>
    </Card>
  </Col>
  <Col span={9}>
    <Card bordered width="100%">
      <Text b>Profile</Text>
      <Text p>Update your name, photo and the email we use to contact you.</Text>
    </Card>
  </Col>
</Row>
`}
/>

<Attributes edit="/content/docs/components/col.mdx">
<Attributes.Title>Col.Props</Attributes.Title>

| Attribute     | Description                                | Type                          | Accepted values               | Default |
| ------------- | ------------------------------------------ | ----------------------------- | ----------------------------- | ------- |
| **span**      | how many twelfths of the row it takes      | `number`                      | `1` to `12`                   | `12`    |
| **offset**    | how many twelfths to leave before it       | `number`                      | `0` to `11`                   | `0`     |
| **component** | the element to render                      | `keyof JSX.IntrinsicElements` | `'div', 'li', 'section', ...` | `div`   |
| ...           | native props                               | `HTMLAttributes`              | `'id', 'className', ...`      | -       |

<Attributes.Title>Ref</Attributes.Title>

The `ref` points at the root element.

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Collapse, Grid, Text } from 'core'

export const meta = {
  title: 'Collapse',
  description:
    'Display large amounts of text in collapsible sections. Commonly referred to as an accordion.',
  sidebar: 'components',
  group: 'Components',
  index: 11
}

## Collapse

Display large amounts of text in collapsible sections. Commonly referred to as an accordion.

<Playground
  scope={{ Collapse, Text, Grid }}
  desc="Show title only by default."
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Collapse.Group>
      <Collapse title="Lorem ipsum 1">
        <Text>
          Duis aute irure dolor in reprehenderit in voluptate velit esse
          cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat
          cupidatat non proident, sunt in culpa qui officia deserunt mollit
          anim id est laborum.
        </Text>
      </Collapse>
      <Collapse title="Lorem ipsum 2">
        <Text>
          Duis aute irure dolor in reprehenderit in voluptate velit esse
          cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat
          cupidatat non proident, sunt in culpa qui officia deserunt mollit
          anim id est laborum.
        </Text>
      </Collapse>
    </Collapse.Group>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Expanded"
  desc="Specify what to display first."
  scope={{ Collapse, Text, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Collapse.Group>
      <Collapse title="Lorem ipsum 1" initialVisible>
        <Text>
          Duis aute irure dolor in reprehenderit in voluptate velit esse
          cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat
          cupidatat non proident, sunt in culpa qui officia deserunt mollit
          anim id est laborum.
        </Text>
      </Collapse>
      <Collapse title="Lorem ipsum 2">
        <Text>
          Duis aute irure dolor in reprehenderit in voluptate velit esse
          cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat
          cupidatat non proident, sunt in culpa qui officia deserunt mollit
          anim id est laborum.
        </Text>
      </Collapse>
    </Collapse.Group>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Subtitle"
  desc="Add text or components as subtitle."
  scope={{ Collapse, Text, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Collapse.Group>
      <Collapse
        title="Lorem ipsum 1"
        subtitle="More description about Lorem ipsum 1"
      >
        <Text>
          Duis aute irure dolor in reprehenderit in voluptate velit esse
          cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat
          cupidatat non proident, sunt in culpa qui officia deserunt mollit
          anim id est laborum.
        </Text>
      </Collapse>
      <Collapse
        title="Lorem ipsum 2"
        subtitle={
          <>
            More description about <Text b>Lorem ipsum 2</Text>
          </>
        }
      >
        <Text>
          Duis aute irure dolor in reprehenderit in voluptate velit esse
          cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat
          cupidatat non proident, sunt in culpa qui officia deserunt mollit
          anim id est laborum.
        </Text>
      </Collapse>
    </Collapse.Group>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Shadow"
  desc="Highlight importance at a higher level."
  scope={{ Collapse, Text, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Collapse
      shadow
      title="Lorem ipsum 1"
      subtitle="More description about Lorem ipsum 1"
    >
      <Text>
        Duis aute irure dolor in reprehenderit in voluptate velit esse cillum
        dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
        proident, sunt in culpa qui officia deserunt mollit anim id est
        laborum
      </Text>
    </Collapse>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Controlled and disabled"
  desc="Pass `visible` and `onVisibleChange` to control a section. A section with `disabled` cannot be toggled."
  scope={{ Collapse, Text, Grid }}
  code={`
() => {
  const [visible, setVisible] = React.useState(true)
  return (
    <Grid.Container gap={2} direction="column">
      <Grid>
        <Collapse title="Controlled" visible={visible} onVisibleChange={setVisible}>
          <Text>The section is {visible ? 'open' : 'closed'}.</Text>
        </Collapse>
      </Grid>
      <Grid>
        <Collapse title="Disabled" disabled>
          <Text>Nobody sees this.</Text>
        </Collapse>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Attributes edit="/content/docs/components/collapse.mdx">
<Attributes.Title>Collapse.Props</Attributes.Title>

| Attribute           | Description      | Type             | Accepted values                  | Default |
| ------------------- | ---------------- | ---------------- | -------------------------------- | ------- |
| **title**(required) | collapse title   | `string`         | -                                | -       |
| **subtitle**        | description      | `string`         | -                                | -       |
| **initialVisible**  | initial expanded | `boolean`        | -                                | `false` |
| **visible**         | expanded, to control it | `boolean` | -                                | -       |
| **onVisibleChange** | called with the next state when the header is clicked | `(visible: boolean) => void` | -  | -       |
| **disabled**        | the section cannot be toggled | `boolean`   | -                                | `false` |
| **shadow**          | show shadow card | `boolean`        | -                                | `false` |
| ...                 | native props     | `HTMLAttributes` | `'id', 'name', 'className', ...` | -       |

<Attributes.Title>Collapse.Group.Props</Attributes.Title>

| Attribute     | Description    | Type             | Accepted values                  | Default |
| ------------- | -------------- | ---------------- | -------------------------------- | ------- |
| **accordion** | accordion mode | `boolean`        | -                                | `true`  |
| ...           | native props   | `HTMLAttributes` | `'id', 'name', 'className', ...` | -       |

<Attributes.Title>Accessibility</Attributes.Title>

The title is a heading with a real button inside, so a screen reader announces it as a heading and as a button that is expanded or collapsed, and `aria-controls` points at the content. Enter and Space toggle a section. In a `Collapse.Group`, the Up and Down arrows move focus between the titles, wrapping at the ends, and Home and End go to the first and the last. Disabled sections are skipped.

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { ColorInput, Grid, useTheme } from 'core'

export const meta = {
  title: 'Color Input',
  description:
    'A field for a hex color, with a swatch that opens a color picker in a popover.',
  sidebar: 'components',
  group: 'Components',
  index: 66
}

## Color Input

A field for a hex color. The swatch on the left shows the color and opens a
<a href="/docs/components/color-picker">Color Picker</a> in a popover. You can
also type the code.

<Playground
  desc="Name the field with a label passed as children. Without a visible label, use `aria-label`."
  scope={{ ColorInput }}
  code={`
<ColorInput initialValue="#2563eb">Brand color</ColorInput>
`}
/>

<Playground
  title="With swatches"
  desc="`swatches` shows colors to pick with one click inside the popover."
  scope={{ ColorInput }}
  code={`
<ColorInput
  aria-label="Label color"
  initialValue="#16a34a"
  swatches={['#dc2626', '#f59e0b', '#16a34a', '#2563eb', '#7c3aed']}
/>
`}
/>

<Playground
  title="Brand colors"
  desc="Two labeled fields side by side, with a preview that follows them as they change."
  scope={{ ColorInput, Grid, useTheme }}
  code={`
() => {
  const theme = useTheme()
  const [primary, setPrimary] = React.useState('#2563eb')
  const [secondary, setSecondary] = React.useState('#7c3aed')
  return (
    <Grid.Container gap={2}>
      <Grid>
        <ColorInput value={primary} onChange={setPrimary}>Primary</ColorInput>
      </Grid>
      <Grid>
        <ColorInput value={secondary} onChange={setSecondary}>Secondary</ColorInput>
      </Grid>
      <Grid xs={12}>
        <div
          style={{
            width: '100%',
            height: 56,
            borderRadius: theme.layout.radius,
            border: '1px solid ' + theme.palette.border,
            background: 'linear-gradient(90deg, ' + primary + ', ' + secondary + ')'
          }}
        />
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Playground
  title="Variants"
  desc="Use `filled`, `light`, `ghost` or `subtle` with a `type`, and `rounded`, to change the surface of the field."
  scope={{ ColorInput, Grid }}
  code={`
<Grid.Container gap={2} direction="column">
  <Grid>
    <ColorInput aria-label="Filled" type="primary" filled initialValue="#2563eb" />
  </Grid>
  <Grid>
    <ColorInput aria-label="Light" type="success" light initialValue="#16a34a" />
  </Grid>
  <Grid>
    <ColorInput aria-label="Ghost" type="info" ghost rounded initialValue="#0ea5e9" />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Disabled"
  desc="Shows the color and blocks the field and the swatch."
  scope={{ ColorInput }}
  code={`
<ColorInput aria-label="Brand color" disabled initialValue="#2563eb" />
`}
/>

<Attributes edit="/content/docs/components/color-input.mdx">
<Attributes.Title>ColorInput.Props</Attributes.Title>

| Attribute         | Description                                              | Type                    | Accepted values                                                            | Default        |
| ----------------- | -------------------------------------------------------- | ----------------------- | -------------------------------------------------------------------------- | -------------- |
| **value**         | the color, to control the component                      | `string`                | `'#rrggbb'`, `'#rgb'`                                                      | -              |
| **initialValue**  | the color on the first render                            | `string`                | `'#rrggbb'`, `'#rgb'`                                                      | `#000000`      |
| **onChange**      | called with the color as `#rrggbb` in lowercase          | `(hex: string) => void` | -                                                                          | -              |
| **swatches**      | colors to pick with one click in the popover             | `string[]`              | -                                                                          | -              |
| **placeholder**   | text shown when the field is empty                       | `string`                | -                                                                          | `#000000`      |
| **pickerLabel**   | name of the swatch button and of the dialog              | `string`                | -                                                                          | `Choose color` |
| **disabled**      | disable the component                                    | `boolean`               | -                                                                          | `false`        |
| **type**          | color of the field                                       | `NormalTypes`           | `'default', 'primary', 'secondary', 'success', 'warning', 'error', 'info'` | `default`      |
| **rounded**       | round the corners                                        | `boolean`               | -                                                                          | `false`        |
| **filled**        | filled variant                                           | `boolean`               | -                                                                          | `false`        |
| **light**         | light variant                                            | `boolean`               | -                                                                          | `false`        |
| **ghost**         | outline variant                                          | `boolean`               | -                                                                          | `false`        |
| **subtle**        | subtle variant                                           | `boolean`               | -                                                                          | `false`        |
| ...               | native props, passed to the input                        | `InputHTMLAttributes`   | `'aria-label', 'name', ...`                                                | -              |

<Attributes.Title>Typing</Attributes.Title>

The color changes as soon as the text holds six digits, with or without the `#`. A short code like `#abc` is read when the field loses the focus, and becomes `#aabbcc`. Any other text is dropped on blur, and the field goes back to the current color. The field always holds a color, so it cannot be left empty.

<Attributes.Title>Ref</Attributes.Title>

The `ref` points at the `input`.

<Attributes.Title>Accessibility</Attributes.Title>

The field is named by its label, or by `aria-label`. The swatch is a button with `aria-haspopup="dialog"` and `aria-expanded`, named by `pickerLabel`. The picker opens in a dialog with the focus on its square. Escape closes it and puts the focus back on the swatch. The code is also a text in the field, so the color is not conveyed by the swatch alone. See <a href="/docs/components/color-picker">Color Picker</a> for the keys.

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { ColorPicker, Grid, Text, Button, useTheme } from 'core'

export const meta = {
  title: 'Color Picker',
  description:
    'A panel to pick a color by saturation, brightness and hue, with a hex field and optional swatches.',
  sidebar: 'components',
  group: 'Components',
  index: 65
}

## Color Picker

A panel to pick a color. Drag in the square for the saturation and the
brightness, use the bar for the hue, or type the hex code. For a field that
opens this panel in a popover, see <a href="/docs/components/color-input">Color Input</a>.

<Playground
  desc="Start with a color using `initialValue`, and name the group with `aria-label`."
  scope={{ ColorPicker }}
  code={`
<ColorPicker aria-label="Brand color" initialValue="#2563eb" />
`}
/>

<Playground
  title="With swatches"
  desc="`swatches` adds colors to pick with one click, like the ones a team already uses."
  scope={{ ColorPicker }}
  code={`
<ColorPicker
  aria-label="Label color"
  initialValue="#16a34a"
  swatches={['#dc2626', '#f59e0b', '#16a34a', '#2563eb', '#7c3aed']}
/>
`}
/>

<Playground
  title="Controlled"
  desc="Use `value` and `onChange` to keep the color in your own state, for example to show a preview or to reset it."
  scope={{ ColorPicker, Grid, Text, Button, useTheme }}
  code={`
() => {
  const theme = useTheme()
  const [color, setColor] = React.useState('#f59e0b')
  return (
    <Grid.Container gap={2} alignItems="center">
      <Grid>
        <ColorPicker aria-label="Highlight color" value={color} onChange={setColor} />
      </Grid>
      <Grid>
        <div
          style={{
            width: 96,
            height: 96,
            borderRadius: theme.layout.radius,
            border: '1px solid ' + theme.palette.border,
            backgroundColor: color
          }}
        />
        <Text small type="secondary">{color}</Text>
        <div>
          <Button auto scale={0.6} onClick={() => setColor('#f59e0b')}>Reset</Button>
        </div>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Playground
  title="Disabled"
  desc="A disabled picker shows the color and cannot change it."
  scope={{ ColorPicker }}
  code={`
<ColorPicker aria-label="Brand color" disabled initialValue="#2563eb" />
`}
/>

<Attributes edit="/content/docs/components/color-picker.mdx">
<Attributes.Title>ColorPicker.Props</Attributes.Title>

| Attribute        | Description                                                  | Type                    | Accepted values           | Default                       |
| ---------------- | ------------------------------------------------------------ | ----------------------- | ------------------------- | ----------------------------- |
| **value**        | the color, to control the component                          | `string`                | `'#rrggbb'`, `'#rgb'`     | -                             |
| **initialValue** | the color on the first render                                | `string`                | `'#rrggbb'`, `'#rgb'`     | `#000000`                     |
| **onChange**     | called with the color as `#rrggbb` in lowercase              | `(hex: string) => void` | -                         | -                             |
| **swatches**     | colors to pick with one click                                | `string[]`              | -                         | -                             |
| **hexInput**     | show the field for the hex code                              | `boolean`               | -                         | `true`                        |
| **disabled**     | disable the component                                        | `boolean`               | -                         | `false`                       |
| **panelLabel**   | name of the square, for screen readers                       | `string`                | -                         | `Saturation and brightness`   |
| **hueLabel**     | name of the hue bar                                          | `string`                | -                         | `Hue`                         |
| **hexLabel**     | name of the hex field                                        | `string`                | -                         | `Hex color`                   |
| ...              | native props, passed to the root `div`                       | `HTMLAttributes`        | `'aria-label', 'id', ...` | -                             |

<Attributes.Title>Hex field</Attributes.Title>

The field changes the color as soon as it holds six digits, with or without the `#`. A short code like `#abc` is read when the field loses the focus, and becomes `#aabbcc`. Any other text is dropped on blur, and the field goes back to the current color.

<Attributes.Title>Ref</Attributes.Title>

The `ref` points at the root `div`.

<Attributes.Title>Accessibility</Attributes.Title>

The square is a `slider` named by `panelLabel`, whose value reads like "40% saturation, 80% brightness". With the focus on it, Left and Right change the saturation and Up and Down the brightness, by 1%, or by 10% with Shift. The hue bar is a native range input, and the swatches are buttons named by their code, with `aria-pressed` on the one in use. The color is never conveyed by the swatch alone, because the hex code is also a text.

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Combobox, Grid, Code } from 'core'

export const meta = {
  title: 'Combobox',
  description:
    'An input that filters a list of options while you type and lets you pick one.',
  sidebar: 'components',
  group: 'Components',
  index: 42
}

## Combobox

An input that filters a list of options while you type and lets you pick one.
Use it when the list is long enough that a `Select` is hard to scan.

<Playground
  desc="Pass the options and name the field with `aria-label`, or with a visible label."
  scope={{ Combobox, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Combobox
      aria-label="Country"
      placeholder="Search a country"
      options={[
        { value: 'br', label: 'Brazil' },
        { value: 'pt', label: 'Portugal' },
        { value: 'us', label: 'United States' },
        { value: 'ar', label: 'Argentina' }
      ]}
    />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Initial value and disabled options"
  desc="Use `initialValue` to start with a selection. An option with `disabled` cannot be picked."
  scope={{ Combobox, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Combobox
      aria-label="Country"
      initialValue="pt"
      options={[
        { value: 'br', label: 'Brazil' },
        { value: 'pt', label: 'Portugal' },
        { value: 'xx', label: 'Nowhere', disabled: true }
      ]}
    />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Empty text"
  desc="Change what shows when nothing matches with `emptyText`."
  scope={{ Combobox, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Combobox
      aria-label="Fruit"
      emptyText="No fruit with that name"
      options={[
        { value: 'apple', label: 'Apple' },
        { value: 'pear', label: 'Pear' }
      ]}
    />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Variants"
  desc="Use `filled`, `light`, `ghost` or `subtle` with a `type` to change the surface of the field."
  scope={{ Combobox, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Combobox type="primary" filled placeholder="Primary filled" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
  <Grid>
    <Combobox type="secondary" filled placeholder="Secondary filled" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
  <Grid>
    <Combobox type="success" filled placeholder="Success filled" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
  <Grid>
    <Combobox type="warning" filled placeholder="Warning filled" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
  <Grid>
    <Combobox type="error" filled placeholder="Error filled" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
  <Grid>
    <Combobox type="info" filled placeholder="Info filled" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
  <Grid>
    <Combobox type="primary" light placeholder="Primary light" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
  <Grid>
    <Combobox type="secondary" light placeholder="Secondary light" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
  <Grid>
    <Combobox type="success" light placeholder="Success light" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
  <Grid>
    <Combobox type="warning" light placeholder="Warning light" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
  <Grid>
    <Combobox type="error" light placeholder="Error light" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
  <Grid>
    <Combobox type="info" light placeholder="Info light" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
  <Grid>
    <Combobox type="primary" ghost placeholder="Primary ghost" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
  <Grid>
    <Combobox type="secondary" ghost placeholder="Secondary ghost" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
  <Grid>
    <Combobox type="success" ghost placeholder="Success ghost" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
  <Grid>
    <Combobox type="warning" ghost placeholder="Warning ghost" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
  <Grid>
    <Combobox type="error" ghost placeholder="Error ghost" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
  <Grid>
    <Combobox type="info" ghost placeholder="Info ghost" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
  <Grid>
    <Combobox type="primary" subtle placeholder="Primary subtle" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
  <Grid>
    <Combobox type="secondary" subtle placeholder="Secondary subtle" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
  <Grid>
    <Combobox type="success" subtle placeholder="Success subtle" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
  <Grid>
    <Combobox type="warning" subtle placeholder="Warning subtle" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
  <Grid>
    <Combobox type="error" subtle placeholder="Error subtle" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
  <Grid>
    <Combobox type="info" subtle placeholder="Info subtle" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Variants"
  desc="Use `filled`, `light`, `ghost` or `subtle` with a `type` to change the surface of the field."
  scope={{ Combobox, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Combobox type="primary" filled placeholder="Primary filled" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
  <Grid>
    <Combobox type="secondary" filled placeholder="Secondary filled" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
  <Grid>
    <Combobox type="success" filled placeholder="Success filled" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
  <Grid>
    <Combobox type="warning" filled placeholder="Warning filled" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
  <Grid>
    <Combobox type="error" filled placeholder="Error filled" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
  <Grid>
    <Combobox type="info" filled placeholder="Info filled" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
  <Grid>
    <Combobox type="primary" light placeholder="Primary light" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
  <Grid>
    <Combobox type="secondary" light placeholder="Secondary light" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
  <Grid>
    <Combobox type="success" light placeholder="Success light" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
  <Grid>
    <Combobox type="warning" light placeholder="Warning light" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
  <Grid>
    <Combobox type="error" light placeholder="Error light" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
  <Grid>
    <Combobox type="info" light placeholder="Info light" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
  <Grid>
    <Combobox type="primary" ghost placeholder="Primary ghost" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
  <Grid>
    <Combobox type="secondary" ghost placeholder="Secondary ghost" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
  <Grid>
    <Combobox type="success" ghost placeholder="Success ghost" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
  <Grid>
    <Combobox type="warning" ghost placeholder="Warning ghost" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
  <Grid>
    <Combobox type="error" ghost placeholder="Error ghost" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
  <Grid>
    <Combobox type="info" ghost placeholder="Info ghost" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
  <Grid>
    <Combobox type="primary" subtle placeholder="Primary subtle" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
  <Grid>
    <Combobox type="secondary" subtle placeholder="Secondary subtle" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
  <Grid>
    <Combobox type="success" subtle placeholder="Success subtle" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
  <Grid>
    <Combobox type="warning" subtle placeholder="Warning subtle" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
  <Grid>
    <Combobox type="error" subtle placeholder="Error subtle" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
  <Grid>
    <Combobox type="info" subtle placeholder="Info subtle" options={[{ value: "react" }, { value: "vue" }]} />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Disabled"
  desc="A disabled Combobox cannot be focused."
  scope={{ Combobox, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Combobox
      aria-label="Country"
      disabled
      options={[{ value: 'br', label: 'Brazil' }]}
    />
  </Grid>
</Grid.Container>
`}
/>

<Attributes edit="/content/docs/components/combobox.mdx">
<Attributes.Title>Combobox.Props</Attributes.Title>

| Attribute         | Description                                                | Type                                                | Accepted values                                                            | Default                    |
| ----------------- | ---------------------------------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------------- | -------------------------- |
| **options**       | the options to choose from                                 | `ComboboxOption[]`                                  | [ComboboxOption](#comboboxoption)                                          | -                          |
| **value**         | selected value, to control the component                   | `string` / `null`                                   | -                                                                          | -                          |
| **initialValue**  | selected value at the start                                | `string` / `null`                                   | -                                                                          | `null`                     |
| **onChange**      | called with the chosen value, or `null` when it is cleared | <Code>(value: string &#124; null) =&gt; void</Code> | -                                                                          | -                          |
| **onInputChange** | called with the text while the user types                  | `(text: string) => void`                            | -                                                                          | -                          |
| **filter**        | decides which options match the text                       | `(option, text) => boolean`                         | -                                                                          | contains, case insensitive |
| **placeholder**   | text shown when the input is empty                         | `string`                                            | -                                                                          | -                          |
| **emptyText**     | text shown when no option matches                          | `string`                                            | -                                                                          | `No results`               |
| **disabled**      | disable the component                                      | `boolean`                                           | -                                                                          | `false`                    |
| **rounded**       | round the corners                                          | `boolean`                                           | -                                                                          | `false`                    |
| **filled**        | filled variant                                             | `boolean`                                           | -                                                                          | `false`                    |
| **light**         | light variant                                              | `boolean`                                           | -                                                                          | `false`                    |
| **ghost**         | outline variant                                            | `boolean`                                           | -                                                                          | `false`                    |
| **subtle**        | subtle variant                                             | `boolean`                                           | -                                                                          | `false`                    |
| **type**          | color of the field                                         | `NormalTypes`                                       | `'default', 'primary', 'secondary', 'success', 'warning', 'error', 'info'` | `default`                  |
| **rounded**       | round the corners                                          | `boolean`                                           | -                                                                          | `false`                    |
| **filled**        | filled variant                                             | `boolean`                                           | -                                                                          | `false`                    |
| **light**         | light variant                                              | `boolean`                                           | -                                                                          | `false`                    |
| **ghost**         | outline variant                                            | `boolean`                                           | -                                                                          | `false`                    |
| **subtle**        | subtle variant                                             | `boolean`                                           | -                                                                          | `false`                    |
| ...               | native props, passed to the input                          | `InputHTMLAttributes`                               | `'aria-label', 'name', 'id', ...`                                          | -                          |

<Attributes.Title>ComboboxOption</Attributes.Title>

```ts
type ComboboxOption = {
  value: string
  label?: string // shown in the list and in the input, `value` when missing
  disabled?: boolean
}
```

<Attributes.Title>Ref</Attributes.Title>

The `ref` points at the `input`.

<Attributes.Title>Accessibility</Attributes.Title>

The input has `role="combobox"` and points at the active option with `aria-activedescendant`. The list is a `listbox` of `option` elements.

| Key               | Action                                               |
| ----------------- | ---------------------------------------------------- |
| Arrow Down and Up | Open the list, and move between the options          |
| Enter             | Choose the active option                             |
| Escape            | Close the list                                       |
| Tab               | Close the list and restore the text of the selection |

A screen reader hears how many options match while the user types. Give the input a name with `aria-label` or `aria-labelledby`.

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Command, Button, Keyboard, useKeyboard, KeyCode, KeyMod, Grid, Text } from 'core'
import { useState } from 'react'
import { Home, Settings, Search, Plus, UserPlus, CreditCard, LogOut } from '@bolio-ui/icons'

export const meta = {
  title: 'Command',
  description: 'A searchable list of actions, opened with a shortcut.',
  sidebar: 'components',
  group: 'Components',
  index: 57
}

## Command

A searchable list of actions, opened with a shortcut.

<Playground
  title="General"
  desc="Type to filter, use the arrow keys to move and Enter to run the action."
  scope={{ Command, Button, useState, Home, Settings }}
  code={`
() => {
  const [open, setOpen] = useState(false)
  const items = [
    { value: 'home', label: 'Go to home', icon: <Home />, onSelect: () => console.log('home') },
    { value: 'settings', label: 'Open settings', icon: <Settings />, hint: 'G S', onSelect: () => console.log('settings') },
    { value: 'theme', label: 'Switch theme', hint: 'T', onSelect: () => console.log('theme') }
  ]
  return (
    <>
      <Button auto onClick={() => setOpen(true)}>Open command</Button>
      <Command visible={open} onClose={() => setOpen(false)} items={items} />
    </>
  )
}
`}
/>

<Playground
  title="With Shortcut"
  desc="Open it with Cmd+K, or Ctrl+K on Windows and Linux, using `useKeyboard`."
  scope={{ Command, Keyboard, useKeyboard, KeyCode, KeyMod, useState }}
  code={`
() => {
  const [open, setOpen] = useState(false)
  useKeyboard(
    (event) => {
      event.preventDefault()
      setOpen(true)
    },
    [KeyCode.KEY_K, KeyMod.CtrlCmd]
  )
  const items = [
    { value: 'new', label: 'New project', onSelect: () => console.log('new') },
    { value: 'invite', label: 'Invite a teammate', onSelect: () => console.log('invite') }
  ]
  return (
    <>
      <Keyboard command>K</Keyboard>
      <Command visible={open} onClose={() => setOpen(false)} items={items} />
    </>
  )
}
`}
/>

<Playground
  title="App command palette"
  desc="List the actions people reach for most, with a short hint of the shortcut on the right."
  scope={{ Command, Button, Grid, Text, useState, Search, Plus, UserPlus, CreditCard, Settings, LogOut }}
  code={`
() => {
  const [open, setOpen] = useState(false)
  const [last, setLast] = useState('nothing yet')
  const run = (name) => () => setLast(name)
  const items = [
    { value: 'new', label: 'Create project', icon: <Plus />, hint: 'N', onSelect: run('created a project') },
    { value: 'invite', label: 'Invite a teammate', icon: <UserPlus />, onSelect: run('opened the invite form') },
    { value: 'billing', label: 'Go to billing', icon: <CreditCard />, hint: 'G B', onSelect: run('went to billing') },
    { value: 'settings', label: 'Open settings', icon: <Settings />, hint: 'G S', onSelect: run('opened settings') },
    { value: 'signout', label: 'Sign out', icon: <LogOut />, onSelect: run('signed out') }
  ]
  return (
    <>
      <Grid.Container gap={2} alignItems="center">
        <Grid>
          <Button auto icon={<Search />} onClick={() => setOpen(true)}>Search or run a command</Button>
        </Grid>
        <Grid>
          <Text small type="secondary">Last action: {last}</Text>
        </Grid>
      </Grid.Container>
      <Command visible={open} onClose={() => setOpen(false)} items={items} />
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/components/command.mdx">
<Attributes.Title>Command.Props</Attributes.Title>

| Attribute       | Description                         | Type                 | Accepted values | Default                        |
| --------------- | ----------------------------------- | -------------------- | --------------- | ------------------------------ |
| **visible**     | show the palette                    | `boolean`            | -               | -                              |
| **onClose**     | called on Esc, backdrop or selection | `() => void`        | -               | -                              |
| **items**       | actions to list                     | `CommandItem[]`      | -               | -                              |
| **placeholder** | placeholder of the search field     | `string`             | -               | `Type a command or search`     |
| **emptyText**   | shown when nothing matches          | `string`             | -               | `No results. Try another word.` |


<Attributes.Title>CommandItem</Attributes.Title>

```ts
interface CommandItem {
  value: string
  label: string
  icon?: React.ReactNode
  hint?: React.ReactNode
  onSelect?: () => void
}
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Container, Card, Text, Button, Grid } from 'core'

export const meta = {
  title: 'Container',
  description: 'Limit the width of the page and center its content.',
  sidebar: 'components',
  group: 'Components',
  index: 45
}

## Container

Limit the width of the page and center its content. Put a `Row` inside it to build the layout. See the <a href="/docs/guide/page-structure">page structure</a> guide.

<Playground
  desc="The Container has a maximum width and grows with the window until it."
  scope={{ Container, Card, Text }}
  code={`
<Container>
  <Card>
    <Text>The content of the page.</Text>
  </Card>
</Container>
`}
/>

<Playground
  title="Fluid"
  desc="A fluid Container has no maximum width."
  scope={{ Container, Card, Text }}
  code={`
<Container fluid>
  <Card>
    <Text>This one has no maximum width.</Text>
  </Card>
</Container>
`}
/>

<Playground
  title="Centered hero"
  desc="Center a headline and its actions in the page, with the width of the Container as the limit."
  scope={{ Container, Text, Button, Grid }}
  code={`
<Container style={{ textAlign: 'center', padding: '24px 0' }}>
  <Text h2>Build your interface faster</Text>
  <Text p type="secondary">Accessible components, themes that follow your brand and docs you can copy from.</Text>
  <Grid.Container gap={1} justify="center">
    <Grid>
      <Button auto type="primary">Get started</Button>
    </Grid>
    <Grid>
      <Button auto>View on GitHub</Button>
    </Grid>
  </Grid.Container>
</Container>
`}
/>

<Attributes edit="/content/docs/components/container.mdx">
<Attributes.Title>Container.Props</Attributes.Title>

| Attribute     | Description                                                     | Type                  | Accepted values                               | Default |
| ------------- | --------------------------------------------------------------- | --------------------- | --------------------------------------------- | ------- |
| **fluid**     | remove the maximum width                                        | `boolean`             | -                                             | `false` |
| **justify**   | horizontal alignment, when the Container is a flex box          | `string`              | `start`, `end`, `center`, `space-around`, `space-between` | `start` |
| **align**     | vertical alignment, when the Container is a flex box            | `string`              | `top`, `middle`, `bottom`                     | `top`   |
| **component** | the element to render                                           | `keyof JSX.IntrinsicElements` | `'div', 'main', 'section', ...`       | `div`   |
| ...           | native props                                                    | `HTMLAttributes`      | `'id', 'className', ...`                      | -       |

`justify` and `align` only have an effect when you make the Container a flex box, for example with `style={{ display: 'flex' }}`.

<Attributes.Title>Ref</Attributes.Title>

The `ref` points at the root element.

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { ContextMenu, Menu, Card, Text, Grid } from 'core'

export const meta = {
  title: 'Context Menu',
  description:
    'A menu of actions that opens at the pointer when the user right clicks an area.',
  sidebar: 'components',
  group: 'Components',
  index: 67
}

## Context Menu

A menu of actions that opens at the pointer when the user right clicks an area.
It is a <a href="/docs/components/menu">Menu</a> placed at the cursor, so it has
the same items, submenus and keys.

<Playground
  desc="Wrap the area and pass the items in `content`. The area has to be focusable to open the menu from the keyboard, so give it `tabIndex={0}`."
  scope={{ ContextMenu, Menu, Card }}
  code={`
<ContextMenu
  tabIndex={0}
  content={
    <>
      <Menu.Item shortcut="⌘C">Copy</Menu.Item>
      <Menu.Item shortcut="⌘V">Paste</Menu.Item>
      <Menu.Divider />
      <Menu.Item type="error">Delete</Menu.Item>
    </>
  }
>
  <Card bordered style={{ minHeight: 140 }}>
    Right click anywhere in this card
  </Card>
</ContextMenu>
`}
/>

<Playground
  title="Files"
  desc="Give each row its own menu, with a submenu for the less common actions, and tell what happened."
  scope={{ ContextMenu, Menu, Card, Text, Grid }}
  code={`
() => {
  const [last, setLast] = React.useState('Right click a file.')
  const files = ['Contract.pdf', 'Invoice.pdf', 'Photo.png']
  return (
    <Grid.Container direction="column" gap={1}>
      <Grid>
        <Card bordered width="100%">
          {files.map((file) => (
            <ContextMenu
              key={file}
              tabIndex={0}
              style={{ padding: '6px 0' }}
              content={
                <>
                  <Menu.Item onClick={() => setLast('Opened ' + file)}>Open</Menu.Item>
                  <Menu.Item onClick={() => setLast('Renamed ' + file)}>Rename</Menu.Item>
                  <Menu.Sub label="Share">
                    <Menu.Item onClick={() => setLast('Emailed ' + file)}>Email</Menu.Item>
                    <Menu.Item onClick={() => setLast('Copied the link to ' + file)}>Copy link</Menu.Item>
                  </Menu.Sub>
                  <Menu.Divider />
                  <Menu.Item type="error" onClick={() => setLast('Deleted ' + file)}>Delete</Menu.Item>
                </>
              }
            >
              <Text my={0}>{file}</Text>
            </ContextMenu>
          ))}
        </Card>
      </Grid>
      <Grid>
        <Text small type="secondary">{last}</Text>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Playground
  title="Disabled"
  desc="With `disabled`, a right click opens the menu of the browser, as if there were no Context Menu."
  scope={{ ContextMenu, Menu, Card }}
  code={`
<ContextMenu disabled content={<Menu.Item>Never shown</Menu.Item>}>
  <Card bordered>The menu of the browser opens here</Card>
</ContextMenu>
`}
/>

<Attributes edit="/content/docs/components/context-menu.mdx">
<Attributes.Title>ContextMenu.Props</Attributes.Title>

| Attribute           | Description                                                     | Type                         | Accepted values                          | Default |
| ------------------- | --------------------------------------------------------------- | ---------------------------- | ---------------------------------------- | ------- |
| **content**         | the items of the menu                                           | `ReactNode`                  | `Menu.Item`, `Menu.Sub`, `Menu.Divider`, ... | -       |
| **disabled**        | leave the right click to the browser                            | `boolean`                    | -                                        | `false` |
| **onVisibleChange** | called with `true` when the menu opens and `false` when it closes | `(visible: boolean) => void` | -                                        | -       |
| ...                 | native props, passed to the area `div`                          | `HTMLAttributes`             | `'tabIndex', 'id', 'style', ...`         | -       |

<Attributes.Title>Behavior</Attributes.Title>

- • **Position**: the menu opens at the pointer and flips to the other side when there is no room.
- • **Another right click** moves the menu to the new point.
- • **Closing**: choosing an item, Escape, a click outside and a scroll of the page all close it. The focus goes back to the area.
- • **Items** are the ones of <a href="/docs/components/menu">Menu</a>, with the same keys: arrows, Home, End, Enter, Space and the first letters.
- • **onContextMenu**: a handler you pass to the area runs first, and calling `preventDefault` there keeps the menu closed.

<Attributes.Title>Ref</Attributes.Title>

The `ref` points at the area `div`.

<Attributes.Title>Accessibility</Attributes.Title>

The right click is not the only way in. The keyboard opens a context menu with Shift and F10, or with the menu key, on a focused element, and the browser sends the same event with the position of that element. For that, the area, or something inside it, has to be focusable: use `tabIndex={0}` on the area when it has nothing focusable. The menu is a `menu` with `menuitem` children, as in Menu. Touch screens have no right click, so keep a visible way to reach the same actions, like a button with a Menu.

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { DatePicker, Grid, Code } from 'core'

export const meta = {
  title: 'DatePicker',
  description: 'An input to type a date, with a calendar to pick it.',
  sidebar: 'components',
  group: 'Components',
  index: 44
}

## DatePicker

An input to type a date, with a calendar to pick it. The text is a date in the `YYYY-MM-DD` format, which is the same in every country.

<Playground
  desc="Name the field with `aria-label`, or with a visible label."
  scope={{ DatePicker, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <DatePicker aria-label="Birthday" />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Initial value"
  desc="Start with a date using `initialValue`. Use `value` and `onChange` to control it."
  scope={{ DatePicker, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <DatePicker aria-label="Birthday" initialValue={new Date(2026, 0, 15)} />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Min and max"
  desc="A date outside the range cannot be typed, and its day is disabled in the calendar."
  scope={{ DatePicker, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <DatePicker
      aria-label="Trip date"
      initialValue={new Date(2026, 0, 15)}
      min={new Date(2026, 0, 10)}
      max={new Date(2026, 0, 20)}
    />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Variants"
  desc="Use `filled`, `light`, `ghost` or `subtle` with a `type` to change the surface of the field."
  scope={{ DatePicker, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <DatePicker type="primary" filled />
  </Grid>
  <Grid>
    <DatePicker type="secondary" filled />
  </Grid>
  <Grid>
    <DatePicker type="success" filled />
  </Grid>
  <Grid>
    <DatePicker type="warning" filled />
  </Grid>
  <Grid>
    <DatePicker type="error" filled />
  </Grid>
  <Grid>
    <DatePicker type="info" filled />
  </Grid>
  <Grid>
    <DatePicker type="primary" light />
  </Grid>
  <Grid>
    <DatePicker type="secondary" light />
  </Grid>
  <Grid>
    <DatePicker type="success" light />
  </Grid>
  <Grid>
    <DatePicker type="warning" light />
  </Grid>
  <Grid>
    <DatePicker type="error" light />
  </Grid>
  <Grid>
    <DatePicker type="info" light />
  </Grid>
  <Grid>
    <DatePicker type="primary" ghost />
  </Grid>
  <Grid>
    <DatePicker type="secondary" ghost />
  </Grid>
  <Grid>
    <DatePicker type="success" ghost />
  </Grid>
  <Grid>
    <DatePicker type="warning" ghost />
  </Grid>
  <Grid>
    <DatePicker type="error" ghost />
  </Grid>
  <Grid>
    <DatePicker type="info" ghost />
  </Grid>
  <Grid>
    <DatePicker type="primary" subtle />
  </Grid>
  <Grid>
    <DatePicker type="secondary" subtle />
  </Grid>
  <Grid>
    <DatePicker type="success" subtle />
  </Grid>
  <Grid>
    <DatePicker type="warning" subtle />
  </Grid>
  <Grid>
    <DatePicker type="error" subtle />
  </Grid>
  <Grid>
    <DatePicker type="info" subtle />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Variants"
  desc="Use `filled`, `light`, `ghost` or `subtle` with a `type` to change the surface of the field."
  scope={{ DatePicker, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <DatePicker type="primary" filled />
  </Grid>
  <Grid>
    <DatePicker type="secondary" filled />
  </Grid>
  <Grid>
    <DatePicker type="success" filled />
  </Grid>
  <Grid>
    <DatePicker type="warning" filled />
  </Grid>
  <Grid>
    <DatePicker type="error" filled />
  </Grid>
  <Grid>
    <DatePicker type="info" filled />
  </Grid>
  <Grid>
    <DatePicker type="primary" light />
  </Grid>
  <Grid>
    <DatePicker type="secondary" light />
  </Grid>
  <Grid>
    <DatePicker type="success" light />
  </Grid>
  <Grid>
    <DatePicker type="warning" light />
  </Grid>
  <Grid>
    <DatePicker type="error" light />
  </Grid>
  <Grid>
    <DatePicker type="info" light />
  </Grid>
  <Grid>
    <DatePicker type="primary" ghost />
  </Grid>
  <Grid>
    <DatePicker type="secondary" ghost />
  </Grid>
  <Grid>
    <DatePicker type="success" ghost />
  </Grid>
  <Grid>
    <DatePicker type="warning" ghost />
  </Grid>
  <Grid>
    <DatePicker type="error" ghost />
  </Grid>
  <Grid>
    <DatePicker type="info" ghost />
  </Grid>
  <Grid>
    <DatePicker type="primary" subtle />
  </Grid>
  <Grid>
    <DatePicker type="secondary" subtle />
  </Grid>
  <Grid>
    <DatePicker type="success" subtle />
  </Grid>
  <Grid>
    <DatePicker type="warning" subtle />
  </Grid>
  <Grid>
    <DatePicker type="error" subtle />
  </Grid>
  <Grid>
    <DatePicker type="info" subtle />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Disabled"
  desc="Disable the input and the calendar button."
  scope={{ DatePicker, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <DatePicker aria-label="Birthday" disabled />
  </Grid>
</Grid.Container>
`}
/>

<Attributes edit="/content/docs/components/date-picker.mdx">
<Attributes.Title>DatePicker.Props</Attributes.Title>

| Attribute         | Description                                              | Type                                             | Accepted values                                                            | Default       |
| ----------------- | -------------------------------------------------------- | ------------------------------------------------ | -------------------------------------------------------------------------- | ------------- |
| **value**         | selected date, to control the component                  | `Date` / `null`                                  | -                                                                          | -             |
| **initialValue**  | date at the start                                        | `Date` / `null`                                  | -                                                                          | `null`        |
| **onChange**      | called with the date, or `null` when the text is emptied | <Code>(date: Date &#124; null) =&gt; void</Code> | -                                                                          | -             |
| **min**           | first date that can be picked                            | `Date`                                           | -                                                                          | -             |
| **max**           | last date that can be picked                             | `Date`                                           | -                                                                          | -             |
| **locale**        | language of the calendar                                 | `string`                                         | any `Intl` locale                                                          | `en-US`       |
| **weekStartsOn**  | first day of the week in the calendar, 0 is Sunday       | `number`                                         | `0` to `6`                                                                 | `0`           |
| **placeholder**   | text shown when the input is empty                       | `string`                                         | -                                                                          | `YYYY-MM-DD`  |
| **calendarLabel** | name of the calendar button and of its dialog            | `string`                                         | -                                                                          | `Choose date` |
| **disabled**      | disable the component                                    | `boolean`                                        | -                                                                          | `false`       |
| **rounded**       | round the corners                                        | `boolean`                                        | -                                                                          | `false`       |
| **filled**        | filled variant                                           | `boolean`                                        | -                                                                          | `false`       |
| **light**         | light variant                                            | `boolean`                                        | -                                                                          | `false`       |
| **ghost**         | outline variant                                          | `boolean`                                        | -                                                                          | `false`       |
| **subtle**        | subtle variant                                           | `boolean`                                        | -                                                                          | `false`       |
| **type**          | color of the field                                       | `NormalTypes`                                    | `'default', 'primary', 'secondary', 'success', 'warning', 'error', 'info'` | `default`     |
| **rounded**       | round the corners                                        | `boolean`                                        | -                                                                          | `false`       |
| **filled**        | filled variant                                           | `boolean`                                        | -                                                                          | `false`       |
| **light**         | light variant                                            | `boolean`                                        | -                                                                          | `false`       |
| **ghost**         | outline variant                                          | `boolean`                                        | -                                                                          | `false`       |
| **subtle**        | subtle variant                                           | `boolean`                                        | -                                                                          | `false`       |
| ...               | native props, passed to the input                        | `InputHTMLAttributes`                            | `'aria-label', 'name', ...`                                                | -             |

<Attributes.Title>Typing</Attributes.Title>

The value changes only for a real date inside `min` and `max`. `2026-02-31` is not accepted. When the input loses the focus, it goes back to the last valid date. An empty text clears the value.

<Attributes.Title>Ref</Attributes.Title>

The `ref` points at the `input`.

<Attributes.Title>Accessibility</Attributes.Title>

The calendar button has `aria-haspopup="dialog"` and `aria-expanded`. The calendar opens in a dialog with the focus on the day of the current value. Escape closes it and puts the focus back on the button, and picking a day puts the focus on the input. See <a href="/docs/components/calendar">Calendar</a> for the keys.

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { DateRangePicker, Grid, Text, Code } from 'core'

export const meta = {
  title: 'DateRangePicker',
  description:
    'Two inputs to type a start and an end date, with one calendar to pick the range.',
  sidebar: 'components',
  group: 'Components',
  index: 60
}

## DateRangePicker

Two inputs to type a start and an end date, with a calendar of two months to pick the
range. When there is not room for two months, for example on a phone, it shows one. The text is a date in the `YYYY-MM-DD` format, which is the same in every country.

<Playground
  desc="Name the group with `aria-label`. In the calendar, the first click sets the start, the second sets the end and closes it."
  scope={{ DateRangePicker, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <DateRangePicker aria-label="Stay" />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Initial value"
  desc="Start with a range using `initialValue`, a pair of dates. Use `value` and `onChange` to control it."
  scope={{ DateRangePicker, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <DateRangePicker
      aria-label="Stay"
      initialValue={[new Date(2026, 0, 10), new Date(2026, 0, 15)]}
    />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Controlled"
  desc="`onChange` receives the pair `[start, end]`. While the range is being picked, `end` is `null`."
  scope={{ DateRangePicker, Grid, Text }}
  code={`
() => {
  const [range, setRange] = React.useState([null, null])
  const format = (date) => (date ? date.toDateString() : '...')
  return (
    <Grid.Container gap={2} direction="column">
      <Grid>
        <DateRangePicker aria-label="Stay" value={range} onChange={setRange} />
      </Grid>
      <Grid>
        <Text p>From {format(range[0])} to {format(range[1])}.</Text>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Playground
  title="Min and max"
  desc="A date outside the limits cannot be typed, and its day is disabled in the calendar."
  scope={{ DateRangePicker, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <DateRangePicker
      aria-label="Trip dates"
      initialValue={[new Date(2026, 0, 12), new Date(2026, 0, 15)]}
      min={new Date(2026, 0, 10)}
      max={new Date(2026, 0, 20)}
    />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Variants"
  desc="Use `filled`, `light`, `ghost` or `subtle` with a `type` to change the surface of the field."
  scope={{ DateRangePicker, Grid }}
  code={`
<Grid.Container gap={2} direction="column">
  <Grid>
    <DateRangePicker type="primary" filled aria-label="Filled" />
  </Grid>
  <Grid>
    <DateRangePicker type="success" light aria-label="Light" />
  </Grid>
  <Grid>
    <DateRangePicker type="info" ghost rounded aria-label="Ghost" />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Disabled"
  desc="Locks both inputs and the calendar button."
  scope={{ DateRangePicker }}
  code={`
<DateRangePicker disabled aria-label="Stay" />
`}
/>

<Attributes edit="/content/docs/components/date-range-picker.mdx">
<Attributes.Title>DateRangePicker.Props</Attributes.Title>

| Attribute            | Description                                                                 | Type                                                                | Accepted values                                                            | Default        |
| -------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------- | -------------- |
| **value**            | selected range, to control the component                                    | <Code>[Date &#124; null, Date &#124; null]</Code>                   | -                                                                          | -              |
| **initialValue**     | range at the start                                                          | <Code>[Date &#124; null, Date &#124; null]</Code>                   | -                                                                          | `[null, null]` |
| **onChange**         | called with `[start, end]`, with `end` as `null` while the range is picked  | <Code>(range: [Date &#124; null, Date &#124; null]) =&gt; void</Code> | -                                                                        | -              |
| **min**              | first date that can be picked                                               | `Date`                                                              | -                                                                          | -              |
| **max**              | last date that can be picked                                                | `Date`                                                              | -                                                                          | -              |
| **locale**           | language of the calendar                                                    | `string`                                                            | any `Intl` locale                                                          | `en-US`        |
| **weekStartsOn**     | first day of the week in the calendar, 0 is Sunday                          | `number`                                                            | `0` to `6`                                                                 | `0`            |
| **startPlaceholder** | text shown when the start input is empty                                    | `string`                                                            | -                                                                          | `YYYY-MM-DD`   |
| **endPlaceholder**   | text shown when the end input is empty                                      | `string`                                                            | -                                                                          | `YYYY-MM-DD`   |
| **startLabel**       | name of the start input                                                     | `string`                                                            | -                                                                          | `Start date`   |
| **endLabel**         | name of the end input                                                       | `string`                                                            | -                                                                          | `End date`     |
| **calendarLabel**    | name of the calendar button and of its dialog                               | `string`                                                            | -                                                                          | `Choose dates` |
| **disabled**         | disable the component                                                       | `boolean`                                                           | -                                                                          | `false`        |
| **type**             | color of the field                                                          | `NormalTypes`                                                       | `'default', 'primary', 'secondary', 'success', 'warning', 'error', 'info'` | `default`      |
| **rounded**          | round the corners                                                           | `boolean`                                                           | -                                                                          | `false`        |
| **filled**           | filled variant                                                              | `boolean`                                                           | -                                                                          | `false`        |
| **light**            | light variant                                                               | `boolean`                                                           | -                                                                          | `false`        |
| **ghost**            | outline variant                                                             | `boolean`                                                           | -                                                                          | `false`        |
| **subtle**           | subtle variant                                                              | `boolean`                                                           | -                                                                          | `false`        |
| ...                  | native props, passed to the group `div`                                     | `HTMLAttributes`                                                    | `'aria-label', 'id', ...`                                                  | -              |

<Attributes.Title>Typing</Attributes.Title>

Each input changes the range only for a real date inside `min` and `max`. The end cannot come before the start, so that text is not accepted. When an input loses the focus, it goes back to the last valid date. An empty text clears that edge of the range.

<Attributes.Title>Ref</Attributes.Title>

The `ref` points at the group `div`.

<Attributes.Title>Accessibility</Attributes.Title>

The group is named by `aria-label`, and each input has its own name, `Start date` and `End date`, which you can translate with `startLabel` and `endLabel`. The calendar button has `aria-haspopup="dialog"` and `aria-expanded`. The calendar opens in a dialog that shows two months side by side, or one month when there is not room, with the focus on the day of the start. Escape closes it and puts the focus back on the button, and picking the end puts the focus on the end input. See <a href="/docs/components/calendar">Calendar</a> for the keys.

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Description, Code, Grid, Card, Badge } from 'core'

export const meta = {
  title: 'Description',
  description: 'Display brief information with a title and description.',
  sidebar: 'components',
  group: 'Components',
  index: 12
}

## Description

Display brief information with a title and description.

<Playground
  desc="`Description` component contains title and content."
  scope={{ Description, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Description title="Section Title" content="Data about this section." />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="With Component"
  desc="Use in combination with other components."
  scope={{ Description, Code, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Description
      title="Section Title"
      content={
        <p>
          <Code>code</Code> about this section.
        </p>
      }
    />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Account details"
  desc="Lay several `Description` items in a grid to show the fields of a record."
  scope={{ Description, Grid, Card, Badge }}
  code={`
<Card bordered width="100%">
  <Grid.Container gap={2}>
    <Grid xs={12} md={6}>
      <Description title="Owner" content="Ada Lovelace" />
    </Grid>
    <Grid xs={12} md={6}>
      <Description title="Email" content="ada@example.com" />
    </Grid>
    <Grid xs={12} md={6}>
      <Description title="Plan" content={<Badge type="primary">Pro</Badge>} />
    </Grid>
    <Grid xs={12} md={6}>
      <Description title="Renews on" content="Nov 3, 2026" />
    </Grid>
  </Grid.Container>
</Card>
`}
/>

<Attributes edit="/content/docs/components/description.mdx">
<Attributes.Title>Description.Props</Attributes.Title>

| Attribute   | Description  | Type                   | Accepted values | Default |
| ----------- | ------------ | ---------------------- | --------------- | ------- |
| **title**   | title text   | `ReactNode` / `string` | -               | -       |
| **content** | title text   | `ReactNode` / `string` | -               | -       |
| ...         | native props | `HTMLAttributes`       | -               | -       |

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Display, Code, Snippet, Image, Grid } from 'core'

export const meta = {
  title: 'Display',
  description:
    'To display important information or images in a central alignment.',
  sidebar: 'components',
  group: 'Components',
  index: 13
}

## Display

To display important information or images in a central alignment.

<Playground
  title="General"
  desc="Describe the main part with a paragraph."
  scope={{ Display, Image, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid md={12}>
    <Display shadow caption="Make your development more creative and dynamic with amazing tools for React. 🥷🏼">
      <Image height="200px" src="https://images.pexels.com/photos/1779487/pexels-photo-1779487.jpeg" />
    </Display>
  </Grid>
</Grid.Container>  
`}
/>

<Playground
  title="With Code"
  desc="Show multiline code blocks."
  scope={{ Display, Code, Grid }}
  code={`
() => {
  const codes = \`{
  "build": {
    "env": {
      "VARIABLE": "ENV_SECRET"
    }
  }
}\`
  return (
    <Grid.Container gap={2}>
      <Grid md={12}>
        <Display width="500px" caption="Application's build with a defined secret environment variable.">
          <Code block>{codes}</Code>
        </Display>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Playground
  title="With Snippet"
  desc="Show shell codes."
  scope={{ Display, Snippet, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid md={12}>
    <Display width="500px" caption="Run this command to install the library.">
      <Snippet type="dark" text="yarn add @bolio-ui/core" />
    </Display>
  </Grid>
</Grid.Container> 
`}
/>

<Playground
  title="Component Caption"
  desc="Use component on `caption` prop."
  scope={{ Display, Code, Image, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid md={12}>
    <Display shadow caption={<p>Browse <Code>bolio-ui.com.br</Code> for more information.</p>}>
      <Image width="650px" height="297px" src="https://images.pexels.com/photos/1779487/pexels-photo-1779487.jpeg" />
    </Display>
  </Grid>
</Grid.Container>
`}
/>

<Attributes edit="/content/docs/components/display.mdx">
<Attributes.Title>Display.Props</Attributes.Title>

| Attribute   | Description                   | Type                   | Accepted values | Default |
| ----------- | ----------------------------- | ---------------------- | --------------- | ------- |
| **caption** | description for display block | `ReactNode` / `string` | -               | -       |
| **shadow**  | show shadow                   | `boolean`              | -               | `false` |
| ...         | native props                  | `HTMLAttributes`       | -               | -       |

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Layout, Playground, Attributes } from 'src/components'
import { Divider, Text, Grid } from 'core'

export const meta = {
  title: 'Divider',
  description: 'A divider line separates different content.',
  sidebar: 'components',
  group: 'Components',
  index: 14
}

## Divider

A divider line separates different content.

<Playground
  desc="The basic `Divider` usage."
  scope={{ Divider, Text, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Text>
      React makes it painless to create interactive UIs. Design simple views
      for each state in your application, and React will efficiently update
      and render just the right components when your data changes.
    </Text>
    <Divider />
    <Text>
      Declarative views make your code more predictable and easier to debug.
    </Text>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="With Text"
  desc="Display text or components in diriver."
  scope={{ Divider, Text, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Text>
      React makes it painless to create interactive UIs. Design simple views
      for each state in your application, and React will efficiently update
      and render just the right components when your data changes.
    </Text>
    <Divider>A Simple Component</Divider>
    <Text>
      React components implement a render() method that takes input data and
      returns what to display. This example uses an XML-like syntax called
      JSX. Input data that is passed into the component can be accessed by
      render() via this.props.
    </Text>
    <Divider align="start">A Stateful Component</Divider>
    <Text>
      In addition to taking input data (accessed via this.props), a component
      can maintain internal state data (accessed via this.state). When a
      component’s state data changes, the rendered markup will be updated by
      re-invoking render().
    </Text>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Space"
  desc="Custom size of white space around components."
  scope={{ Divider, Text, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Text>
      React makes it painless to create interactive UIs. Design simple views
      for each state in your application, and React will efficiently update
      and render just the right components when your data changes.
    </Text>
    <Divider h={5}>A Simple Component</Divider>
    <Text>
      React components implement a render() method that takes input data and
      returns what to display. This example uses an XML-like syntax called
      JSX. Input data that is passed into the component can be accessed by
      render() via this.props.
    </Text>
    <Divider my={5} h={5}>
      A Stateful Component
    </Divider>
    <Text>
      In addition to taking input data (accessed via this.props), a component
      can maintain internal state data (accessed via this.state). When a
      component’s state data changes, the rendered markup will be updated by
      re-invoking render().
    </Text>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Types"
  desc="Different state."
  scope={{ Divider, Text, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Text>
      React makes it painless to create interactive UIs. Design simple views
      for each state in your application, and React will efficiently update
      and render just the right components when your data changes.
    </Text>
    <Divider h={3} type="success">
      A Simple Component
    </Divider>
    <Text>
      React components implement a render() method that takes input data and
      returns what to display. This example uses an XML-like syntax called
      JSX. Input data that is passed into the component can be accessed by
      render() via this.props.
    </Text>
    <Divider h={3} my={3} type="warning">
      A Stateful Component
    </Divider>
    <Text>
      In addition to taking input data (accessed via this.props), a component
      can maintain internal state data (accessed via this.state). When a
      component’s state data changes, the rendered markup will be updated by
      re-invoking render().
    </Text>
  </Grid>
</Grid.Container>
`}
/>

<Attributes edit="/content/docs/components/divider.mdx">
<Attributes.Title>Divider.Props</Attributes.Title>

| Attribute | Description       | Type                          | Accepted values                  | Default   |
| --------- | ----------------- | ----------------------------- | -------------------------------- | --------- |
| **type**  | type of divier    | [DividerTypes](#dividertypes) | -                                | `default` |
| **align** | alignment of text | [DividerAlign](#divideralign) | -                                | `center`  |
| ...       | native props      | `HTMLAttributes`              | `'id', 'name', 'className', ...` | -         |

<Attributes.Title>DividerTypes</Attributes.Title>

```ts
type DividerTypes =
  | 'default'
  | 'primary'
  | 'secondary'
  | 'success'
  | 'warning'
  | 'error'
  | 'info'
  | 'dark'
  | 'lite'
```

<Attributes.Title>DividerAlign</Attributes.Title>

```ts
type DividerAlign = 'center' | 'start' | 'left' | 'end' | 'right'
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Dot, Grid, Card } from 'core'

export const meta = {
  title: 'Dot',
  description: 'Display an indicator of standardization status.',
  sidebar: 'components',
  group: 'Components',
  index: 15
}

## Dot

Display an indicator of standardization status.

<Playground
  desc="The basic `Dot` usage."
  scope={{ Dot, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Dot />
  </Grid>
  <Grid>
    <Dot type="primary" />
  </Grid>
  <Grid>
    <Dot type="secondary" />
  </Grid>
  <Grid>
    <Dot type="success" />
  </Grid>
  <Grid>
    <Dot type="warning" />
  </Grid>
  <Grid>
    <Dot type="error" />
  </Grid>
  <Grid>
    <Dot type="info" />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="With Text"
  desc="Show different types of content using `Text`."
  scope={{ Dot, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Dot>Canceled</Dot>
  </Grid>
  <Grid>
    <Dot type="primary">Primary</Dot>
  </Grid>
  <Grid>
    <Dot type="secondary">Secondary</Dot>
  </Grid>
  <Grid>
    <Dot type="success">Ready</Dot>
  </Grid>
  <Grid>
    <Dot type="warning">Warning</Dot>
  </Grid>
  <Grid>
    <Dot type="error">Error</Dot>
  </Grid>
  <Grid>
    <Dot type="info">Info</Dot>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Service status"
  desc="Use the type of the `Dot` to show the state at a glance, and put the detail in the text."
  scope={{ Dot, Grid, Card }}
  code={`
<Card bordered width="100%">
  <Grid.Container direction="column" gap={1}>
    {[
      ['success', 'API', 'Operational'],
      ['warning', 'Webhooks', 'Delayed by 4 minutes'],
      ['error', 'Payments', 'Down since 09:12']
    ].map(([type, name, state]) => (
      <Grid key={name}>
        <Dot type={type}>{name}: {state}</Dot>
      </Grid>
    ))}
  </Grid.Container>
</Card>
`}
/>

<Attributes edit="/content/docs/components/dot.mdx">
<Attributes.Title>Dot.Props</Attributes.Title>

| Attribute | Description  | Type             | Accepted values       | Default   |
| --------- | ------------ | ---------------- | --------------------- | --------- |
| **type**  | dot type     | `DotTypes`       | [DotTypes](#dottypes) | `default` |
| ...       | native props | `HTMLAttributes` | -                     | -         |

<Attributes.Title>DotTypes</Attributes.Title>

```ts
type DotTypes =
  | 'default'
  | 'primary'
  | 'secondary'
  | 'success'
  | 'warning'
  | 'error'
  | 'info'
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Drawer, Button, Grid, Input, Spacer } from 'core'

export const meta = {
  title: 'Drawer',
  description: 'An interactive element fixed to the edge of the screen.',
  sidebar: 'components',
  group: 'Components',
  index: 16
}

## Drawer

An interactive element fixed to the edge of the screen.

<Playground
  desc="Basic usage."
  scope={{ Drawer, Button, Grid }}
  code={`
() => {
  const [state, setState] = React.useState(false)
  return (
    <Grid.Container gap={2}>
      <Grid>
        <Button auto onClick={() => setState(true)}>
          Show Drawer
        </Button>
        <Drawer
          visible={state}
          onClose={() => setState(false)}
          placement="right"
        >
          <Drawer.Title>Drawer</Drawer.Title>
          <Drawer.Subtitle>Example of a drawer</Drawer.Subtitle>
          <Drawer.Content>
            <p>Demo content for the drawer.</p>
          </Drawer.Content>
        </Drawer>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Playground
  title="Placement"
  desc="Change the placement of the drawer with the `placement` prop."
  scope={{ Drawer, Button, Grid }}
  code={`
() => {
  const [state, setState] = React.useState(false)
  const [placement, setPlacement] = React.useState('')
  const open = (text) => {
    setPlacement(text)
    setState(true)
  }
  return (
    <Grid.Container gap={2}>
      <Grid>
        <Button auto onClick={() => open('top')} mr="10px">
          Top
        </Button>
      </Grid>
      <Grid>
        <Button auto onClick={() => open('right')} mr="10px">
          Right
        </Button>
      </Grid>
      <Grid>
        <Button auto onClick={() => open('bottom')} mr="10px">
          Bottom
        </Button>
      </Grid>
      <Grid>
        <Button auto onClick={() => open('left')}>
          Left
        </Button>
      </Grid>
      <Drawer
        visible={state}
        onClose={() => setState(false)}
        placement={placement}
      >
        <Drawer.Title>Drawer</Drawer.Title>
        <Drawer.Subtitle>Example of a drawer</Drawer.Subtitle>
        <Drawer.Content>
          <p>Demo content for the drawer.</p>
        </Drawer.Content>
      </Drawer>
    </Grid.Container>
  )
}
`}
/>

<Playground
  title="Edit profile"
  desc="A form in a Drawer keeps the page behind it in view. Put the confirm button first and a way out next to it."
  scope={{ Drawer, Button, Grid, Input, Spacer }}
  code={`
() => {
  const [open, setOpen] = React.useState(false)
  return (
    <>
      <Button auto onClick={() => setOpen(true)}>Edit profile</Button>
      <Drawer visible={open} onClose={() => setOpen(false)} placement="right">
        <Drawer.Title>Edit profile</Drawer.Title>
        <Drawer.Subtitle>Changes show on your public page.</Drawer.Subtitle>
        <Drawer.Content>
          <Input floating width="100%" initialValue="Ada Lovelace">Name</Input>
          <Spacer h={1} />
          <Input floating width="100%" initialValue="ada@example.com">Email</Input>
          <Spacer h={1.5} />
          <Grid.Container gap={1}>
            <Grid>
              <Button auto type="primary" onClick={() => setOpen(false)}>Save changes</Button>
            </Grid>
            <Grid>
              <Button auto onClick={() => setOpen(false)}>Cancel</Button>
            </Grid>
          </Grid.Container>
        </Drawer.Content>
      </Drawer>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/components/drawer.mdx">
<Attributes.Title>Drawer.Props</Attributes.Title>

| Attribute                | Description                      | Type                                | Accepted values            | Default |
| ------------------------ | -------------------------------- | ----------------------------------- | -------------------------- | ------- |
| **visible**              | open or close                    | `boolean`                           | -                          | `false` |
| **onClose**              | close event                      | `() => void`                        | -                          | -       |
| **onContentClick**       | event from modal content         | `(e: MouseEvent) => void`           | -                          | -       |
| **wrapClassName**        | className of the drawer dialog   | `string`                            | -                          | -       |
| **keyboard**             | press Esc to close drawer        | `boolean`                           | -                          | `true`  |
| **disableBackdropClick** | click background and don't close | `boolean`                           | -                          | `false` |
| **placement**            | position of the drawer           | [DrawerPlacement](#drawerplacement) | -                          | `right` |
| ...                      | native props                     | `HTMLAttributes`                    | `'name', 'className', ...` | -       |

<Attributes.Title>Drawer.Title.Props</Attributes.Title>

| Attribute | Description  | Type             | Accepted values          | Default |
| --------- | ------------ | ---------------- | ------------------------ | ------- |
| ...       | native props | `HTMLAttributes` | `'id', 'className', ...` | -       |

<Attributes.Title>Drawer.Subtitle.Props</Attributes.Title>

| Attribute | Description  | Type             | Accepted values          | Default |
| --------- | ------------ | ---------------- | ------------------------ | ------- |
| ...       | native props | `HTMLAttributes` | `'id', 'className', ...` | -       |

<Attributes.Title>Drawer.Content.Props</Attributes.Title>

| Attribute | Description  | Type             | Accepted values          | Default |
| --------- | ------------ | ---------------- | ------------------------ | ------- |
| ...       | native props | `HTMLAttributes` | `'id', 'className', ...` | -       |

<Attributes.Title>DrawerPlacement</Attributes.Title>

```ts
type DrawerPlacement = 'top' | 'bottom' | 'right' | 'left'
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Dropzone, Grid, Text, Code } from 'core'

export const meta = {
  title: 'Dropzone',
  description:
    'An area to drop files or click to choose them, with limits for type, size and number.',
  sidebar: 'components',
  group: 'Components',
  index: 62
}

## Dropzone

An area to drop files or click to choose them. It checks the type, the size and
the number of files, and hands them to `onDrop`. Uploading and listing the files
is up to you.

<Playground
  desc="Pass the files you want to keep from `onDrop`, which receives the ones that passed and the ones that did not."
  scope={{ Dropzone, Grid, Text }}
  code={`
() => {
  const [names, setNames] = React.useState([])
  return (
    <Grid.Container gap={2} direction="column">
      <Grid>
        <Dropzone multiple onDrop={(accepted) => setNames(accepted.map((file) => file.name))} />
      </Grid>
      <Grid>
        <Text p>{names.length ? names.join(', ') : 'No files yet.'}</Text>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Playground
  title="Limits and rejected files"
  desc="`accept`, `maxSize` and `maxFiles` decide what passes. A rejected file comes back with the `reason`: `file-type`, `file-too-large` or `too-many-files`."
  scope={{ Dropzone, Grid, Text }}
  code={`
() => {
  const [result, setResult] = React.useState('Drop up to 2 images of 1 MB.')
  const onDrop = (accepted, rejected) =>
    setResult(
      accepted.length + ' accepted. ' +
        rejected.map((item) => item.file.name + ': ' + item.reason).join('; ')
    )
  return (
    <Grid.Container gap={2} direction="column">
      <Grid>
        <Dropzone multiple accept="image/*" maxSize={1024 * 1024} maxFiles={2} onDrop={onDrop}>
          Drop up to 2 images of 1 MB
        </Dropzone>
      </Grid>
      <Grid>
        <Text p>{result}</Text>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Playground
  title="Thumbnails"
  desc="With `thumbnails`, the accepted files stay below the area as tiles. Each tile has the format of the file, a preview when it is an image, a file icon when it is not, and a button to remove it."
  scope={{ Dropzone }}
  code={`
<Dropzone thumbnails multiple maxFiles={6} accept="image/*,.pdf,.csv,.zip">
  Drop images, PDFs, CSVs or ZIPs
</Dropzone>
`}
/>

<Playground
  title="Custom content"
  desc="The children replace the default text. Name the area with them, or with `aria-label`."
  scope={{ Dropzone, Text }}
  code={`
<Dropzone accept=".pdf">
  <Text b>Upload your contract</Text>
  <Text small>PDF, one file</Text>
</Dropzone>
`}
/>

<Playground
  title="Disabled"
  desc="A disabled area ignores drops and cannot open the file picker."
  scope={{ Dropzone }}
  code={`
<Dropzone disabled>Uploads are off</Dropzone>
`}
/>

<Attributes edit="/content/docs/components/dropzone.mdx">
<Attributes.Title>Dropzone.Props</Attributes.Title>

| Attribute    | Description                                                              | Type                                                      | Accepted values                               | Default |
| ------------ | ------------------------------------------------------------------------ | --------------------------------------------------------- | --------------------------------------------- | ------- |
| **onDrop**   | called with the accepted files and the rejected ones, from a drop or from the picker | <Code>(accepted: File[], rejected: FileRejection[]) =&gt; void</Code> | -                         | -       |
| **accept**   | types that pass, in the format of the `accept` of a file input           | `string`                                                  | `'.pdf', 'image/*', 'image/png', ...`, separated by commas | -       |
| **multiple** | accepts more than one file                                               | `boolean`                                                 | -                                             | `false` |
| **maxSize**  | largest size of a file, in bytes                                         | `number`                                                  | -                                             | -       |
| **maxFiles** | most files in one drop, with `multiple`                                  | `number`                                                  | -                                             | -       |
| **thumbnails** | keeps the accepted files and shows them as tiles below the area | `boolean`                                             | -                                             | `false` |
| **value**    | the files shown with `thumbnails`, to control them                       | `File[]`                                                  | -                                             | -       |
| **onChange** | called with the whole list when a file is added or removed, with `thumbnails` | <Code>(files: File[]) =&gt; void</Code>              | -                                             | -       |
| **removeLabel** | name of the remove button of a file, for screen readers               | <Code>(file: File) =&gt; string</Code>                    | -                                             | `Remove <name>` |
| **disabled** | ignores drops and blocks the picker                                      | `boolean`                                                 | -                                             | `false` |
| ...          | native props, passed to the `input`                                      | `InputHTMLAttributes`                                     | `'name', 'aria-label', 'required', ...`       | -       |

<Attributes.Title>Rejected files</Attributes.Title>

`rejected` is a list of `{ file, reason }`. Each file gets only the first reason that applies, checked in this order:

- • **file-type**: the file does not match `accept`.
- • **file-too-large**: the file is bigger than `maxSize`.
- • **too-many-files**: there are already as many accepted files as the limit, which is `1` without `multiple` and `maxFiles` with it.

`onDrop` is called on every drop or choice, even when every file was rejected. The file picker is cleared after each choice, so the same file can be chosen again.

<Attributes.Title>Thumbnail behavior</Attributes.Title>

- • **Format**: the tile shows the extension of the file in capitals, like `PNG` or `PDF`. A file without an extension uses the subtype of its type.
- • **Preview**: only images are shown as they are. Other formats, like PDF, CSV or ZIP, cannot be drawn by the browser, so they get a file icon.
- • **Limits**: with `multiple`, new files are added to the ones already there, and `maxFiles` counts all of them. Without it, a new file replaces the current one.
- • **Control**: the list is kept for you. Use `value` and `onChange` to own it, for example to clear it after an upload. `onDrop` is still called on every drop with the files of that drop.

<Attributes.Title>Ref</Attributes.Title>

The `ref` points at the file `input`. Extra props go to the `input` too, while `className` and `style` go to the wrapper of the area and the thumbnails.

<Attributes.Title>Accessibility</Attributes.Title>

The area is a label around a native file input, so it is reached with Tab and opened with Enter or Space, and its content names the input. A dragged file highlights the area, but the drag is only a shortcut: the picker does the same for people who use the keyboard or a screen reader. The thumbnails are a list, each with the name of the file as text and a remove button named after it, and the preview of an image is decorative. Show the result of `onDrop` as text on the page, for example the rejected files and why.

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { EmptyState, Button, Card, Grid } from 'core'
import { Inbox, Search, FolderPlus, AlertCircle } from '@bolio-ui/icons'

export const meta = {
  title: 'Empty State',
  description: 'Explain an empty area and how to leave it.',
  sidebar: 'components',
  group: 'Components',
  index: 54
}

## Empty State

Explain an empty area and how to leave it.

<Playground
  title="General"
  desc="Say what is missing and offer the next step with `action`."
  scope={{ EmptyState, Button, Inbox }}
  code={`
<EmptyState
  icon={<Inbox />}
  title="No messages yet"
  description="Messages from your team show up here. Invite someone to start a conversation."
  action={<Button type="primary" auto>Invite a teammate</Button>}
/>
`}
/>

<Playground
  title="In a Card"
  desc="Inside a `Card`, for a list or table that has no rows."
  scope={{ EmptyState, Button, Card, Search }}
  code={`
<Card bordered width="100%">
  <EmptyState
    icon={<Search />}
    title="No results for “invoice”"
    description="Check the spelling or clear the filters to see every document."
    action={<Button auto>Clear filters</Button>}
  />
</Card>
`}
/>

<Playground
  title="Onboarding"
  desc="On a first visit, offer the main action and a second way in."
  scope={{ EmptyState, Button, Card, Grid, FolderPlus }}
  code={`
<Card bordered width="100%">
  <EmptyState
    icon={<FolderPlus />}
    title="Create your first project"
    description="Projects keep your files, members and deploys in one place. It takes under a minute."
    action={
      <Grid.Container gap={1} justify="center">
        <Grid>
          <Button type="primary" auto>New project</Button>
        </Grid>
        <Grid>
          <Button auto>Import from GitHub</Button>
        </Grid>
      </Grid.Container>
    }
  />
</Card>
`}
/>

<Playground
  title="Error"
  desc="When a request fails, say what happened and what to do next."
  scope={{ EmptyState, Button, Card, AlertCircle }}
  code={`
<Card bordered width="100%">
  <EmptyState
    icon={<AlertCircle />}
    title="We could not load your invoices"
    description="Check your connection and try again. Your data is safe."
    action={<Button auto>Try again</Button>}
  />
</Card>
`}
/>

<Attributes edit="/content/docs/components/empty-state.mdx">
<Attributes.Title>EmptyState.Props</Attributes.Title>

| Attribute       | Description                    | Type             | Accepted values | Default |
| --------------- | ------------------------------ | ---------------- | --------------- | ------- |
| **title**       | what is empty                  | `ReactNode`      | -               | -       |
| **description** | how to leave the empty state   | `ReactNode`      | -               | -       |
| **icon**        | icon above the title           | `ReactNode`      | -               | -       |
| **action**      | usually a `Button`             | `ReactNode`      | -               | -       |
| ...             | native props                   | `HTMLAttributes` | -               | -       |


</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Card, Grid, Fieldset, Button, Text, Divider } from 'core'

export const meta = {
  title: 'Fieldset',
  description: 'Display a collection of related information in a single unit.',
  sidebar: 'components',
  group: 'Components',
  index: 17
}

## Fieldset

Display a collection of related information in a single unit.

<Playground
  title="General"
  desc="Add custom buttons."
  scope={{ Fieldset, Button, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Fieldset>
      <Fieldset.Title>Try React </Fieldset.Title>
      <Fieldset.Subtitle>
        React has been designed from the start for gradual adoption, and you
        can use as little or as much React as you need. Whether you want to
        get a taste of React, add some interactivity to a simple HTML page, or
        start a complex React-powered app, the links in this section will help
        you get started.
      </Fieldset.Subtitle>
      <Fieldset.Footer>
        Try React
        <Button auto scale={1 / 3} font="12px">
          Confirm
        </Button>
      </Fieldset.Footer>
    </Fieldset>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Custom Text"
  desc="Representation in different situations."
  scope={{ Fieldset, Button, Text, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Fieldset>
      <Fieldset.Title>Add React to a Website </Fieldset.Title>
      <Fieldset.Subtitle>
        You can add React to an HTML page in one minute. You can then either
        gradually expand its presence, or keep it contained to a few dynamic
        widgets
      </Fieldset.Subtitle>
      <Fieldset.Footer>
        <Text type="error">An error has occurred.</Text>
        <Button auto scale={1 / 3} type="error" font="12px">
          Cancel
        </Button>
      </Fieldset.Footer>
    </Fieldset>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Tabs"
  desc="Show multiple Fieldset."
  scope={{ Fieldset, Button, Grid }}
  code={`
() => {
  const handler = (v) => console.log(v)
  return (
    <Grid.Container gap={2}>
      <Grid>
        <Fieldset.Group value="create new react app" onChange={handler}>
          <Fieldset label="create new react app">
            <Fieldset.Title>Create a New React App</Fieldset.Title>
            <Fieldset.Subtitle>
              When starting a React project, a simple HTML page with script tags
              might still be the best option. It only takes a minute to set up!
            </Fieldset.Subtitle>
            <Fieldset.Footer>
              Create a New React App
              <Button auto scale={1 / 3} font="12px">
                Functions
              </Button>
            </Fieldset.Footer>
          </Fieldset>
          <Fieldset label="learn react">
            <Fieldset.Title>Learn React</Fieldset.Title>
            <Fieldset.Subtitle>
              People come to React from different backgrounds and with different
              learning styles. Whether you prefer a more theoretical or a
              practical approach, we hope you’ll find this section helpful.
            </Fieldset.Subtitle>
            <Fieldset.Footer>
              Learn React
              <Button auto scale={1 / 3} font="12px">
                Functions
              </Button>
            </Fieldset.Footer>
          </Fieldset>
          <Fieldset label="first examples">
            <Fieldset.Title>First Examples</Fieldset.Title>
            <Fieldset.Subtitle>
              The React homepage contains a few small React examples with a live
              editor. Even if you don’t know anything about React yet, try
              changing their code and see how it affects the result.
            </Fieldset.Subtitle>
            <Fieldset.Footer>
              First Examples
              <Button auto scale={1 / 3} font="12px">
                Functions
              </Button>
            </Fieldset.Footer>
          </Fieldset>
        </Fieldset.Group>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Playground
  title="With Divider"
  desc="Use `Divider` and `Fieldset.Content` to combine different layouts."
  scope={{ Fieldset, Divider, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Fieldset>
      <Fieldset.Content style={{ paddingTop: '10pt', paddingBottom: '10pt' }}>
        <h4>React</h4>
      </Fieldset.Content>
      <Divider my={0} />
      <Fieldset.Content>
        <Fieldset.Title>For Beginners</Fieldset.Title>
        <p>
          If you feel that the React documentation goes at a faster pace than
          you’re comfortable with, check out this overview of React by Tania
          Rascia. It introduces the most important React concepts in a
          detailed, beginner-friendly way. Once you’re done, give the
          documentation another try!
        </p>
      </Fieldset.Content>
      <Fieldset.Footer>
        <small>JavaScript Resources </small>
      </Fieldset.Footer>
    </Fieldset>
  </Grid>
</Grid.Container>
`}
/>

<Attributes edit="/content/docs/components/fieldset.mdx">
<Attributes.Title>Fieldset.Props</Attributes.Title>

| Attribute    | Description                        | Type                     | Accepted values            | Default |
| ------------ | ---------------------------------- | ------------------------ | -------------------------- | ------- |
| **value**    | unique ident value (only in group) | `string`                 | -                          | -       |
| **label**    | group tab text (only in group)     | `string`                 | -                          | -       |
| **title**    | title of fieldset                  | `ReactNode` / `string`   | -                          | -       |
| **subtitle** | subtitle of fieldset               | `ReactNode` / `string`   | -                          | -       |
| ...          | native props                       | `FieldsetHTMLAttributes` | `'name', 'className', ...` | -       |

<Attributes.Title alias="Fieldset.Body">Fieldset.Content.Props</Attributes.Title>

| Attribute | Description  | Type             | Accepted values | Default |
| --------- | ------------ | ---------------- | --------------- | ------- |
| ...       | native props | `HTMLAttributes` | -               | -       |

<Attributes.Title>Fieldset.Footer.Props</Attributes.Title>

| Attribute | Description  | Type             | Accepted values | Default |
| --------- | ------------ | ---------------- | --------------- | ------- |
| ...       | native props | `HTMLAttributes` | -               | -       |

<Attributes.Title>Fieldset.Group.Props</Attributes.Title>

| Attribute    | Description        | Type                      | Accepted values | Default |
| ------------ | ------------------ | ------------------------- | --------------- | ------- |
| **value**    | selected tab value | `string`                  | -               | -       |
| **onChange** | change tab event   | `(value: string) => void` | -               | -       |
| ...          | native props       | `HTMLAttributes`          | -               | -       |

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, PlaygroundTitle, Attributes } from 'src/components'
import { Grid, Card } from 'core'

export const meta = {
  title: 'Grid',
  description: 'Powerful fluid style layout container.',
  sidebar: 'components',
  group: 'Components',
  index: 18
}

## Grid

Powerful fluid style layout container.

The `Grid` component uses **dynamic CSS media query** to implement responsive layout, It has ultra-high performance
and very small size. Of course, it still supports dynamic props and custom breakpoints.

<Playground
  desc="Dynamically scale container width while maintaining spacing."
  scope={{ Grid, Card }}
  code={`
<Grid.Container gap={2} justify="center" height="100px">
  <Grid xs={6}>
    <Card shadow width="100%" />
  </Grid>
  <Grid xs={6}>
    <Card shadow width="100%" />
  </Grid>
  <Grid xs={6}>
    <Card shadow width="100%" />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Fluid Layout"
  desc="Containers for wrapping and scaling."
  scope={{ Grid, Card }}
  code={`
<Grid.Container gap={2} justify="center">
  <Grid xs={12}>
    <Card shadow width="100%" height="50px" />
  </Grid>
  <Grid xs={6}>
    <Card shadow width="100%" height="50px" />
  </Grid>
  <Grid xs={6}>
    <Card shadow width="100%" height="50px" />
  </Grid>
  <Grid xs={3}>
    <Card shadow width="100%" height="50px" />
  </Grid>
  <Grid xs={3}>
    <Card shadow width="100%" height="50px" />
  </Grid>
  <Grid xs={3}>
    <Card shadow width="100%" height="50px" />
  </Grid>
  <Grid xs={3}>
    <Card shadow width="100%" height="50px" />
  </Grid>
  <Grid xs={3}>
    <Card shadow width="100%" height="50px" />
  </Grid>
  <Grid xs={6}>
    <Card shadow width="100%" height="50px" />
  </Grid>
  <Grid xs={3}>
    <Card shadow width="100%" height="50px" />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Responsive Layout"
  desc="Use different layouts for different screen widths."
  scope={{ Grid, Card }}
  code={`
<Grid.Container gap={2} justify="center">
  <Grid xs={12} md={6}>
    <Card shadow width="100%" height="50px" />
  </Grid>
  <Grid xs={6} md={6}>
    <Card shadow width="100%" height="50px" />
  </Grid>
  <Grid xs={6} md={3}>
    <Card shadow width="100%" height="50px" />
  </Grid>
  <Grid xs={6} md={3}>
    <Card shadow width="100%" height="50px" />
  </Grid>
  <Grid xs={6} md={3}>
    <Card shadow width="100%" height="50px" />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Hide Elements"
  desc="Hide elements when unit size is 0."
  scope={{ Grid, Card }}
  code={`
<Grid.Container gap={2} justify="center">
  <Grid xs={6} sm={0}>
    <Card shadow width="100%" height="50px" />
  </Grid>
  <Grid xs={6} sm={0}>
    <Card shadow width="100%" height="50px" />
  </Grid>
  <Grid xs={12}>
    <Card shadow width="100%" height="50px" />
  </Grid>
  <Grid xs={12}>
    <Card shadow width="100%" height="50px" />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Auto Width"
  desc="Auto fill remaining width."
  scope={{ Grid, Card }}
  code={`
<>
  <Grid.Container gap={2} justify="center">
    <Grid xs>
      <Card shadow width="100%" height="50px" />
    </Grid>
    <Grid xs>
      <Card shadow width="100%" height="50px" />
    </Grid>
    <Grid xs>
      <Card shadow width="100%" height="50px" />
    </Grid>
  </Grid.Container>
  <Grid.Container gap={2} justify="center">
    <Grid xs>
      <Card shadow width="100%" height="50px" />
    </Grid>
    <Grid xs={12}>
      <Card shadow width="100%" height="50px" />
    </Grid>
    <Grid xs>
      <Card shadow width="100%" height="50px" />
    </Grid>
  </Grid.Container>
</>
`}
/>

<PlaygroundTitle
  title="Custom Breakpoints"
  desc="Override the default breakpoints of the `@bolio-ui/core`."
/>

```tsx
const breakpoints: BolioUIThemesBreakpoints = {
  xs: { min: '0', max: '650px' },
  sm: { min: '650px', max: '900px' },
  md: { min: '900px', max: '1280px' },
  lg: { min: '1280px', max: '1920px' },
  xl: { min: '1920px', max: '10000px' }
}

const App = () => {
  const myTheme = Themes.createFromLight({
    type: 'myTheme',
    breakpoints
  })
  return (
    <BolioProvider themes={[myTheme]} themeType="myTheme">
      <CssBaseline />
      <AppComponent />
    </BolioProvider>
  )
}
```

<Attributes edit="/content/docs/components/grid.mdx">
<Attributes.Title>Grid.Props</Attributes.Title>

| Attribute        | Description                                           | Type             | Accepted values               | Default      |
| ---------------- | ----------------------------------------------------- | ---------------- | ----------------------------- | ------------ |
| **justify**      | CSS "justify-content" property                        | `Justify`        | [Justify](#justify)           | `flex-start` |
| **alignItems**   | CSS "align-items" property                            | `AlignItems`     | [AlignItems](#alignitems)     | `stretch`    |
| **alignContent** | CSS "align-content" property                          | `AlignContent`   | [AlignContent](#aligncontent) | `flex-start` |
| **direction**    | CSS "flex-direction" property                         | `Direction`      | [Direction](#direction)       | `row`        |
| **xs**           | width of grid, for `xs` breakpoints and wider screens | `number`         | `0 - 24`, `boolean`           | `false`      |
| **sm**           | width of grid, for `sm` breakpoints and wider screens | `number`         | `0 - 24`, `boolean`           | `false`      |
| **md**           | width of grid, for `md` breakpoints and wider screens | `number`         | `0 - 24`, `boolean`           | `false`      |
| **lg**           | width of grid, for `lg` breakpoints and wider screens | `number`         | `0 - 24`, `boolean`           | `false`      |
| **xl**           | width of grid, for `xl` breakpoints and wider screens | `number`         | `0 - 24`, `boolean`           | `false`      |
| ...              | native props                                          | `HTMLAttributes` | `'id', 'className', ...`      | -            |

<Attributes.Title>Grid.Container.Props</Attributes.Title>

| Attribute | Description              | Type               | Accepted values           | Default |
| --------- | ------------------------ | ------------------ | ------------------------- | ------- |
| **gap**   | spacing of children      | `number` / `float` | -                         | 0       |
| **wrap**  | CSS "flex-wrap" property | `Wrap`             | [Wrap](#wrap)             | `wrap`  |
| ...       | Grid props               | `Grid.Props`       | [Grid.Props](#grid.props) | -       |

<Attributes.Title>Justify</Attributes.Title>

```ts
type Justify =
  | 'flex-start'
  | 'center'
  | 'flex-end'
  | 'space-between'
  | 'space-around'
  | 'space-evenly'
```

<Attributes.Title>AlignItems</Attributes.Title>

```ts
type AlignItems = 'flex-start' | 'center' | 'flex-end' | 'stretch' | 'baseline'
```

<Attributes.Title>AlignContent</Attributes.Title>

```ts
type AlignContent =
  | 'stretch'
  | 'center'
  | 'flex-start'
  | 'flex-end'
  | 'space-between'
  | 'space-around'
```

<Attributes.Title>Direction</Attributes.Title>

```ts
type Direction = 'row' | 'row-reverse' | 'column' | 'column-reverse'
```

<Attributes.Title>Wrap</Attributes.Title>

```ts
type Wrap = 'nowrap' | 'wrap' | 'wrap-reverse'
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Smile } from '@bolio-ui/icons'
import { Grid } from 'core'
import {
  Layout,
  Playground,
  PlaygroundTitle,
  Attributes,
  IconsGallery,
  PackageTabs
} from 'src/components'

export const meta = {
  title: 'Icons',
  description: 'Display semantic vector graphics in SVG format.',
  sidebar: 'components',
  group: 'Components',
  index: 19
}

## Icons

Display semantic vector graphics in SVG format.

<Grid.Container gap={4}>
  <Grid md={12}>
    <PlaygroundTitle
      title="Installation"
      desc="Install the package in your project directory."
    />
    <PackageTabs pnpm="pnpm add @bolio-ui/icons" npm="npm i @bolio-ui/icons" yarn="yarn add @bolio-ui/icons" bun="bun add @bolio-ui/icons" width="100%" />
  </Grid>
</Grid.Container>

<Playground
  title="Import"
  desc="The basic `Icon` usage."
  scope={{ Smile, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Smile />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Color"
  desc="You can apply a color with the `color` prop."
  scope={{ Smile, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Smile color="purple" />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Sizes"
  desc="You can apply size with the `fontSize` prop."
  scope={{ Smile, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Smile fontSize={16} />
  </Grid>
  <Grid>
    <Smile fontSize={20} />
  </Grid>
  <Grid>
    <Smile fontSize={24} />
  </Grid>
  <Grid>
    <Smile fontSize={28} />
  </Grid>
  <Grid>
    <Smile fontSize={32} />
  </Grid>
  <Grid>
    <Smile fontSize={36} />
  </Grid>
</Grid.Container>
`}
/>

<IconsGallery />

<Attributes edit="/content/docs/components/icons.mdx">
<Attributes.Title>Icon.Props</Attributes.Title>

| Attribute    | Description  | Type            | Accepted values                  | Default |
| ------------ | ------------ | --------------- | -------------------------------- | ------- |
| **color**    | Icon color   | `string`        | -                                | -       |
| **fontSize** | Icon size    | `number`        | -                                | -       |
| ...          | Native props | `SVGAttributes` | `'id', 'name', 'className', ...` | -       |

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { ImageZoom, Grid, useTheme } from 'core'

export const meta = {
  title: 'Image Zoom',
  description:
    'A picture that opens in a larger view above the page when it is clicked.',
  sidebar: 'components',
  group: 'Components',
  index: 69
}

## Image Zoom

A picture that opens in a larger view above the page when it is clicked. The view
is a native `dialog`: it keeps the focus inside, closes with Escape, and gives the
focus back to the picture.

<Playground
  desc="Describe the picture in `alt`, which also names the button. The size props are the ones of `Image`."
  scope={{ ImageZoom, useTheme }}
  code={`
() => {
  const theme = useTheme()
  return (
    <ImageZoom
      src="/img/jpg/docs/lake-sunrise.jpg"
      alt="A mountain lake at sunrise"
      width="240px"
      height="150px"
      style={{ objectFit: 'cover', borderRadius: theme.layout.radius }}
    />
  )
}
`}
/>

<Playground
  title="Larger image and caption"
  desc="`zoomSrc` is a larger version, loaded only when the view opens, so the page stays light. `caption` goes under the picture."
  scope={{ ImageZoom, useTheme }}
  code={`
() => {
  const theme = useTheme()
  return (
    <ImageZoom
      src="/img/jpg/docs/autumn-canyon.jpg"
      zoomSrc="/img/jpg/docs/autumn-canyon.jpg"
      alt="A river in a canyon in autumn"
      caption="The river at the bottom of the canyon, in October"
      width="240px"
      height="150px"
      style={{ objectFit: 'cover', borderRadius: theme.layout.radius }}
    />
  )
}
`}
/>

<Playground
  title="Gallery"
  desc="Several pictures, each with its own view. A click on the dark area, or on the close button, closes it."
  scope={{ ImageZoom, Grid, useTheme }}
  code={`
() => {
  const theme = useTheme()
  const photos = [
    ['/img/jpg/docs/forest-lake.jpg', 'A forest lake under the clouds'],
    ['/img/jpg/docs/mountain-reflection.jpg', 'Snowy mountains reflected in a lake'],
    ['/img/jpg/docs/moonlit-peaks.jpg', 'Snowy mountains under the moon']
  ]
  return (
    <Grid.Container gap={1}>
      {photos.map(([src, alt]) => (
        <Grid key={src}>
          <ImageZoom
            src={src}
            alt={alt}
            width="160px"
            height="100px"
            style={{ objectFit: 'cover', borderRadius: theme.layout.radius }}
          />
        </Grid>
      ))}
    </Grid.Container>
  )
}
`}
/>

<Attributes edit="/content/docs/components/image-zoom.mdx">
<Attributes.Title>ImageZoom.Props</Attributes.Title>

| Attribute        | Description                                                  | Type        | Accepted values                  | Default |
| ---------------- | ------------------------------------------------------------ | ----------- | -------------------------------- | ------- |
| **src**          | the picture                                                  | `string`    | -                                | -       |
| **alt**          | what the picture shows, and the name of the button           | `string`    | -                                | -       |
| **zoomSrc**      | a larger version, loaded when the view opens                 | `string`    | -                                | `src`   |
| **caption**      | text under the picture in the view                           | `ReactNode` | -                                | -       |
| **closeLabel**   | name of the close button                                     | `string`    | -                                | `Close` |
| ...              | the props of <a href="/docs/components/image">Image</a>, like `width`, `height` and `style` | `ImageProps` | - | -       |

<Attributes.Title>Behavior</Attributes.Title>

- • **Closing**: Escape, the close button and a click on the dark area close it. A click on the picture does not.
- • **Page**: it does not scroll while the view is open.
- • **Size**: the picture in the view fits the screen, in the proportion it has.

<Attributes.Title>Ref</Attributes.Title>

The `ref` points at the button that opens the view.

<Attributes.Title>Accessibility</Attributes.Title>

The picture is a button with `aria-haspopup="dialog"`, named by `alt`. The view is a modal `dialog` named by the same text. The focus goes to the close button when it opens, stays inside while it is open, and goes back to the picture when it closes. Always write a useful `alt`: it is what a screen reader reads for both the thumbnail and the larger picture.

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Image, Display, Code, Grid } from 'core'

export const meta = {
  title: 'Image',
  description: 'Display image content.',
  sidebar: 'components',
  group: 'Components',
  index: 19
}

## Image

Display image content.

<Playground
  title="General"
  desc="The basic `Image` usage."
  scope={{ Image, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Image
      width="280px"
      height="160px"
      src="https://bolio-ui.com/logo-white.jpg"
    />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Skeleton"
  desc="`Image` will show skeleton animation after `width` and `height` props are set."
  scope={{ Image, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Image
      width="280px"
      height="160px"
      src="https://bolio-ui.com/logo-white.jpg"
    />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Browser"
  desc="Add a browser style wrapper to the image."
  scope={{ Image, Display, Code, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Image.Browser
      url="https://bolio-ui.com.br/"
      anchorProps={{ rel: 'nofollow' }}
    >
      <Image
        width="450px"
        height="300px"
        src="https://bolio-ui.com/logo-white.jpg"
      />
    </Image.Browser>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Browser Invert"
  desc="You can apply a color invert with the `invert` prop."
  scope={{ Image, Display, Code, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Image.Browser url="https://bolio-ui.com.br/" invert>
      <Image
        width="450px"
        height="300px"
        src="https://bolio-ui.com/logo-white.jpg"
      />
    </Image.Browser>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Compose"
  desc="Show `Image` in `Display` component."
  scope={{ Image, Display, Code, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Display
      shadow
      caption={
        <p>
          Reduce the possibility of page rendering by setting{' '}
          <Code>height</Code>
        </p>
      }
    >
      <Image
        height="250px"
        src="https://bolio-ui.com/logo-white.jpg"
      />
    </Display>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="SVG"
  desc="Render svg strings directly"
  scope={{ Image, Grid }}
  code={`
() => {
  const svg = \`<svg xmlns="http://www.w3.org/2000/svg" width="30px" height="30px" viewBox="0 0 30 30" fill="none">
    <path d="M13.5 3.5H14V3.29289L13.8536 3.14645L13.5 3.5ZM10.5 0.5L10.8536 0.146447L10.7071 0H10.5V0.5ZM2.5 6.5V6H2V6.5H2.5ZM2.5 8.5H2V9H2.5V8.5ZM4.5 8.5H5V8H4.5V8.5ZM4.5 10.5V11H5V10.5H4.5ZM6.5 9.5H6V9.70711L6.14645 9.85355L6.5 9.5ZM7.5 10.5L7.14645 10.8536L7.5 11.2071L7.85355 10.8536L7.5 10.5ZM8.5 9.5L8.85355 9.85355L9 9.70711V9.5H8.5ZM10.5 6.5V6H10V6.5H10.5ZM10.5 10.5H10V11H10.5V10.5ZM12.5 10.5V11H13V10.5H12.5ZM2 5V1.5H1V5H2ZM13 3.5V5H14V3.5H13ZM2.5 1H10.5V0H2.5V1ZM10.1464 0.853553L13.1464 3.85355L13.8536 3.14645L10.8536 0.146447L10.1464 0.853553ZM2 1.5C2 1.22386 2.22386 1 2.5 1V0C1.67157 0 1 0.671573 1 1.5H2ZM1 12V13.5H2V12H1ZM2.5 15H12.5V14H2.5V15ZM14 13.5V12H13V13.5H14ZM12.5 15C13.3284 15 14 14.3284 14 13.5H13C13 13.7761 12.7761 14 12.5 14V15ZM1 13.5C1 14.3284 1.67157 15 2.5 15V14C2.22386 14 2 13.7761 2 13.5H1ZM5 6H2.5V7H5V6ZM2 6.5V8.5H3V6.5H2ZM2.5 9H4.5V8H2.5V9ZM4 8.5V10.5H5V8.5H4ZM4.5 10H2V11H4.5V10ZM6 6V9.5H7V6H6ZM6.14645 9.85355L7.14645 10.8536L7.85355 10.1464L6.85355 9.14645L6.14645 9.85355ZM7.85355 10.8536L8.85355 9.85355L8.14645 9.14645L7.14645 10.1464L7.85355 10.8536ZM9 9.5V6H8V9.5H9ZM13 6H10.5V7H13V6ZM10 6.5V10.5H11V6.5H10ZM10.5 11H12.5V10H10.5V11ZM13 10.5V8.5H12V10.5H13Z" fill="gray"/>
  </svg>\`
  return (
    <Grid.Container gap={2}>
      <Grid>
        <Image width="100px" height="50px" src={svg} />
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Attributes edit="/content/docs/components/image.mdx">
<Attributes.Title>Image.Props</Attributes.Title>

| Attribute             | Description                             | Type                | Accepted values           | Default |
| --------------------- | --------------------------------------- | ------------------- | ------------------------- | ------- |
| **src**               | image src                               | `string`            | -                         | -       |
| **disableSkeleton**   | disable skeleton animation when loading | `boolean`           | -                         | `false` |
| **disableAutoResize** | disable zooming when width is too small | `boolean`           | -                         | `false` |
| **maxDelay**(ms)      | max duration of animation               | `number`            | -                         | `3000`  |
| ...                   | native props                            | `ImgHTMLAttributes` | `'alt', 'className', ...` | -       |

<Attributes.Title>Image.Browser.Props</Attributes.Title>

| Attribute        | Description                           | Type                   | Accepted values          | Default |
| ---------------- | ------------------------------------- | ---------------------- | ------------------------ | ------- |
| **title**        | show text title (when "url" is unset) | `string`               | -                        | -       |
| **url**          | show url on browser address input     | `string`               | -                        | -       |
| **showFullLink** | show full url                         | `boolean`              | -                        | `false` |
| **invert**       | invert colors                         | `boolean`              | -                        | `false` |
| **anchorProps**  | props of element `a`                  | `AnchorHTMLAttributes` | -                        | `{}`    |
| ...              | native props                          | `HTMLAttributes`       | `'id', 'className', ...` | -       |

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Instagram, Facebook } from '@bolio-ui/icons'
import { Input, Grid, Button, Code, Text, Dot, Spacer } from 'core'

export const meta = {
  title: 'Input',
  description: 'Retrieve text input from a user.',
  sidebar: 'components',
  group: 'Components',
  index: 20
}

## Input

Retrieve text input from a user.

The Input contain an additional Hooks, see subsection [useInput](/docs/hooks/use-input) for details.

<Playground
  desc="Basic input field."
  scope={{ Input, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Input placeholder="Placeholder Text" />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Floating Label"
  desc="With `floating` the label sits inside the field and moves up when you type or focus. It replaces the placeholder."
  scope={{ Input, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Input floating width="100%">Email</Input>
  </Grid>
  <Grid>
    <Input floating width="100%" initialValue="bolio@ui.dev">Email</Input>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Sizes"
  desc="Inputs of different sizes."
  scope={{ Input, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Input scale={1 / 3} placeholder="Scale 1/3" />
  </Grid>
  <Grid>
    <Input scale={2 / 3} placeholder="Scale 2/3" />
  </Grid>
  <Grid>
    <Input placeholder="Scale 1" />
  </Grid>
  <Grid>
    <Input scale={4 / 3} placeholder="Scale 4/3" />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Set width"
  desc="Specify width or other styles."
  scope={{ Input, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Input placeholder="Placeholder Text" width="100%" />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Unwritable"
  desc="Disable interactive inputs."
  scope={{ Input, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Input disabled placeholder="Disabled" />
  </Grid>
  <Grid>
    <Input readOnly initialValue="Read Only" />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Inline Label"
  desc="Show a short label in the line."
  scope={{ Input, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Input label="username" placeholder="Username" />
  </Grid>
  <Grid>
    <Input labelRight=".com" placeholder="https://github.com/" />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Block Label"
  desc="Labels for custom styles."
  scope={{ Input, Grid, Text, Code, Dot }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Input placeholder="Block Label">
      <Text h3>Block Label</Text>
    </Input>
  </Grid>
  <Grid>
    <Input placeholder="Block Label">Block Label</Input>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Type"
  desc="Differentiate states by color."
  scope={{ Input, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Input placeholder="Default" />
  </Grid>
  <Grid>
    <Input type="primary" placeholder="Primary" />
  </Grid>
  <Grid>
    <Input type="secondary" placeholder="Secondary" />
  </Grid>
  <Grid>
    <Input type="success" placeholder="Success" />
  </Grid>
  <Grid>
    <Input type="warning" placeholder="Warning" />
  </Grid>
  <Grid>
    <Input type="error" placeholder="Error" />
  </Grid>
  <Grid>
    <Input type="info" placeholder="Info" />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Rounded"
  desc="You can completely round the corners of any type of `Input` with the `rounded` property."
  scope={{ Input, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Input placeholder="Default" rounded />
  </Grid>
  <Grid>
    <Input type="primary" placeholder="Primary" rounded />
  </Grid>
  <Grid>
    <Input type="secondary" placeholder="Secondary" rounded />
  </Grid>
  <Grid>
    <Input type="success" placeholder="Success" rounded />
  </Grid>
  <Grid>
    <Input type="warning" placeholder="Warning" rounded />
  </Grid>
  <Grid>
    <Input type="error" placeholder="Error" rounded />
  </Grid>
  <Grid>
    <Input type="info" placeholder="Info" rounded />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Variants"
  desc="Use `filled`, `light`, `ghost` or `subtle` to change the surface of any colored `Input`."
  scope={{ Input, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Input type="primary" placeholder="Primary filled" filled />
  </Grid>
  <Grid>
    <Input type="secondary" placeholder="Secondary filled" filled />
  </Grid>
  <Grid>
    <Input type="success" placeholder="Success filled" filled />
  </Grid>
  <Grid>
    <Input type="warning" placeholder="Warning filled" filled />
  </Grid>
  <Grid>
    <Input type="error" placeholder="Error filled" filled />
  </Grid>
  <Grid>
    <Input type="info" placeholder="Info filled" filled />
  </Grid>
  <Grid>
    <Input type="primary" placeholder="Primary light" light />
  </Grid>
  <Grid>
    <Input type="secondary" placeholder="Secondary light" light />
  </Grid>
  <Grid>
    <Input type="success" placeholder="Success light" light />
  </Grid>
  <Grid>
    <Input type="warning" placeholder="Warning light" light />
  </Grid>
  <Grid>
    <Input type="error" placeholder="Error light" light />
  </Grid>
  <Grid>
    <Input type="info" placeholder="Info light" light />
  </Grid>
  <Grid>
    <Input type="primary" placeholder="Primary ghost" ghost />
  </Grid>
  <Grid>
    <Input type="secondary" placeholder="Secondary ghost" ghost />
  </Grid>
  <Grid>
    <Input type="success" placeholder="Success ghost" ghost />
  </Grid>
  <Grid>
    <Input type="warning" placeholder="Warning ghost" ghost />
  </Grid>
  <Grid>
    <Input type="error" placeholder="Error ghost" ghost />
  </Grid>
  <Grid>
    <Input type="info" placeholder="Info ghost" ghost />
  </Grid>
  <Grid>
    <Input type="primary" placeholder="Primary subtle" subtle />
  </Grid>
  <Grid>
    <Input type="secondary" placeholder="Secondary subtle" subtle />
  </Grid>
  <Grid>
    <Input type="success" placeholder="Success subtle" subtle />
  </Grid>
  <Grid>
    <Input type="warning" placeholder="Warning subtle" subtle />
  </Grid>
  <Grid>
    <Input type="error" placeholder="Error subtle" subtle />
  </Grid>
  <Grid>
    <Input type="info" placeholder="Info subtle" subtle />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Icon"
  desc="Specify an icon component."
  scope={{ Input, Instagram, Facebook, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Input icon={<Instagram />} placeholder="Instagram" />
  </Grid>
  <Grid>
    <Input iconRight={<Facebook />} placeholder="Facebook" />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Clearable"
  desc="Add a clear button in the input box."
  scope={{ Input, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Input
      clearable
      initialValue="Initial Value"
      placeholder="Initial Value"
    />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Password"
  desc="`Input` component with a show/hide password functionality, Important: You have to use the `Input.Password` component."
  scope={{ Input, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Input.Password initialValue="123456abc" />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Get Change"
  desc="Capture changes in input."
  scope={{ Input, Grid }}
  code={`
() => {
  const [value, setValue] = React.useState()
  const handler = (e) => {
    setValue(e.target.value)
    console.log(e.target.value)
  }
  return (
    <Grid.Container gap={2}>
      <Grid>
        <Input value={value} onChange={handler} placeholder="Bolio UI" />
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Playground
  title="Date and time"
  desc="`htmlType` takes the native types, like `date`, `time` and `datetime-local`. The browser draws the picker, in the language and with the keyboard of the user, and it follows the theme."
  scope={{ Input, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Input htmlType="date">Date</Input>
  </Grid>
  <Grid>
    <Input htmlType="time">Time</Input>
  </Grid>
  <Grid>
    <Input htmlType="datetime-local">Date and time</Input>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Imperative API"
  desc="Update component in an uncontrolled way."
  scope={{ Input, Grid, Button }}
  code={`
() => {
  const ref = React.useRef(null)
  const setChange = () => {
    ref && (ref.current.value = Math.random().toString(32))
  }
  return (
    <Grid.Container gap={2}>
      <Grid>
        <Input initialValue="Hello" onChange={e => console.log(e.target.value)} ref={ref} />
      </Grid>
      <Grid>
        <Button auto type="secondary" scale={1/3} onClick={setChange}>set value</Button>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Playground
  title="Login form"
  desc="Validate on submit and say what to fix, under the field. The `error` type turns the field red."
  scope={{ Input, Button, Text, Spacer }}
  code={`
() => {
  const [email, setEmail] = React.useState('')
  const [submitted, setSubmitted] = React.useState(false)
  const invalid = submitted && !/^\\S+@\\S+\\.\\S+$/.test(email)
  return (
    <form
      style={{ maxWidth: 320 }}
      onSubmit={(event) => {
        event.preventDefault()
        setSubmitted(true)
      }}
    >
      <Input floating width="100%" type={invalid ? 'error' : 'default'} value={email} onChange={(event) => setEmail(event.target.value)}>
        Email
      </Input>
      {invalid && <Text small type="error">Enter an email like name@company.com.</Text>}
      <Spacer h={1} />
      <Input.Password floating width="100%">Password</Input.Password>
      <Spacer h={1.5} />
      <Button type="primary" htmlType="submit" width="100%">Sign in</Button>
    </form>
  )
}
`}
/>

<Attributes edit="/content/docs/components/input.mdx">
<Attributes.Title>Input.Props</Attributes.Title>

| Attribute         | Description                   | Type                                                 | Accepted values                   | Default   |
| ----------------- | ----------------------------- | ---------------------------------------------------- | --------------------------------- | --------- |
| **value**         | input value                   | `string`                                             | -                                 | -         |
| **initialValue**  | initial value                 | `string`                                             | -                                 | -         |
| **placeholder**   | placeholder                   | `string`                                             | -                                 | -         |
| **type**          | current type                  | `InputTypes`                                         | [InputTypes](#inputtypes)         | `default` |
| **htmlType**      | native type attr              | `string`                                             | -                                 | `text`    |
| **readOnly**      | native attr                   | `boolean`                                            | -                                 | `false`   |
| **disabled**      | disable input                 | `boolean`                                            | -                                 | `false`   |
| **clearable**     | show clear icon               | `boolean`                                            | -                                 | `false`   |
| **filled**        | filled variant                | `boolean`                                            | -                                 | `false`   |
| **light**         | light variant                 | `boolean`                                            | -                                 | `false`   |
| **ghost**         | outline variant               | `boolean`                                            | -                                 | `false`   |
| **subtle**        | subtle variant                | `boolean`                                            | -                                 | `false`   |
| **label**         | text label for input          | `string`                                             | -                                 | -         |
| **labelRight**    | text label at right for input | `string`                                             | -                                 | -         |
| **floating**      | label inside the field that moves up on focus | `boolean`                         | -                                 | `false`   |
| **icon**          | icon for input                | `React.ReactNode`                                    | -                                 | -         |
| **iconRight**     | icon at right for input       | `React.ReactNode`                                    | -                                 | -         |
| **iconClickable** | icons are clickable           | `boolean`                                            | -                                 | `false`   |
| **onIconClick**   | click icon event              | `(e: React.ChangeEvent) => void`                     | -                                 | -         |
| **onChange**      | change event                  | `(e: React.ChangeEvent) => void`                     | -                                 | -         |
| **onClearClick**  | clear icon event              | `(e: React.MouseEvent) => void`                      | -                                 | -         |
| **ref**           | forwardRef                    | <Code>Ref&lt;HTMLInputElement &#124; null&gt;</Code> | -                                 | -         |
| ...               | native props                  | `InputHTMLAttributes`                                | `'alt', 'type', 'className', ...` | -         |

<Attributes.Title>Input.Password.Props</Attributes.Title>

| Attribute      | Description      | Type          | Accepted values             | Default |
| -------------- | ---------------- | ------------- | --------------------------- | ------- |
| **hideToggle** | hide toggle icon | `boolean`     | -                           | `false` |
| ...            | input props      | `Input.Props` | [Input.Props](#input.props) | -       |

<Attributes.Title>InputTypes</Attributes.Title>

```ts
type InputTypes =
  'default' | 'primary' | 'secondary' | 'success' | 'warning' | 'error' | 'info'
```

<Attributes.Title>useInput</Attributes.Title>

```ts
type useInput = (initialValue: string) => {
  state: string
  setState: Dispatch<SetStateAction<string>>
  currentRef: MutableRefObject<string>
  reset: () => void
  bindings: {
    value: string
    onChange: (event: React.ChangeEvent<HTMLInputElement>) => void
  }
}
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Keyboard, Grid } from 'core'

export const meta = {
  title: 'Keyboard',
  description: 'Display keyboard input that triggers an action.',
  sidebar: 'components',
  group: 'Components',
  index: 21
}

## Keyboard

Display keyboard input that triggers an action.

The `Keyboard` can only display layout styles, if you need to bind the keyboard events, please read subsection [useKeyboard](/docs/hooks/use-keyboard).

<Playground
  scope={{ Keyboard, Grid }}
  desc="The basic `Keyboard` usage."
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Keyboard>C</Keyboard>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Modifiers"
  desc="You can apply a modifiers with the `command`, `shift`, `option`, `ctrl` prop."
  scope={{ Keyboard, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Keyboard command mr="10px" />
  </Grid>
  <Grid>
    <Keyboard shift mr="10px" />
  </Grid>
  <Grid>
    <Keyboard option mr="10px" />
  </Grid>
  <Grid>
    <Keyboard ctrl mr="10px" />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Combination"
  desc="You can apply a combination with the `option ctrl` prop for example."
  scope={{ Keyboard, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Keyboard command mr="10px">
      f
    </Keyboard>
  </Grid>
  <Grid>
    <Keyboard shift mr="10px">
      e
    </Keyboard>
  </Grid>
  <Grid>
    <Keyboard option ctrl mr="10px">
      b
    </Keyboard>
  </Grid>
</Grid.Container>
`}
/>

<Attributes edit="/content/docs/components/keyboard.mdx">
<Attributes.Title>Keyboard.Props</Attributes.Title>

| Attribute   | Description      | Type                   | Accepted values               | Default |
| ----------- | ---------------- | ---------------------- | ----------------------------- | ------- |
| **command** | show command key | `boolean`              | -                             | `false` |
| **shift**   | show shift key   | `boolean`              | -                             | `false` |
| **option**  | show option key  | `boolean`              | -                             | `false` |
| **ctrl**    | show ctrl key    | `boolean`              | -                             | `false` |
| ...         | native props     | `KeygenHTMLAttributes` | `'keyType', 'className', ...` | -       |

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Text, Code, Grid } from 'core'
import { useRouter } from 'next/navigation'

export const meta = {
  title: 'Link',
  description: 'Hyperlinks between pages.',
  sidebar: 'components',
  group: 'Components',
  index: 22
}

## Link

Hyperlinks between pages.

<Playground
  scope={{ Link, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Link href="#">
      Is a reference to the data you can follow directly by tapping.
    </Link>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Highlight"
  desc="Distinguish links with different colors."
  scope={{ Link, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Link href="#" color>
      Is a reference to the data you can follow directly by tapping.
    </Link>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="With Icon"
  desc="Show an icon in the link."
  scope={{ Link, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Link href="#" icon>
      Is a reference to the data you can follow directly by tapping.
    </Link>
  </Grid>
  <Grid>
    <Link href="#" icon color>
      Is a reference to the data you can follow directly by tapping.
    </Link>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Variant"
  desc="Different styles of links."
  scope={{ Link, Text, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Text>
      <Link href="#">
        Is a reference to the data you can follow directly by tapping.
      </Link>
    </Text>
  </Grid>
  <Grid>
    <Text>
      <Link href="#" color>
        Is a reference to the data you can follow directly by tapping.
      </Link>
    </Text>
  </Grid>
  <Grid>
    <Text>
      <Link href="#" underline>
        Is a reference to the data you can follow directly by tapping.
      </Link>
    </Text>
  </Grid>
  <Grid>
    <Text>
      <Link href="#" color underline>
        Is a reference to the data you can follow directly by tapping.
      </Link>
    </Text>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Block"
  desc="Display as a separate block."
  scope={{ Link, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Link href="#" block>
      Is a reference to the data you can follow directly by tapping.
    </Link>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="With the Next.js router"
  desc="Keep the `href`, so the link works in a new tab, and navigate with the router on click."
  scope={{ Link, Grid, useRouter }}
  code={`
() => {
  const router = useRouter()
  return (
    <Grid.Container gap={2}>
      <Grid>
        <Link
          block
          href="/docs/components/button"
          onClick={(event) => {
            event.preventDefault()
            router.push('/docs/components/button')
          }}
        >
          Docs of Button
        </Link>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Attributes edit="/content/docs/components/link.mdx">
<Attributes.Title>Link.Props</Attributes.Title>

| Attribute     | Description                 | Type                                            | Accepted values        | Default |
| ------------- | --------------------------- | ----------------------------------------------- | ---------------------- | ------- |
| **href**      | link url                    | `string`                                        | -                      | -       |
| **color**     | display color for link      | `boolean`                                       | -                      | `false` |
| **icon**      | show icon                   | `boolean`                                       | -                      | `false` |
| **underline** | display underline           | `boolean`                                       | -                      | `false` |
| **block**     | display as a separate block | `boolean`                                       | -                      | `false` |
| **ref**       | forwardRef                  | <Code>Ref&lt;HTMLAnchorElement &#124; null&gt;</Code> | -                      | -       |
| ...           | native props                | `AnchorHTMLAttributes`                          | `'rel', 'target', ...` | -       |

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Loading, Grid } from 'core'

export const meta = {
  title: 'Loading',
  description: 'Indicate an action running in the background.',
  sidebar: 'components',
  group: 'Components',
  index: 23
}

## Loading

Indicate an action running in the background.

<Playground
  desc="The basic `Loading` usage."
  scope={{ Loading, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid xs={12} md={12}>
    <Loading />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="With Text"
  desc="Customize text next to icon."
  scope={{ Loading, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid xs={12} md={12}>
    <Loading>Loading</Loading>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Types"
  desc="Loading indicators in different states."
  scope={{ Loading, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid xs={3} md={3}>
    <Loading />
  </Grid>
  <Grid xs={3} md={3}>
    <Loading type="primary" />
  </Grid>
  <Grid xs={3} md={3}>
    <Loading type="secondary" />
  </Grid>
  <Grid xs={3} md={3}>
    <Loading type="success" />
  </Grid>
  <Grid xs={3} md={3}>
    <Loading type="warning" />
  </Grid>
  <Grid xs={3} md={3}>
    <Loading type="error" />
  </Grid>
  <Grid xs={3} md={3}>
    <Loading type="info" />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Spaces"
  desc="Customize the space between points. (the ratio is relative to the current `size`)"
  scope={{ Loading, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid xs={6} md={6}>
    <Loading spaceRatio={10} />
  </Grid>
  <Grid xs={6} md={6}>
    <Loading spaceRatio={5} />
  </Grid>
</Grid.Container>
`}
/>

<Attributes edit="/content/docs/components/loading.mdx">
<Attributes.Title>Loading.Props</Attributes.Title>

| Attribute      | Description                        | Type             | Accepted values                   | Default   |
| -------------- | ---------------------------------- | ---------------- | --------------------------------- | --------- |
| **type**       | bg-color type                      | `LoadingTypes`   | [LoadingTypes](#loadingtypes)     | `default` |
| **color**      | custom bg color                    | `string`         | -                                 | -         |
| **spaceRatio** | percentage of space between points | `number`         | -                                 | 1         |
| ...            | native props                       | `HTMLAttributes` | `'id', 'title', 'className', ...` | -         |

<Attributes.Title>LoadingTypes</Attributes.Title>

```ts
type LoadingTypes =
  | 'default'
  | 'primary'
  | 'secondary'
  | 'success'
  | 'warning'
  | 'error'
  | 'info'
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Marquee, Tag, Card, Text } from 'core'

export const meta = {
  title: 'Marquee',
  description: 'Loop content horizontally without end.',
  sidebar: 'components',
  group: 'Components',
  index: 56
}

## Marquee

Loop content horizontally without end.

<Playground
  title="General"
  desc="Pauses on hover and stops when the user prefers reduced motion."
  scope={{ Marquee, Tag }}
  code={`
<Marquee duration={20}>
  <Tag>React</Tag>
  <Tag>Next.js</Tag>
  <Tag>Gatsby</Tag>
  <Tag>RedwoodJS</Tag>
  <Tag>Vite</Tag>
  <Tag>Remix</Tag>
</Marquee>
`}
/>

<Playground
  title="Reverse"
  desc="Use `reverse` to run the other way, for example in a second row."
  scope={{ Marquee, Card, Text }}
  code={`
<Marquee reverse duration={25} gap="1rem">
  <Card bordered width="260px">
    <Text my={0}>“Easy to theme and clear docs.”</Text>
  </Card>
  <Card bordered width="260px">
    <Text my={0}>“We shipped our dashboard in a week.”</Text>
  </Card>
  <Card bordered width="260px">
    <Text my={0}>“The best defaults I have used.”</Text>
  </Card>
</Marquee>
`}
/>

<Playground
  title="Two rows"
  desc="Run a second row in the other direction, with the same `duration`, so the two feel like one band."
  scope={{ Marquee, Tag }}
  code={`
<div style={{ display: 'flex', flexDirection: 'column', gap: 12 }}>
  <Marquee duration={30}>
    <Tag>Acme</Tag>
    <Tag>Globex</Tag>
    <Tag>Initech</Tag>
    <Tag>Umbrella</Tag>
    <Tag>Hooli</Tag>
  </Marquee>
  <Marquee reverse duration={30}>
    <Tag>Stark</Tag>
    <Tag>Wayne</Tag>
    <Tag>Wonka</Tag>
    <Tag>Cyberdyne</Tag>
    <Tag>Soylent</Tag>
  </Marquee>
</div>
`}
/>

<Attributes edit="/content/docs/components/marquee.mdx">
<Attributes.Title>Marquee.Props</Attributes.Title>

| Attribute        | Description                | Type             | Accepted values | Default |
| ---------------- | -------------------------- | ---------------- | --------------- | ------- |
| **duration**     | seconds for one full loop  | `number`         | -               | `30`    |
| **pauseOnHover** | pause while hovering       | `boolean`        | -               | `true`  |
| **reverse**      | run in the other direction | `boolean`        | -               | `false` |
| **gap**          | space between items        | `string`         | -               | `2rem`  |
| ...              | native props               | `HTMLAttributes` | -               | -       |


</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Mention, Card, Text, Button } from 'core'

export const meta = {
  title: 'Mention',
  description: 'Type a trigger character in a text field to pick a person, a tag or a command from a list.',
  sidebar: 'components',
  group: 'Components',
  index: 57
}

## Mention

Type a trigger character in a text field to pick a person, a tag or a command from a list.

<Playground
  title="General"
  desc="Type `@` and the start of a name. Arrow keys move through the list, Enter or Tab inserts the mention and Escape closes the list."
  scope={{ Mention }}
  code={`
<Mention
  aria-label="Comment"
  placeholder="Write a comment and type @ to mention someone"
  options={[
    { value: 'ana', label: 'Ana Souza' },
    { value: 'bruno', label: 'Bruno Lima' },
    { value: 'carla', label: 'Carla Dias' },
    { value: 'diego', label: 'Diego Prado', disabled: true }
  ]}
/>
`}
/>

<Playground
  title="Other trigger"
  desc="Change the character with `trigger`. Here `#` picks a topic."
  scope={{ Mention }}
  code={`
<Mention
  aria-label="Post"
  trigger="#"
  rows={2}
  placeholder="Write a post and type # to add a topic"
  options={[
    { value: 'release', label: 'release' },
    { value: 'design', label: 'design' },
    { value: 'accessibility', label: 'accessibility' }
  ]}
/>
`}
/>

<Playground
  title="Comment box"
  desc="Keep the text in your state to read who was mentioned. The people below are the ones who will be notified."
  scope={{ Mention, Card, Text, Button }}
  code={`
() => {
  const people = [
    { value: 'ana', label: 'Ana Souza' },
    { value: 'bruno', label: 'Bruno Lima' },
    { value: 'carla', label: 'Carla Dias' }
  ]
  const [text, setText] = React.useState('')
  const [posted, setPosted] = React.useState(null)
  const mentioned = people.filter((p) => text.includes('@' + p.value + ' ') || text.endsWith('@' + p.value))
  return (
    <Card bordered width="100%">
      <Mention
        aria-label="Comment"
        value={text}
        onChange={setText}
        options={people}
        placeholder="Reply to the thread, @ to mention someone"
      />
      <div style={{ marginTop: 12, display: 'flex', alignItems: 'center', gap: 12, flexWrap: 'wrap' }}>
        <Button auto scale={0.75} type="primary" disabled={!text.trim()} onClick={() => { setPosted(mentioned.length); setText('') }}>
          Post comment
        </Button>
        <Text small type="secondary">
          {mentioned.length ? 'Notifies ' + mentioned.map((p) => p.label).join(', ') : 'Nobody is mentioned yet.'}
        </Text>
      </div>
      {posted !== null && <Text small type="success">Posted, {posted} {posted === 1 ? 'person' : 'people'} notified.</Text>}
    </Card>
  )
}
`}
/>

<Attributes edit="/content/docs/components/mention.mdx">
<Attributes.Title>Mention.Props</Attributes.Title>

| Attribute        | Description                                                      | Type                                                  | Accepted values | Default      |
| ---------------- | ---------------------------------------------------------------- | ----------------------------------------------------- | --------------- | ------------ |
| **options**      | what can be mentioned. `value` is inserted, `label` is shown     | `{ value: string; label?: string; disabled?: boolean }[]` | -           | -            |
| **trigger**      | character that opens the list                                    | `string`                                              | -               | `@`          |
| **value**        | text of the field, to control it                                 | `string`                                              | -               | -            |
| **initialValue** | text at the start                                                | `string`                                              | -               | `''`         |
| **onChange**     | called with the new text                                         | `(text: string) => void`                              | -               | -            |
| **onSelect**     | called with the option that was inserted                         | `(option: MentionOption) => void`                     | -               | -            |
| **rows**         | height of the field                                              | `number`                                              | -               | `3`          |
| **placeholder**  | hint while the field is empty                                    | `string`                                              | -               | -            |
| **emptyText**    | shown when nothing matches                                       | `string`                                              | -               | `No results` |
| **disabled**     | block the field                                                  | `boolean`                                             | -               | `false`      |
| ...              | native props of the textarea                                     | `TextareaHTMLAttributes`                              | -               | -            |

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Menu, Button, Grid } from 'core'

export const meta = {
  title: 'Menu',
  description:
    'A list of actions that opens from a button, with submenus, checkbox and radio items and keyboard support.',
  sidebar: 'components',
  group: 'Components',
  index: 49
}

## Menu

A list of actions that opens from a button. Use it for commands, like editing
or sharing something. To pick a value for a form, use `Select` or `Combobox`.

<Playground
  desc="Pass the element that opens the menu in `trigger`. A `shortcut` is shown next to the item."
  scope={{ Menu, Button, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Menu trigger={<Button auto>Options</Button>}>
      <Menu.Item shortcut="⌘E">Edit</Menu.Item>
      <Menu.Item shortcut="⌘D">Duplicate</Menu.Item>
      <Menu.Item disabled>Archive</Menu.Item>
      <Menu.Divider />
      <Menu.Item type="error">Delete</Menu.Item>
    </Menu>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Labels and dividers"
  desc="Group the items with `Menu.Label` and separate the groups with `Menu.Divider`."
  scope={{ Menu, Button, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Menu trigger={<Button auto>Account</Button>}>
      <Menu.Label>Profile</Menu.Label>
      <Menu.Item>Settings</Menu.Item>
      <Menu.Item>Billing</Menu.Item>
      <Menu.Divider />
      <Menu.Label>Team</Menu.Label>
      <Menu.Item>Invite people</Menu.Item>
      <Menu.Divider />
      <Menu.Item>Log out</Menu.Item>
    </Menu>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Submenus"
  desc="`Menu.Sub` opens a menu next to its item on hover, on click or with the right arrow. Submenus can be nested."
  scope={{ Menu, Button, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Menu trigger={<Button auto>File</Button>}>
      <Menu.Item>New</Menu.Item>
      <Menu.Item>Open</Menu.Item>
      <Menu.Sub label="Share">
        <Menu.Item>Email</Menu.Item>
        <Menu.Item>Copy link</Menu.Item>
        <Menu.Sub label="More">
          <Menu.Item>Embed</Menu.Item>
          <Menu.Item>Export</Menu.Item>
        </Menu.Sub>
      </Menu.Sub>
      <Menu.Divider />
      <Menu.Item>Close</Menu.Item>
    </Menu>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Checkbox and radio items"
  desc="`Menu.CheckboxItem` turns an option on or off. `Menu.RadioItem` picks one value of its `Menu.RadioGroup`. Both keep the menu open."
  scope={{ Menu, Button, Grid }}
  code={`
() => {
  const [grid, setGrid] = React.useState(true)
  const [ruler, setRuler] = React.useState(false)
  const [sort, setSort] = React.useState('name')
  return (
    <Grid.Container gap={2}>
      <Grid>
        <Menu trigger={<Button auto>View</Button>}>
          <Menu.CheckboxItem checked={grid} onChange={setGrid}>
            Show grid
          </Menu.CheckboxItem>
          <Menu.CheckboxItem checked={ruler} onChange={setRuler}>
            Show ruler
          </Menu.CheckboxItem>
          <Menu.Divider />
          <Menu.Label>Sort by</Menu.Label>
          <Menu.RadioGroup aria-label="Sort by" value={sort} onChange={setSort}>
            <Menu.RadioItem value="name">Name</Menu.RadioItem>
            <Menu.RadioItem value="date">Date</Menu.RadioItem>
            <Menu.RadioItem value="size">Size</Menu.RadioItem>
          </Menu.RadioGroup>
        </Menu>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Playground
  title="Controlled"
  desc="Control when the menu is open with `visible` and `onVisibleChange`."
  scope={{ Menu, Button, Grid }}
  code={`
() => {
  const [visible, setVisible] = React.useState(false)
  return (
    <Grid.Container gap={2}>
      <Grid>
        <Menu
          visible={visible}
          onVisibleChange={setVisible}
          trigger={<Button auto>{visible ? 'Open' : 'Closed'}</Button>}
        >
          <Menu.Item>Edit</Menu.Item>
          <Menu.Item>Duplicate</Menu.Item>
        </Menu>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Attributes edit="/content/docs/components/menu.mdx">
<Attributes.Title>Menu.Props</Attributes.Title>

| Attribute             | Description                                          | Type                           | Accepted values                   | Default |
| --------------------- | ---------------------------------------------------- | ------------------------------ | --------------------------------- | ------- |
| **trigger**           | the element that opens the menu, usually a `Button`  | `ReactElement`                 | -                                 | -       |
| **visible**           | open state, to control the menu                      | `boolean`                      | -                                 | -       |
| **initialVisible**    | open state at the start                              | `boolean`                      | -                                 | `false` |
| **onVisibleChange**   | called when the menu wants to open or close          | `(visible: boolean) => void`   | -                                 | -       |
| **getPopupContainer** | element that receives the menu, `document.body` when missing | `() => HTMLElement`    | -                                 | -       |
| ...                   | native props, passed to the element around the trigger | `HTMLAttributes`            | `'id', 'className', ...`          | -       |

<Attributes.Title>Menu.Item.Props</Attributes.Title>

| Attribute            | Description                                     | Type                       | Accepted values          | Default   |
| -------------------- | ----------------------------------------------- | -------------------------- | ------------------------ | --------- |
| **onClick**          | called when the item is chosen, by click or key | `(event) => void`          | -                        | -         |
| **icon**             | shown before the label                          | `ReactNode`                | -                        | -         |
| **shortcut**         | shown after the label, only for the eye         | `string`                   | -                        | -         |
| **type**             | color of the item                               | `string`                   | `'default', 'error'`     | `default` |
| **disabled**         | the item cannot be chosen or focused            | `boolean`                  | -                        | `false`   |
| **disableAutoClose** | keep the menu open after the item is chosen     | `boolean`                  | -                        | `false`   |
| ...                  | native props                                    | `HTMLAttributes`           | `'aria-keyshortcuts', ...` | -       |

<Attributes.Title>Menu.CheckboxItem.Props</Attributes.Title>

Accepts the props of `Menu.Item`, except `onClick`, plus:

| Attribute            | Description                                 | Type                          | Accepted values | Default |
| -------------------- | ------------------------------------------- | ----------------------------- | --------------- | ------- |
| **checked**          | whether the option is on                    | `boolean`                     | -               | `false` |
| **onChange**         | called with the new state                   | `(checked: boolean) => void`  | -               | -       |
| **disableAutoClose** | keep the menu open after the item is chosen | `boolean`                     | -               | `true`  |

<Attributes.Title>Menu.RadioGroup.Props</Attributes.Title>

| Attribute    | Description                                    | Type                      | Accepted values          | Default |
| ------------ | ---------------------------------------------- | ------------------------- | ------------------------ | ------- |
| **value**    | the value of the checked item                  | `string`                  | -                        | -       |
| **onChange** | called with the value of the chosen item       | `(value: string) => void` | -                        | -       |
| ...          | native props, name the group with `aria-label` | `HTMLAttributes`          | `'aria-label', ...`      | -       |

<Attributes.Title>Menu.RadioItem.Props</Attributes.Title>

Accepts the props of `Menu.Item`, except `onClick`, plus:

| Attribute            | Description                                 | Type      | Accepted values | Default |
| -------------------- | ------------------------------------------- | --------- | --------------- | ------- |
| **value**            | the value this item checks in its group     | `string`  | -               | -       |
| **disableAutoClose** | keep the menu open after the item is chosen | `boolean` | -               | `true`  |

<Attributes.Title>Menu.Sub.Props</Attributes.Title>

| Attribute    | Description                         | Type             | Accepted values | Default |
| ------------ | ----------------------------------- | ---------------- | --------------- | ------- |
| **label**    | text of the item that opens it      | `ReactNode`      | -               | -       |
| **icon**     | shown before the label              | `ReactNode`      | -               | -       |
| **disabled** | the submenu cannot be opened        | `boolean`        | -               | `false` |
| ...          | native props, passed to the item    | `HTMLAttributes` | -               | -       |

<Attributes.Title>Menu.Label and Menu.Divider</Attributes.Title>

Both accept native props. `Menu.Label` is a title for the items below it, and `Menu.Divider` is a line between groups.

<Attributes.Title>Ref</Attributes.Title>

The `ref` of `Menu` points at the element around the trigger. The `ref` of each item, of `Menu.Label` and of `Menu.Divider` points at its own element, and the `ref` of `Menu.Sub` at the item that opens it.

<Attributes.Title>Accessibility</Attributes.Title>

The trigger gets `aria-haspopup="menu"` and `aria-expanded`. The list is a `menu`, named by the trigger, with `menuitem`, `menuitemcheckbox` and `menuitemradio` items. A radio group is a `group`; name it with `aria-label`. The `shortcut` is only visual: to announce it, pass `aria-keyshortcuts`, like `aria-keyshortcuts="Meta+E"`.

| Key                   | Action                                                     |
| --------------------- | ---------------------------------------------------------- |
| Arrow Down and Up     | On the trigger, open on the first or the last item. In the menu, move between the items |
| Enter and Space       | Choose the focused item, or open its submenu               |
| Home and End          | Go to the first or the last item                           |
| Arrow Right           | Open the submenu of the focused item                       |
| Arrow Left            | Close the submenu and go back to its item                  |
| Escape                | Close the submenu, or the menu and focus the trigger       |
| Tab                   | Close the menu and focus the trigger                       |
| Letters               | Go to the next item that starts with what was typed        |

Disabled items are skipped by the keyboard.

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Modal, Button, Code, useModal, Grid, Text } from 'core'
import { useState } from 'react'

export const meta = {
  title: 'Modal',
  description:
    'Display popup content that requires attention or provides additional information.',
  sidebar: 'components',
  group: 'Components',
  index: 24
}

## Modal

Display popup content that requires attention or provides additional information.
If you just need to prompt for a text message, try component [Toast](/docs/hooks/use-toast).

The Modal contain an additional Hooks, see subsection [useModal](/docs/hooks/use-modal) for details.

<Playground
  title="General"
  desc="Use `visible` control whether `Modal` is displayed."
  scope={{ Modal, Button, useState, Grid }}
  code={`
() => {
  const [state, setState] = useState(false)
  const handler = () => setState(true)
  const closeHandler = (event) => {
    setState(false)
    console.log('closed')
  }
  return (
    <Grid.Container gap={2}>
      <Grid>
        <Button auto onClick={handler}>
          Show Modal
        </Button>
        <Modal visible={state} onClose={() => setState(false)}>
          <Modal.Title>Modal</Modal.Title>
          <Modal.Subtitle>Example of a modal</Modal.Subtitle>
          <Modal.Content>
            <p>Demo content for the modal.</p>
          </Modal.Content>
          <Modal.Action passive onClick={() => setState(false)}>
            Cancel
          </Modal.Action>
          <Modal.Action>Accepted</Modal.Action>
        </Modal>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Playground
  title="With useModal"
  desc="Use `hooks` for easier control `Modal`."
  scope={{ Modal, Button, Grid, useModal }}
  code={`
() => {
  const { visible, setVisible, bindings } = useModal()
  return (
    <Grid.Container gap={2}>
      <Grid>
        <Button auto onClick={() => setVisible(true)}>
          Show Modal
        </Button>
        <Modal {...bindings}>
          <Modal.Title>Modal</Modal.Title>
          <Modal.Subtitle>Example of a modal</Modal.Subtitle>
          <Modal.Content>
            <p>Demo content for the modal.</p>
          </Modal.Content>
          <Modal.Action passive onClick={() => setVisible(false)}>
            Cancel
          </Modal.Action>
          <Modal.Action>Accepted</Modal.Action>
        </Modal>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Playground
  title="Without Actions"
  desc="Hide all action buttons."
  scope={{ Modal, Button, Grid, useState }}
  code={`
() => {
  const [state, setState] = useState(false)
  const handler = () => setState(true)
  const closeHandler = (event) => {
    setState(false)
    console.log('closed')
  }
  return (
    <Grid.Container gap={2}>
      <Grid>
        <Button auto onClick={handler}>
          Show Modal
        </Button>
        <Modal visible={state} onClose={() => setState(false)}>
          <Modal.Title>Modal</Modal.Title>
          <Modal.Subtitle>Example of a modal</Modal.Subtitle>
          <Modal.Content>
            <p>Demo content for the modal.</p>
          </Modal.Content>
        </Modal>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Playground
  title="Disable Action"
  desc="Disable one of the buttons."
  scope={{ Modal, Button, Grid, useState }}
  code={`
() => {
  const [state, setState] = useState(false)
  const handler = () => setState(true)
  const closeHandler = (event) => {
    setState(false)
    console.log('closed')
  }
  return (
    <>
      <Button auto onClick={handler}>Show Modal</Button>
      <Modal visible={state} onClose={closeHandler}>
        <Modal.Title>Modal</Modal.Title>
        <Modal.Subtitle>Example of a modal</Modal.Subtitle>
        <Modal.Content>
          <p>Demo content for the modal.</p>
        </Modal.Content>
        <Modal.Action passive onClick={() => setState(false)}>Cancel</Modal.Action>
        <Modal.Action disabled>Submit</Modal.Action>
      </Modal>
    </>
  )
}
`}
/>

<Playground
  title="Customized"
  desc="Custom `width` or `className`."
  scope={{ Modal, Button, Grid, useModal }}
  code={`
() => {
  const { setVisible, bindings } = useModal()
  return (
    <Grid.Container gap={2}>
      <Grid>
        <Button auto onClick={() => setVisible(true)}>
          Show Modal
        </Button>
        <Modal width="35rem" {...bindings}>
          <Modal.Title>My Favorites</Modal.Title>
          <Modal.Content>
            <p>This is the width I want.</p>
          </Modal.Content>
        </Modal>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Playground
  title="Loading"
  desc="You can use loading in `Modal.Action` with the property `loading`."
  scope={{ Modal, Button, Grid, useModal }}
  code={`
() => {
  const { visible, setVisible, bindings } = useModal()
  return (
    <Grid.Container gap={2}>
      <Grid>
        <Button auto onClick={() => setVisible(true)}>
          Show Modal
        </Button>
        <Modal {...bindings}>
          <Modal.Title>Modal</Modal.Title>
          <Modal.Subtitle>Example of a modal</Modal.Subtitle>
          <Modal.Content>
            <p>Demo content for the modal.</p>
          </Modal.Content>
          <Modal.Action passive onClick={() => setVisible(false)}>
            Cancel
          </Modal.Action>
          <Modal.Action loading>Accepted</Modal.Action>
        </Modal>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Playground
  title="Overlong"
  desc="Whether it is desktop or mobile, the content beyond the scope has been well handled."
  scope={{ Modal, Button, Grid, useModal }}
  code={`
() => {
  const { visible, setVisible, bindings } = useModal()
  return (
    <Grid.Container gap={2}>
      <Grid>
        <Button auto onClick={() => setVisible(true)}>
          Show Modal
        </Button>
        <Modal {...bindings}>
          <Modal.Title>Modal</Modal.Title>
          <Modal.Subtitle>Modal with a very large content</Modal.Subtitle>
          <Modal.Content>
            <p>
              React has been designed from the start for gradual adoption, and
              you can use as little or as much React as you need. Whether you
              want to get a taste of React, add some interactivity to a simple
              HTML page, or start a complex React-powered app, the links in this
              section will help you get started.
            </p>
            <p>
              React has been designed from the start for gradual adoption, and
              you can use as little or as much React as you need. Whether you
              want to get a taste of React, add some interactivity to a simple
              HTML page, or start a complex React-powered app, the links in this
              section will help you get started.
            </p>
            <p>
              React has been designed from the start for gradual adoption, and
              you can use as little or as much React as you need. Whether you
              want to get a taste of React, add some interactivity to a simple
              HTML page, or start a complex React-powered app, the links in this
              section will help you get started.
            </p>
            <p>
              React has been designed from the start for gradual adoption, and
              you can use as little or as much React as you need. Whether you
              want to get a taste of React, add some interactivity to a simple
              HTML page, or start a complex React-powered app, the links in this
              section will help you get started.
            </p>
            <p>
              React has been designed from the start for gradual adoption, and
              you can use as little or as much React as you need. Whether you
              want to get a taste of React, add some interactivity to a simple
              HTML page, or start a complex React-powered app, the links in this
              section will help you get started.
            </p>
            <p>
              React has been designed from the start for gradual adoption, and
              you can use as little or as much React as you need. Whether you
              want to get a taste of React, add some interactivity to a simple
              HTML page, or start a complex React-powered app, the links in this
              section will help you get started.
            </p>
            <p>
              React has been designed from the start for gradual adoption, and
              you can use as little or as much React as you need. Whether you
              want to get a taste of React, add some interactivity to a simple
              HTML page, or start a complex React-powered app, the links in this
              section will help you get started.
            </p>
          </Modal.Content>
          <Modal.Action passive onClick={() => setVisible(false)}>
            Cancel
          </Modal.Action>
          <Modal.Action>Accepted</Modal.Action>
        </Modal>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Playground
  title="Confirm a destructive action"
  desc="Name the action on both buttons, say what is lost, and show progress on the one that runs it."
  scope={{ Modal, Button, Grid, Text, useModal }}
  code={`
() => {
  const { setVisible, bindings } = useModal()
  const [deleting, setDeleting] = React.useState(false)
  const [done, setDone] = React.useState(false)
  const remove = () => {
    setDeleting(true)
    setTimeout(() => {
      setDeleting(false)
      setDone(true)
      setVisible(false)
    }, 1200)
  }
  return (
    <Grid.Container gap={2} alignItems="center">
      <Grid>
        <Button auto type="error" ghost onClick={() => { setDone(false); setVisible(true) }}>
          Delete project
        </Button>
      </Grid>
      <Grid>
        {done && <Text small type="secondary">Project deleted.</Text>}
      </Grid>
      <Modal {...bindings}>
        <Modal.Title>Delete this project?</Modal.Title>
        <Modal.Content>
          <p>All 14 files and 3 members lose access. This cannot be undone.</p>
        </Modal.Content>
        <Modal.Action passive onClick={() => setVisible(false)}>Keep project</Modal.Action>
        <Modal.Action loading={deleting} onClick={remove}>Delete project</Modal.Action>
      </Modal>
    </Grid.Container>
  )
}
`}
/>

<Attributes edit="/content/docs/components/modal.mdx">
<Attributes.Title>Modal.Props</Attributes.Title>

| Attribute                | Description                      | Type                      | Accepted values                         | Default |
| ------------------------ | -------------------------------- | ------------------------- | --------------------------------------- | ------- |
| **visible**              | open or close                    | `boolean`                 | -                                       | `false` |
| **onClose**              | open event                       | `() => void`              | -                                       | -       |
| **onContentClick**       | event from modal content         | `(e: MouseEvent) => void` | -                                       | -       |
| **wrapClassName**        | className of the modal dialog    | `string`                  | -                                       | -       |
| **keyboard**             | press Esc to close modal         | `boolean`                 | -                                       | `true`  |
| **disableBackdropClick** | click background and don't close | `boolean`                 | -                                       | `false` |
| **role**                 | use `alertdialog` for a message that needs an answer | `'dialog'` / `'alertdialog'` | -                                    | `dialog` |
| **aria-label**           | name of the dialog when there is no `Modal.Title` | `string`                  | -                                       | -       |
| ...                      | native props                     | `HTMLAttributes`          | `'autoFocus', 'name', 'className', ...` | -       |

The dialog is named by `Modal.Title` and described by `Modal.Subtitle` on its own. Without a title, pass `aria-label` or `aria-labelledby`.

<Attributes.Title>Modal.Title.Props</Attributes.Title>

| Attribute | Description  | Type             | Accepted values          | Default |
| --------- | ------------ | ---------------- | ------------------------ | ------- |
| ...       | native props | `HTMLAttributes` | `'id', 'className', ...` | -       |

<Attributes.Title>Modal.Subtitle.Props</Attributes.Title>

| Attribute | Description  | Type             | Accepted values          | Default |
| --------- | ------------ | ---------------- | ------------------------ | ------- |
| ...       | native props | `HTMLAttributes` | `'id', 'className', ...` | -       |

<Attributes.Title>Modal.Content.Props</Attributes.Title>

| Attribute | Description  | Type             | Accepted values          | Default |
| --------- | ------------ | ---------------- | ------------------------ | ------- |
| ...       | native props | `HTMLAttributes` | `'id', 'className', ...` | -       |

<Attributes.Title>Modal.Action.Props</Attributes.Title>

| Attribute    | Description            | Type                                               | Accepted values          | Default |
| ------------ | ---------------------- | -------------------------------------------------- | ------------------------ | ------- |
| **passive**  | display passive mode   | `boolean`                                          | -                        | `false` |
| **disabled** | disable current action | `boolean`                                          | -                        | `false` |
| **onClick**  | click handler          | [(e: ModalActionEvent) => void](#modalactionevent) | -                        | -       |
| **loading**  | show loading           | `boolean`                                          | -                        | `false` |
| ...          | native props           | `ButtonHTMLAttributes`                             | `'id', 'className', ...` | -       |

<Attributes.Title>useModal</Attributes.Title>

```ts
type useModal = (initialVisible: boolean) => {
  visible: boolean
  setVisible: Dispatch<SetStateAction<boolean>>
  currentRef: MutableRefObject<boolean>
  bindings: {
    visible: boolean
    onClose: () => void
  }
}
```

<Attributes.Title>ModalActionEvent</Attributes.Title>

```ts
type ModalActionEvent = MouseEvent<HTMLButtonElement> & {
  close: () => void
}
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Note, Grid } from 'core'

export const meta = {
  title: 'Note',
  description:
    'Display text that requires attention or provides additional information.',
  sidebar: 'components',
  group: 'Components',
  index: 25
}

## Note

Display text that requires attention or provides additional information.

<Playground
  desc="Show a piece of text or components."
  scope={{ Note, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Note>Check payment pending.</Note>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Types"
  desc="You can apply a types differents with the `type` prop."
  scope={{ Note, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Note>Check payment pending.</Note>
  </Grid>
  <Grid>
    <Note type="primary">Check payment pending.</Note>
  </Grid>
  <Grid>
    <Note type="secondary">Check payment pending.</Note>
  </Grid>
  <Grid>
    <Note type="success">Check payment pending.</Note>
  </Grid>
  <Grid>
    <Note type="warning">Check payment pending.</Note>
  </Grid>
  <Grid>
    <Note type="error">Check payment pending.</Note>
  </Grid>
  <Grid>
    <Note type="info">Check payment pending.</Note>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Hidden Label"
  desc="`Note` component with a show/hide label."
  scope={{ Note, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Note label={false}>Demo note!</Note>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Custom Label"
  desc="You can change custom label of the `Note` with the property `label`."
  scope={{ Note, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Note label="custom">Customize a note.</Note>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Filled Variant"
  desc="You can change the filled variant of the `Note` with the property `filled`."
  scope={{ Note, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Note label="custom" filled>
      Customize a note.
    </Note>
  </Grid>
  <Grid>
    <Note type="primary" label="primary" filled>
      Check payment pending.
    </Note>
  </Grid>
  <Grid>
    <Note type="secondary" label="secondary" filled>
      Check payment pending.
    </Note>
  </Grid>
  <Grid>
    <Note type="success" label="success" filled>
      Check payment pending.
    </Note>
  </Grid>
  <Grid>
    <Note type="warning" label="warning" filled>
      Check payment pending.
    </Note>
  </Grid>
  <Grid>
    <Note type="error" label="error" filled>
      Check payment pending.
    </Note>
  </Grid>
  <Grid>
    <Note type="secondary" filled>
      Check payment pending.
    </Note>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Page alerts"
  desc="Say what happened in the label and what to do in the text. Use the type that matches how urgent it is."
  scope={{ Note, Grid }}
  code={`
<Grid.Container direction="column" gap={1}>
  <Grid>
    <Note type="success" label="Saved">Your changes are live.</Note>
  </Grid>
  <Grid>
    <Note type="warning" label="Plan limit">You used 9 of 10 projects. Upgrade to add more.</Note>
  </Grid>
  <Grid>
    <Note type="error" label="Payment failed">We could not charge your card. Update it to keep your plan.</Note>
  </Grid>
</Grid.Container>
`}
/>

<Attributes edit="/content/docs/components/note.mdx">
<Attributes.Title>Note.Props</Attributes.Title>

| Attribute  | Description               | Type                 | Accepted values          | Default   |
| ---------- | ------------------------- | -------------------- | ------------------------ | --------- |
| **type**   | note type                        | `NoteTypes`           | [NoteTypes](#nodetypes)  | `default` |
| **label**  | show label or custom text        | `boolean` / `string`  | -                        | -         |
| **filled** | filled variant: fill color       | `boolean`             | -                        | `false`   |
| **light**  | light variant: tinted background | `boolean`             | -                        | `false`   |
| **subtle** | subtle variant: no border        | `boolean`             | -                        | `false`   |
| ...        | native props                     | `HTMLAttributes`      | `'id', 'className', ...` | -         |

<Attributes.Title>NoteTypes</Attributes.Title>

```ts
type NoteTypes =
  | 'default'
  | 'primary'
  | 'secondary'
  | 'success'
  | 'warning'
  | 'error'
  | 'info'
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { NumberInput, Grid, Text, Code } from 'core'

export const meta = {
  title: 'Number Input',
  description:
    'A field for numbers, with buttons and arrow keys to step the value and limits it stays within.',
  sidebar: 'components',
  group: 'Components',
  index: 52
}

## Number Input

A field for numbers. The buttons and the arrow keys step the value, and it
stays within `min` and `max`.

<Playground
  desc="Name the field with `aria-label`, or with a label passed as children."
  scope={{ NumberInput, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <NumberInput aria-label="Quantity" initialValue={1} min={0} max={10} />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Step and precision"
  desc="`step` sets how much each click or arrow adds. The value keeps the decimal places of `step`, or the ones set in `precision`."
  scope={{ NumberInput, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <NumberInput aria-label="Price" initialValue={9.9} step={0.1} min={0} />
  </Grid>
  <Grid>
    <NumberInput aria-label="Percent" initialValue={50} step={5} min={0} max={100} />
  </Grid>
  <Grid>
    <NumberInput aria-label="Weight" initialValue={1.25} step={1} precision={2} />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Without controls"
  desc="Hide the buttons with `hideControls`. The arrow keys still step the value."
  scope={{ NumberInput }}
  code={`
<NumberInput aria-label="Year" placeholder="Year" min={1900} max={2100} hideControls />
`}
/>

<Playground
  title="Error"
  desc="Show a message with `error` and `errorMessage`. Say what happened and how to fix it."
  scope={{ NumberInput }}
  code={`
() => {
  const [guests, setGuests] = React.useState(12)
  const tooMany = guests !== null && guests > 10
  return (
    <NumberInput
      value={guests}
      onChange={setGuests}
      min={1}
      error={tooMany}
      errorMessage="The room fits 10 people. Remove a guest to continue."
    >
      Guests
    </NumberInput>
  )
}
`}
/>

<Playground
  title="Controlled"
  desc="`onChange` receives the number, or `null` when the field is empty."
  scope={{ NumberInput, Grid, Text }}
  code={`
() => {
  const [value, setValue] = React.useState(3)
  return (
    <Grid.Container gap={2} alignItems="center">
      <Grid>
        <NumberInput aria-label="Amount" value={value} onChange={setValue} />
      </Grid>
      <Grid>
        <Text my={0}>Value: {value === null ? 'empty' : value}</Text>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Playground
  title="Variants"
  desc="Use `filled`, `light`, `ghost` or `subtle` with a `type` to change the surface of the field."
  scope={{ NumberInput, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <NumberInput type="primary" filled initialValue={5} />
  </Grid>
  <Grid>
    <NumberInput type="secondary" filled initialValue={5} />
  </Grid>
  <Grid>
    <NumberInput type="success" filled initialValue={5} />
  </Grid>
  <Grid>
    <NumberInput type="warning" filled initialValue={5} />
  </Grid>
  <Grid>
    <NumberInput type="error" filled initialValue={5} />
  </Grid>
  <Grid>
    <NumberInput type="info" filled initialValue={5} />
  </Grid>
  <Grid>
    <NumberInput type="primary" light initialValue={5} />
  </Grid>
  <Grid>
    <NumberInput type="secondary" light initialValue={5} />
  </Grid>
  <Grid>
    <NumberInput type="success" light initialValue={5} />
  </Grid>
  <Grid>
    <NumberInput type="warning" light initialValue={5} />
  </Grid>
  <Grid>
    <NumberInput type="error" light initialValue={5} />
  </Grid>
  <Grid>
    <NumberInput type="info" light initialValue={5} />
  </Grid>
  <Grid>
    <NumberInput type="primary" ghost initialValue={5} />
  </Grid>
  <Grid>
    <NumberInput type="secondary" ghost initialValue={5} />
  </Grid>
  <Grid>
    <NumberInput type="success" ghost initialValue={5} />
  </Grid>
  <Grid>
    <NumberInput type="warning" ghost initialValue={5} />
  </Grid>
  <Grid>
    <NumberInput type="error" ghost initialValue={5} />
  </Grid>
  <Grid>
    <NumberInput type="info" ghost initialValue={5} />
  </Grid>
  <Grid>
    <NumberInput type="primary" subtle initialValue={5} />
  </Grid>
  <Grid>
    <NumberInput type="secondary" subtle initialValue={5} />
  </Grid>
  <Grid>
    <NumberInput type="success" subtle initialValue={5} />
  </Grid>
  <Grid>
    <NumberInput type="warning" subtle initialValue={5} />
  </Grid>
  <Grid>
    <NumberInput type="error" subtle initialValue={5} />
  </Grid>
  <Grid>
    <NumberInput type="info" subtle initialValue={5} />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Disabled and read only"
  scope={{ NumberInput, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <NumberInput aria-label="Disabled" initialValue={4} disabled />
  </Grid>
  <Grid>
    <NumberInput aria-label="Read only" initialValue={4} readOnly />
  </Grid>
</Grid.Container>
`}
/>

<Attributes edit="/content/docs/components/number-input.mdx">
<Attributes.Title>NumberInput.Props</Attributes.Title>

| Attribute        | Description                                               | Type                                                | Accepted values                                                            | Default            |
| ---------------- | --------------------------------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------------- | ------------------ |
| **value**        | the number, to control the field                          | `number` / `null`                                   | -                                                                          | -                  |
| **initialValue** | the number at the start                                   | `number` / `null`                                   | -                                                                          | `null`             |
| **onChange**     | called with the number, or `null` when the field is empty | <Code>(value: number &#124; null) =&gt; void</Code> | -                                                                          | -                  |
| **min**          | lowest value                                              | `number`                                            | -                                                                          | -                  |
| **max**          | highest value                                             | `number`                                            | -                                                                          | -                  |
| **step**         | how much a button or an arrow key adds                    | `number`                                            | -                                                                          | `1`                |
| **precision**    | decimal places kept                                       | `number`                                            | -                                                                          | the ones of `step` |
| **type**         | color of the field                                        | `NormalTypes`                                       | `'default', 'primary', 'secondary', 'success', 'warning', 'error', 'info'` | `default`          |
| **hideControls** | hide the buttons                                          | `boolean`                                           | -                                                                          | `false`            |
| **error**        | mark the value as invalid                                 | `boolean`                                           | -                                                                          | `false`            |
| **errorMessage** | text shown below the field with `error`                   | `string`                                            | -                                                                          | -                  |
| **disabled**     | disable the field                                         | `boolean`                                           | -                                                                          | `false`            |
| **rounded**      | round the corners                                         | `boolean`                                           | -                                                                          | `false`            |
| **filled**       | filled variant                                            | `boolean`                                           | -                                                                          | `false`            |
| **light**        | light variant                                             | `boolean`                                           | -                                                                          | `false`            |
| **ghost**        | outline variant                                           | `boolean`                                           | -                                                                          | `false`            |
| **subtle**       | subtle variant                                            | `boolean`                                           | -                                                                          | `false`            |
| **readOnly**     | show the value without letting it change                  | `boolean`                                           | -                                                                          | `false`            |
| **children**     | label shown above the field                               | `ReactNode`                                         | -                                                                          | -                  |
| ...              | native props, passed to the input                         | `InputHTMLAttributes`                               | `'aria-label', 'name', 'placeholder', ...`                                 | -                  |

<Attributes.Title>Typing and limits</Attributes.Title>

The field accepts digits, a minus sign and one decimal separator, a dot or a comma. While the user types, `onChange` receives the number as it is. When the field loses the focus, the value is kept within `min` and `max` and rounded to `precision`. The buttons and the keys never go past the limits.

<Attributes.Title>Ref</Attributes.Title>

The `ref` points at the `input`.

<Attributes.Title>Accessibility</Attributes.Title>

The input has `role="spinbutton"` with `aria-valuenow`, `aria-valuemin` and `aria-valuemax`. The buttons are named Increase and Decrease and stay out of the tab order, since the keys do the same from the input. With `error`, the input has `aria-invalid` and is described by the message.

| Key               | Action                         |
| ----------------- | ------------------------------ |
| Arrow Up and Down | Add or subtract `step`         |
| Page Up and Down  | Add or subtract ten steps      |
| Home and End      | Go to `min` or `max`, when set |

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { ComponentTag } from 'src/components'
import { Grid, Spacer } from 'core'

export const meta = {
  title: 'Overview',
  description: 'Browse every Bolio UI component, grouped by what it does.',
  sidebar: 'components',
  group: 'Components',
  index: 0
}

## Overview

Browse every component, grouped by what it does.

<Spacer h={2} />

### Layout

<Grid.Container gap={1}>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/alert">Alert</a><ComponentTag raised href="/docs/components/alert" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/chip">Chip</a><ComponentTag raised href="/docs/components/chip" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/col">Col</a><ComponentTag raised href="/docs/components/col" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/container">Container</a><ComponentTag raised href="/docs/components/container" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/divider">Divider</a><ComponentTag raised href="/docs/components/divider" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/grid">Grid</a><ComponentTag raised href="/docs/components/grid" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/mention">Mention</a><ComponentTag raised href="/docs/components/mention" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/page">Page</a><ComponentTag raised href="/docs/components/page" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/row">Row</a><ComponentTag raised href="/docs/components/row" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/splitter">Splitter</a><ComponentTag raised href="/docs/components/splitter" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/section">Section</a><ComponentTag raised href="/docs/components/section" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/spacer">Spacer</a><ComponentTag raised href="/docs/components/spacer" />
  </Grid>
</Grid.Container>

<Spacer h={2} />

### Typography

<Grid.Container gap={1}>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/code">Code</a><ComponentTag raised href="/docs/components/code" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/description">Description</a><ComponentTag raised href="/docs/components/description" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/keyboard">Keyboard</a><ComponentTag raised href="/docs/components/keyboard" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/link">Link</a><ComponentTag raised href="/docs/components/link" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/text">Text</a><ComponentTag raised href="/docs/components/text" />
  </Grid>
</Grid.Container>

<Spacer h={2} />

### Buttons

<Grid.Container gap={1}>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/button">Button</a><ComponentTag raised href="/docs/components/button" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/button-dropdown">Button Dropdown</a><ComponentTag raised href="/docs/components/button-dropdown" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/button-group">Button Group</a><ComponentTag raised href="/docs/components/button-group" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/menu">Menu</a><ComponentTag raised href="/docs/components/menu" />
  </Grid>
</Grid.Container>

<Spacer h={2} />

### Forms

<Grid.Container gap={1}>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/checkbox">Checkbox</a><ComponentTag raised href="/docs/components/checkbox" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/color-input">Color Input</a><ComponentTag raised href="/docs/components/color-input" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/color-picker">Color Picker</a><ComponentTag raised href="/docs/components/color-picker" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/combobox">Combobox</a><ComponentTag raised href="/docs/components/combobox" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/date-picker">DatePicker</a><ComponentTag raised href="/docs/components/date-picker" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/date-range-picker">DateRangePicker</a><ComponentTag raised href="/docs/components/date-range-picker" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/dropzone">Dropzone</a><ComponentTag raised href="/docs/components/dropzone" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/fieldset">Fieldset</a><ComponentTag raised href="/docs/components/fieldset" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/input">Input</a><ComponentTag raised href="/docs/components/input" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/number-input">Number Input</a><ComponentTag raised href="/docs/components/number-input" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/tags-input">Tags Input</a><ComponentTag raised href="/docs/components/tags-input" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/pin-input">Pin Input</a><ComponentTag raised href="/docs/components/pin-input" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/radio">Radio</a><ComponentTag raised href="/docs/components/radio" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/rating">Rating</a><ComponentTag raised href="/docs/components/rating" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/segmented-control">Segmented Control</a><ComponentTag raised href="/docs/components/segmented-control" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/select">Select</a><ComponentTag raised href="/docs/components/select" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/slider">Slider</a><ComponentTag raised href="/docs/components/slider" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/textarea">Textarea</a><ComponentTag raised href="/docs/components/textarea" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/hooks/use-toast">Toast</a>
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/toggle">Toggle</a><ComponentTag raised href="/docs/components/toggle" />
  </Grid>
</Grid.Container>

<Spacer h={2} />

### Data Display

<Grid.Container gap={1}>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/avatar">Avatar</a><ComponentTag raised href="/docs/components/avatar" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/badge">Badge</a><ComponentTag raised href="/docs/components/badge" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/calendar">Calendar</a><ComponentTag raised href="/docs/components/calendar" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/card">Card</a><ComponentTag raised href="/docs/components/card" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/carousel">Carousel</a><ComponentTag raised href="/docs/components/carousel" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/collapse">Collapse</a><ComponentTag raised href="/docs/components/collapse" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/display">Display</a><ComponentTag raised href="/docs/components/display" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/dot">Dot</a><ComponentTag raised href="/docs/components/dot" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/icons">Icons</a><ComponentTag raised href="/docs/components/icons" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/image">Image</a><ComponentTag raised href="/docs/components/image" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/image-zoom">Image Zoom</a><ComponentTag raised href="/docs/components/image-zoom" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/marquee">Marquee</a><ComponentTag raised href="/docs/components/marquee" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/snippet">Snippet</a><ComponentTag raised href="/docs/components/snippet" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/stat">Stat</a><ComponentTag raised href="/docs/components/stat" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/table">Table</a><ComponentTag raised href="/docs/components/table" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/tag">Tag</a><ComponentTag raised href="/docs/components/tag" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/timeline">Timeline</a><ComponentTag raised href="/docs/components/timeline" />
  </Grid>
</Grid.Container>

<Spacer h={2} />

### Feedback

<Grid.Container gap={1}>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/capacity">Capacity</a><ComponentTag raised href="/docs/components/capacity" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/empty-state">Empty State</a><ComponentTag raised href="/docs/components/empty-state" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/loading">Loading</a><ComponentTag raised href="/docs/components/loading" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/note">Note</a><ComponentTag raised href="/docs/components/note" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/progress">Progress</a><ComponentTag raised href="/docs/components/progress" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/skeleton">Skeleton</a><ComponentTag raised href="/docs/components/skeleton" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/spinner">Spinner</a><ComponentTag raised href="/docs/components/spinner" />
  </Grid>
</Grid.Container>

<Spacer h={2} />

### Overlays

<Grid.Container gap={1}>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/drawer">Drawer</a><ComponentTag raised href="/docs/components/drawer" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/context-menu">Context Menu</a><ComponentTag raised href="/docs/components/context-menu" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/modal">Modal</a><ComponentTag raised href="/docs/components/modal" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/popover">Popover</a><ComponentTag raised href="/docs/components/popover" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/toolbar">Toolbar</a><ComponentTag raised href="/docs/components/toolbar" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/tooltip">Tooltip</a><ComponentTag raised href="/docs/components/tooltip" />
  </Grid>
</Grid.Container>

<Spacer h={2} />

### Navigation

<Grid.Container gap={1}>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/breadcrumbs">Breadcrumbs</a><ComponentTag raised href="/docs/components/breadcrumbs" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/command">Command</a><ComponentTag raised href="/docs/components/command" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/pagination">Pagination</a><ComponentTag raised href="/docs/components/pagination" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/stepper">Stepper</a><ComponentTag raised href="/docs/components/stepper" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/tour">Tour</a><ComponentTag raised href="/docs/components/tour" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/tabs">Tabs</a><ComponentTag raised href="/docs/components/tabs" />
  </Grid>
  <Grid xs={12} sm={6} md={3}>
    <a href="/docs/components/tree">Tree</a><ComponentTag raised href="/docs/components/tree" />
  </Grid>
</Grid.Container>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Page, Button, Grid } from 'core'
import { Layout, Playground, Attributes } from 'src/components'
import MockPage from 'core/MdxWidgets/MockPage'

export const meta = {
  title: 'Page',
  description: 'Container of general for display page content.',
  sidebar: 'components',
  group: 'Components',
  index: 26
}

## Page

Container of general for display page content.

<Playground
  desc="The content will be displayed in the center."
  scope={{ Page, MockPage, Button, Grid }}
  code={`
() => {
  const Child = () => (
    <>
      <h2>Hi my dear!</h2>
      <p>This is an example to show the body of a page.</p>
    </>
  )
  const [visible, setVisible] = React.useState(false)
  return (
    <Grid.Container gap={2}>
      <Grid>
        <Button onClick={() => setVisible(true)} auto>
          View Page
        </Button>
        <MockPage visible={visible} onClose={() => setVisible(false)}>
          <Page>
            <Child />
          </Page>
        </MockPage>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Playground
  title="Content"
  desc="Add `Header` and `Footer` for better layout."
  scope={{ Page, MockPage, Button, Grid }}
  code={`
() => {
  const [visible, setVisible] = React.useState(false)
  return (
    <Grid.Container gap={2}>
      <Grid>
        <Button onClick={() => setVisible(true)} auto>
          Header, Body and Footer
        </Button>
        <MockPage visible={visible} onClose={() => setVisible(false)}>
          <Page>
            <Page.Header>
              <h2>Header</h2>
            </Page.Header>
            <Page.Content>
              <h2>Hi my dear!</h2>
              <p>This is an example to show the body of a page.</p>
            </Page.Content>
            <Page.Footer>
              <h2>Footer</h2>
            </Page.Footer>
          </Page>
        </MockPage>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Attributes edit="/content/docs/components/page.mdx">
<Attributes.Title>Page.Props</Attributes.Title>

| Attribute       | Description                        | Type                              | Accepted values          | Default   |
| --------------- | ---------------------------------- | --------------------------------- | ------------------------ | --------- |
| **render**      | render mode                        | [PageRenderMode](#pagerendermode) | -                        | `default` |
| **dotBackdrop** | show decorations in the background | `boolean`                         | -                        | `false`   |
| **dotSize**     | dot size in the background         | `CSSProperties`                   | -                        | `1px`     |
| **dotSpace**    | space multiple between each dot    | `number`                          | -                        | `1`       |
| ...             | native props                       | `HTMLAttributes`                  | `'id', 'className', ...` | -         |

<Attributes.Title>Page.Header.Props</Attributes.Title>

| Attribute  | Description  | Type             | Accepted values          | Default |
| ---------- | ------------ | ---------------- | ------------------------ | ------- |
| **center** | align center | `boolean`        | -                        | `false` |
| ...        | native props | `HTMLAttributes` | `'id', 'className', ...` | -       |

<Attributes.Title alias="Page.Body">Page.Content.Props</Attributes.Title>

| Attribute | Description  | Type             | Accepted values          | Default |
| --------- | ------------ | ---------------- | ------------------------ | ------- |
| ...       | native props | `HTMLAttributes` | `'id', 'className', ...` | -       |

<Attributes.Title>Page.Footer.Props</Attributes.Title>

| Attribute | Description  | Type             | Accepted values          | Default |
| --------- | ------------ | ---------------- | ------------------------ | ------- |
| ...       | native props | `HTMLAttributes` | `'id', 'className', ...` | -       |

<Attributes.Title>PageRenderMode</Attributes.Title>

```ts
type PageRenderMode =
  | 'default' // Normal rendering
  | 'effect' // Render after the first effect trigger
  | 'effect-seo' // like "effect", but prerender strings for SEO
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Pagination, Grid, Text } from 'core'
import {
  ChevronRight,
  ChevronLeft,
  ArrowRight,
  ArrowLeft,
  ArrowRightCircle,
  ArrowLeftCircle
} from '@bolio-ui/icons'

export const meta = {
  title: 'Pagination',
  description: 'Navigation and identification between multiple pages.',
  sidebar: 'components',
  group: 'Components',
  index: 27
}

## Pagination

Navigation and identification between multiple pages.

<Playground
  desc="The basic `Pagination` usage."
  scope={{ Pagination, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Pagination count={20} initialPage={3} />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Limit"
  desc="The maximum number of pages that can be displayed"
  scope={{ Pagination, Grid }}
  code={`
<Grid.Container gap={2} direction="column">
  <Grid>
    <Pagination count={10} limit={10} />
  </Grid>
  <Grid>
    <Pagination count={5} />
  </Grid>
  <Grid>
    <Pagination count={10} initialPage={6} limit={5} />
  </Grid>
  <Grid>
    <Pagination count={10} initialPage={6} />
  </Grid>
  <Grid>
    <Pagination count={30} initialPage={6} limit={10} />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Icon"
  desc="Customize buttons as icons."
  scope={{
    Grid,
    Pagination,
    ChevronRight,
    ChevronLeft,
    ArrowRight,
    ArrowLeft,
    ArrowRightCircle,
    ArrowLeftCircle
  }}
  code={`
<Grid.Container gap={2} direction="column">
  <Grid>
    <Pagination count={5}>
      <Pagination.Next>
        <ChevronRight />
      </Pagination.Next>
      <Pagination.Previous>
        <ChevronLeft />
      </Pagination.Previous>
    </Pagination>
  </Grid>
  <Grid>
    <Pagination count={5}>
      <Pagination.Next>
        <ArrowRight />
      </Pagination.Next>
      <Pagination.Previous>
        <ArrowLeft />
      </Pagination.Previous>
    </Pagination>
  </Grid>
  <Grid>
    <Pagination count={5}>
      <Pagination.Next>
        <ArrowRightCircle />
      </Pagination.Next>
      <Pagination.Previous>
        <ArrowLeftCircle />
      </Pagination.Previous>
    </Pagination>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Paginated list"
  desc="Compute the page of items from `page`, and show the range next to the list."
  scope={{ Pagination, Grid, Text }}
  code={`
() => {
  const customers = Array.from({ length: 23 }, (_, index) => 'Customer ' + (index + 1))
  const size = 5
  const [page, setPage] = React.useState(1)
  const shown = customers.slice((page - 1) * size, page * size)
  return (
    <Grid.Container direction="column" gap={1}>
      {shown.map((name) => (
        <Grid key={name}>
          <Text my={0}>{name}</Text>
        </Grid>
      ))}
      <Grid>
        <Text small type="secondary">
          {(page - 1) * size + 1} to {Math.min(page * size, customers.length)} of {customers.length}
        </Text>
      </Grid>
      <Grid>
        <Pagination count={Math.ceil(customers.length / size)} page={page} onChange={setPage} />
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Attributes edit="/content/docs/components/pagination.mdx">
<Attributes.Title>Pagination.Props</Attributes.Title>

| Attribute       | Description                  | Type                     | Accepted values          | Default |
| --------------- | ---------------------------- | ------------------------ | ------------------------ | ------- |
| **initialPage** | the page selected by default | `number`                 | -                        | 1       |
| **page**        | current page                 | `number`                 | -                        | 1       |
| **count**       | the total number of pages    | `number`                 | -                        | 1       |
| **limit**       | limit of display page        | `number`                 | -                        | 7       |
| **onChange**    | change event                 | `(page: number) => void` | -                        | -       |
| ...             | native props                 | `HTMLAttributes`         | `'id', 'className', ...` | -       |

<Attributes.Title>Pagination.Previous.Props</Attributes.Title>

| Attribute | Description  | Type                   | Accepted values          | Default |
| --------- | ------------ | ---------------------- | ------------------------ | ------- |
| ...       | native props | `ButtonHTMLAttributes` | `'id', 'className', ...` | -       |

<Attributes.Title>Pagination.Next.Props</Attributes.Title>

| Attribute | Description  | Type                   | Accepted values          | Default |
| --------- | ------------ | ---------------------- | ------------------------ | ------- |
| ...       | native props | `ButtonHTMLAttributes` | `'id', 'className', ...` | -       |

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { PinInput, Grid, Text } from 'core'

export const meta = {
  title: 'Pin Input',
  description:
    'A row of boxes to type a short code, like a verification code or a PIN.',
  sidebar: 'components',
  group: 'Components',
  index: 61
}

## Pin Input

A row of boxes to type a short code, like a verification code or a PIN. Each
character goes to its own box and the focus moves ahead by itself.

<Playground
  desc="Name the group with `aria-label`. With `numeric`, only digits are accepted."
  scope={{ PinInput, Grid }}
  code={`
<Grid.Container gap={2} direction="column">
  <Grid>
    <PinInput aria-label="Verification code" numeric />
  </Grid>
  <Grid>
    <PinInput aria-label="Invite code" length={4} />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Controlled"
  desc="Use `value` and `onChange` to keep the code in your own state, and `onComplete` to react when every box is filled."
  scope={{ PinInput, Grid, Text }}
  code={`
() => {
  const [code, setCode] = React.useState('')
  const [done, setDone] = React.useState(false)
  return (
    <Grid.Container gap={2} direction="column">
      <Grid>
        <PinInput
          aria-label="Verification code"
          length={4}
          numeric
          value={code}
          onChange={(next) => { setCode(next); setDone(false) }}
          onComplete={() => setDone(true)}
        />
      </Grid>
      <Grid>
        <Text p>{done ? 'Code ' + code + ' is complete.' : 'Typed so far: ' + (code || 'nothing')}</Text>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Playground
  title="Masked"
  desc="With `mask`, the characters are hidden, like in a password."
  scope={{ PinInput }}
  code={`
<PinInput aria-label="PIN" length={4} mask numeric />
`}
/>

<Playground
  title="Variants"
  desc="Use `filled`, `light`, `ghost` or `subtle` with a `type` to change the surface of the boxes."
  scope={{ PinInput, Grid }}
  code={`
<Grid.Container gap={2} direction="column">
  <Grid>
    <PinInput type="primary" filled length={4} aria-label="Filled" initialValue="12" />
  </Grid>
  <Grid>
    <PinInput type="success" light length={4} aria-label="Light" initialValue="12" />
  </Grid>
  <Grid>
    <PinInput type="info" ghost rounded length={4} aria-label="Ghost" initialValue="12" />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Error and disabled"
  desc="`error` turns the boxes red and marks them as invalid. `disabled` locks them."
  scope={{ PinInput, Grid }}
  code={`
<Grid.Container gap={2} direction="column">
  <Grid>
    <PinInput error length={4} aria-label="Wrong code" initialValue="1234" />
  </Grid>
  <Grid>
    <PinInput disabled length={4} aria-label="Locked code" initialValue="1234" />
  </Grid>
</Grid.Container>
`}
/>

<Attributes edit="/content/docs/components/pin-input.mdx">
<Attributes.Title>PinInput.Props</Attributes.Title>

| Attribute        | Description                                                  | Type                                          | Accepted values                                                            | Default                    |
| ---------------- | ------------------------------------------------------------ | --------------------------------------------- | -------------------------------------------------------------------------- | -------------------------- |
| **length**       | number of boxes                                              | `number`                                      | -                                                                          | `6`                        |
| **value**        | the code, to control the component                           | `string`                                      | -                                                                          | -                          |
| **initialValue** | the code at the start                                        | `string`                                      | -                                                                          | `''`                       |
| **onChange**     | called with the code each time it changes                    | `(value: string) => void`                     | -                                                                          | -                          |
| **onComplete**   | called with the code when every box is filled                | `(value: string) => void`                     | -                                                                          | -                          |
| **numeric**      | accepts only digits and opens the numeric keyboard           | `boolean`                                     | -                                                                          | `false`                    |
| **mask**         | hides the characters                                         | `boolean`                                     | -                                                                          | `false`                    |
| **boxLabel**     | name of each box for screen readers                          | `(index: number, length: number) => string`   | -                                                                          | `Character 1 of 6`         |
| **disabled**     | disable the component                                        | `boolean`                                     | -                                                                          | `false`                    |
| **error**        | red boxes, marked as invalid                                 | `boolean`                                     | -                                                                          | `false`                    |
| **type**         | color of the boxes                                           | `NormalTypes`                                 | `'default', 'primary', 'secondary', 'success', 'warning', 'error', 'info'` | `default`                  |
| **rounded**      | round the corners                                            | `boolean`                                     | -                                                                          | `false`                    |
| **filled**       | filled variant                                               | `boolean`                                     | -                                                                          | `false`                    |
| **light**        | light variant                                                | `boolean`                                     | -                                                                          | `false`                    |
| **ghost**        | outline variant                                              | `boolean`                                     | -                                                                          | `false`                    |
| **subtle**       | subtle variant                                               | `boolean`                                     | -                                                                          | `false`                    |
| ...              | native props, passed to the group `div`                      | `HTMLAttributes`                              | `'aria-label', 'id', ...`                                                  | -                          |

<Attributes.Title>Typing and pasting</Attributes.Title>

- • **A character** fills its box and moves the focus to the next one. Typing over a filled box replaces its character.
- • **Backspace** clears the box. On an empty box, it goes back to the previous one and clears it.
- • **Paste** fills the boxes from the one that received it, and what does not fit is dropped. The first box accepts the one time code that a phone offers from a text message in the same way.
- • **Left and Right arrows** move between the boxes.
- • The code has no gaps, so a click on a box past the end goes to the first empty one.

<Attributes.Title>Ref</Attributes.Title>

The `ref` points at the group `div`.

<Attributes.Title>Accessibility</Attributes.Title>

The boxes are native text inputs in a group named by `aria-label`, and each one has its own name, like "Character 3 of 6", which you can translate with `boxLabel`. The first box has `autocomplete="one-time-code"`, so phones can offer the code from a message. `error` sets `aria-invalid` on every box.

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Popover, Grid, Spacer, Link, Text, Button } from 'core'
import { Bell } from '@bolio-ui/icons'
import { useState } from 'react'

export const meta = {
  title: 'Popover',
  description: 'The floating box popped by clicking or hovering.',
  sidebar: 'components',
  group: 'Components',
  index: 28
}

## Popover

The floating box popped by clicking or hovering.

<Playground
  desc="The basic `Popover` usage."
  scope={{ Popover, Grid, Spacer, Link }}
  code={`
() => {
  const content = () => (
    <div style={{ padding: '0 10px' }}>
      <Link href="#">A hyperlink</Link>
      <Spacer h={0.5} />
      <Link color href="#">
        External link
      </Link>
    </div>
  )
  return (
    <Grid.Container gap={2}>
      <Grid>
        <Popover content={content}>Menu</Popover>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Playground
  title="Preset Item"
  desc="Use preset `Item` component build layout."
  scope={{ Popover, Grid, Spacer, Link }}
  code={`
() => {
  const content = () => (
    <>
      <Popover.Item title>
        <span>User Settings</span>
      </Popover.Item>
      <Popover.Item>
        <Link href="#">A hyperlink</Link>
      </Popover.Item>
      <Popover.Item>
        <Link color href="#">
          A hyperlink for edit profile
        </Link>
      </Popover.Item>
      <Popover.Item line />
      <Popover.Item>
        <span>Command-Line</span>
      </Popover.Item>
    </>
  )
  return (
    <Grid.Container gap={2}>
      <Grid>
        <Popover content={content}>Menu</Popover>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Playground
  title="Close Manual"
  desc="You can control when to close the pop-up box."
  scope={{ Popover, Spacer, Grid, Link, useState }}
  code={`
() => {
  const [visible, setVisible] = useState(false)
  const changeHandler = (next) => {
    setVisible(next)
  }
  const content = () => (
    <div style={{ padding: '0 10px' }}>
      <span onClick={() => setVisible(false)}>Click to close</span>
      <Spacer h={0.5} />
      <span>Nothing</span>
    </div>
  )
  return (
    <Grid.Container gap={2}>
      <Grid>
        <Popover
          content={content}
          visible={visible}
          onVisibleChange={changeHandler}
        >
          Menu
        </Popover>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Playground
  title="Notifications"
  desc="A `Popover` can hold a small panel with a state and an action, like a list of notifications."
  scope={{ Popover, Button, Text, Bell }}
  code={`
() => {
  const [unread, setUnread] = React.useState(3)
  const content = () => (
    <div style={{ padding: '0 12px', maxWidth: 260 }}>
      <Text small b>{unread ? unread + ' unread' : 'You are all caught up'}</Text>
      <Text small type="secondary" p>Ana commented on Pricing.md</Text>
      <Text small type="secondary" p>Rui invited you to Billing</Text>
      <Text small type="secondary" p>Your export is ready</Text>
      <Button auto scale={0.6} disabled={!unread} onClick={() => setUnread(0)}>Mark all as read</Button>
    </div>
  )
  return (
    <Popover content={content}>
      <Button auto icon={<Bell />}>Notifications</Button>
    </Popover>
  )
}
`}
/>

<Attributes edit="/content/docs/components/popover.mdx">
<Attributes.Title>Popover.Props</Attributes.Title>

| Attribute                 | Description                                    | Type                          | Accepted values     | Default  |
| ------------------------- | ---------------------------------------------- | ----------------------------- | ------------------- | -------- |
| **content**               | content of pop-up                              | `ReactNode` `() => ReactNode` | -                   | -        |
| **visible**               | visible or not                                 | `boolean`                     | -                   | `false`  |
| **initialVisible**        | visible on initial                             | `boolean`                     | -                   | `false`  |
| **hideArrow**             | hide arrow icon                                | `boolean`                     | -                   | `false`  |
| **placement**             | position of the popover relative to the target | [Placement](#placement)       | -                   | `bottom` |
| **trigger**               | tooltip trigger mode                           | `'click' / 'hover'`           | -                   | `click`  |
| **enterDelay**(ms)        | delay before popover is shown                  | `number`                      | -                   | `100`    |
| **leaveDelay**(ms)        | delay before popover is hidden                 | `number`                      | -                   | `0`      |
| **offset**(px)            | distance between pop-up and target             | `number`                      | -                   | `12`     |
| **portalClassName**       | className of pop-up box                        | `string`                      | -                   | -        |
| **onVisibleChange**       | call when visibility of the popover is changed | `(visible: boolean) => void`  | -                   | -        |
| **disableItemsAutoClose** | prevent close Popover when Items clicked       | `boolean`                     | -                   | -        |
| ...                       | native props                                   | `HTMLAttributes`              | `'id', 'name', ...` | -        |

<Attributes.Title alias="Popover.Option">Popover.Item</Attributes.Title>

| Attribute            | Description                        | Type      | Accepted values | Default |
| -------------------- | ---------------------------------- | --------- | --------------- | ------- |
| **line**             | show a line                        | `boolean` | -               | `false` |
| **title**            | show text with title style         | `boolean` | -               | `false` |
| **disableAutoClose** | prevent close Popover when clicked | `boolean` | -               | `false` |

<Attributes.Title>Placement</Attributes.Title>

```ts
type Placement = 'top'
  | 'topStart',
  | 'topEnd',
  | 'left',
  | 'leftStart',
  | 'leftEnd',
  | 'bottom',
  | 'bottomStart',
  | 'bottomEnd',
  | 'right',
  | 'rightStart',
  | 'rightEnd',
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Progress, Grid, useTheme, Button, Text } from 'core'
import { useState } from 'react'

export const meta = {
  title: 'Progress',
  description: 'Display progress relative to a limit or related to a task.',
  sidebar: 'components',
  group: 'Components',
  index: 28
}

## Progress

Display progress relative to a limit or related to a task.

<Playground
  desc="The basic `Progress` usage."
  scope={{ Progress, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid xs={12} md={12}>
    <Progress value={50} />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Custom Max"
  desc="Modify the maximum value of progress."
  scope={{ Progress, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid xs={12} md={12}>
    <Progress value={45} max={50} />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Dynamic Colors"
  desc="You can specify the color of the progress in any range."
  scope={{ Progress, useState, useTheme, Button, Grid }}
  code={`
() => {
  const theme = useTheme()
  const [value, setValue] = useState(20)
  const colors = {
    20: theme.palette.error,
    40: theme.palette.warning,
    60: theme.palette.success,
    80: '#000'
  }
  return (
    <Grid.Container gap={2}>
      <Grid xs={12} md={12}>
        <Progress value={value} colors={colors} />
      </Grid>
      <Grid>
        <Button onClick={() => setValue(value + 20)} auto scale={0.5}>
          Add
        </Button>
      </Grid>
      <Grid>
        <Button onClick={() => setValue(20)} auto scale={0.5} type="error">
          Remove
        </Button>
      </Grid>
    </Grid.Container>
  )
}`}
/>

<Playground
  title="Segmented"
  desc="Split the bar in blocks with `segments`."
  scope={{ Progress, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid xs={12}>
    <Progress segments={10} value={60} type="primary" />
  </Grid>
  <Grid xs={12}>
    <Progress segments={5} value={80} type="success" scale={1.5} />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Circular"
  desc="Use `circular` for a ring. The size follows `width` and `scale`."
  scope={{ Progress, Grid }}
  code={`
<Grid.Container gap={2} alignItems="center">
  <Grid><Progress circular value={25} /></Grid>
  <Grid><Progress circular value={60} type="primary" width="4em" /></Grid>
  <Grid><Progress circular value={90} type="success" width="5em" /></Grid>
</Grid.Container>
`}
/>

<Playground
  title="Type"
  desc="We prepared some different styles in advance."
  scope={{ Progress, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid xs={12} md={12}>
    <Progress value={3} />
  </Grid>
    <Grid xs={12} md={12}>
    <Progress type="primary" value={74} />
  </Grid>
  <Grid xs={12} md={12}>
    <Progress type="secondary" value={10} />
  </Grid>
  <Grid xs={12} md={12}>
    <Progress type="success" value={45} />
  </Grid>
  <Grid xs={12} md={12}>
    <Progress type="warning" value={100} />
  </Grid>
  <Grid xs={12} md={12}>
    <Progress type="error" value={21} />
  </Grid>
  <Grid xs={12} md={12}>
    <Progress type="info" value={34} />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Upload progress"
  desc="Say what is being sent and how far it is, and change the type when it finishes."
  scope={{ Progress, Grid, Text, Button }}
  code={`
() => {
  const [value, setValue] = React.useState(0)
  const upload = () => {
    setValue(10)
    const timer = setInterval(() => {
      setValue((last) => {
        if (last >= 100) {
          clearInterval(timer)
          return 100
        }
        return last + 10
      })
    }, 300)
  }
  const label = value === 100 ? 'Upload complete' : value ? 'Uploading report.pdf, ' + value + '%' : 'report.pdf is ready to upload'
  return (
    <Grid.Container direction="column" gap={1}>
      <Grid>
        <Text small>{label}</Text>
      </Grid>
      <Grid>
        <Progress value={value} type={value === 100 ? 'success' : 'primary'} />
      </Grid>
      <Grid>
        <Button auto scale={0.75} onClick={upload} disabled={value > 0 && value < 100}>Upload</Button>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Attributes edit="/content/docs/components/progress.mdx">
<Attributes.Title>Progress.Props</Attributes.Title>

| Attribute       | Description            | Type                        | Accepted values                 | Default   |
| --------------- | ---------------------- | --------------------------- | ------------------------------- | --------- |
| **value**       | current value          | `number`                    | -                               | 0         |
| **max**         | max value              | `number`                    | -                               | 100       |
| **fixedTop**    | fix progress to top    | `boolean`                   | -                               | `false`   |
| **fixedBottom** | fix progress to bottom | `boolean`                   | -                               | `false`   |
| **segments**    | split the bar in blocks | `number`                    | -                               | -         |
| **circular**    | show a ring instead of a bar | `boolean`              | -                               | `false`   |
| **colors**      | custom colors          | `{ [key: number]: string }` | -                               | -         |
| **type**        | predefined state types | `ProgressTypes`             | [ProgressTypes](#progresstypes) | `default` |
| ...             | native props           | `ProgressHTMLAttributes`    | `'aria-busy', ...`              | -         |

<Attributes.Title>ProgressTypes</Attributes.Title>

```ts
type ProgressTypes =
  | 'default'
  | 'primary'
  | 'secondary'
  | 'success'
  | 'warning'
  | 'error'
  | 'info'
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Radio, Grid, Code, Button } from 'core'
import { useState } from 'react'

export const meta = {
  title: 'Radio',
  description: 'Provides single user input from a selection of options.',
  sidebar: 'components',
  group: 'Components',
  index: 29
}

## Radio

Provides single user input from a selection of options.

<Playground
  desc="The basic `Radio` usage."
  scope={{ Radio, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Radio checked={false}>Option 1</Radio>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Group"
  desc="A group of radio components."
  scope={{ Radio, useState, Grid }}
  code={`
() => {
  const [state, setState] = useState('1')
  const handler = (val) => {
    setState(val)
    console.log(val)
  }
  return (
    <Grid.Container gap={2}>
      <Grid>
        <Radio.Group value={state} onChange={handler}>
          <Radio value="1">Option 1</Radio>
          <Radio value="2">Option 2</Radio>
        </Radio.Group>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Playground
  title="Type"
  desc="Differentiate states by color."
  scope={{ Radio, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Radio checked={false}>Default</Radio>
  </Grid>
  <Grid>
    <Radio checked={false} type="primary">
      Primary
    </Radio>
  </Grid>
  <Grid>
    <Radio checked={false} type="secondary">
      Secondary
    </Radio>
  </Grid>
  <Grid>
    <Radio checked={false} type="success">
      Success
    </Radio>
  </Grid>
  <Grid>
    <Radio checked={false} type="warning">
      Warning
    </Radio>
  </Grid>
  <Grid>
    <Radio checked={false} type="error">
      Error
    </Radio>
  </Grid>
  <Grid>
    <Radio checked={false} type="info">
      Info
    </Radio>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Description"
  desc="`Description` can be combined with other components."
  scope={{ Radio, Code, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Radio.Group value="1" onChange={(val) => console.log(val)}>
      <Radio value="1">
        Option 1
        <Radio.Description>
          Example description for Option 1
        </Radio.Description>
      </Radio>
    </Radio.Group>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Disabled"
  desc="Disable all radios."
  scope={{ Radio, useState, Code, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Radio.Group value="1" disabled>
      <Radio value="1">Option 1</Radio>
      <Radio value="2">Option 2</Radio>
    </Radio.Group>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Row"
  desc="Horizontal arrangement."
  scope={{ Radio, Code, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Radio.Group value="1" useRow>
      <Radio value="1">
        Option 1<Radio.Desc>Description for Option1</Radio.Desc>
      </Radio>
      <Radio value="2">
        Option 2<Radio.Desc>Description for Option2</Radio.Desc>
      </Radio>
    </Radio.Group>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Pick a plan"
  desc="Describe each option under its name, and let the button repeat the choice."
  scope={{ Radio, Grid, Button }}
  code={`
() => {
  const plans = {
    free: ['Free', '$0 a month', '1 project'],
    pro: ['Pro', '$12 a month', 'Unlimited projects'],
    team: ['Team', '$36 a month', 'Up to 10 members']
  }
  const [plan, setPlan] = React.useState('pro')
  return (
    <Grid.Container direction="column" gap={2}>
      <Grid>
        <Radio.Group value={plan} onChange={setPlan}>
          {Object.entries(plans).map(([key, [name, price, hint]]) => (
            <Radio key={key} value={key}>
              {name}
              <Radio.Description>{price}. {hint}.</Radio.Description>
            </Radio>
          ))}
        </Radio.Group>
      </Grid>
      <Grid>
        <Button auto type="primary">Continue with {plans[plan][0]}</Button>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Attributes edit="/content/docs/components/radio.mdx">
<Attributes.Title>Radio.Props</Attributes.Title>

| Attribute    | Description                   | Type                                           | Accepted values           | Default   |
| ------------ | ----------------------------- | ---------------------------------------------- | ------------------------- | --------- |
| **checked**  | selected or not (in single)   | `boolean`                                      | -                         | `false`   |
| **value**    | unique ident value (in group) | `string`                                       | -                         | -         |
| **id**       | native attr                   | `string`                                       | -                         | -         |
| **disabled** | disable current radio         | `boolean`                                      | -                         | `false`   |
| **type**     | current type                  | `RadioTypes`                                   | [RadioTypes](#radiotypes) | `default` |
| **onChange** | change event                  | `(e: RadioEvent) => void`                      | -                         | -         |
| **ref**      | forwardRef                    | <Code>Ref&lt;HTMLInputElement &#124; null&gt;</Code> | -                         | -         |
| ...          | native props                  | `InputHTMLAttributes`                          | `'id', 'className', ...`  | -         |

<Attributes.Title>Radio.Group.Props</Attributes.Title>

| Attribute        | Description          | Type                      | Accepted values          | Default |
| ---------------- | -------------------- | ------------------------- | ------------------------ | ------- |
| **initialValue** | initial value        | `string`                  | -                        | -       |
| **value**        | selected child radio | `string`                  | -                        | -       |
| **useRow**       | horizontal layout    | `boolean`                 | -                        | `false` |
| **disabled**     | disable all radios   | `boolean`                 | -                        | `false` |
| **onChange**     | change event         | `(value: string) => void` | -                        | -       |
| ...              | native props         | `HTMLAttributes`          | `'id', 'className', ...` | -       |

<Attributes.Title alias="Radio.Desc">Radio.Description.Props</Attributes.Title>

| Attribute | Description  | Type             | Accepted values          | Default |
| --------- | ------------ | ---------------- | ------------------------ | ------- |
| ...       | native props | `HTMLAttributes` | `'id', 'className', ...` | -       |

<Attributes.Title>RadioTypes</Attributes.Title>

```ts
type RadioTypes =
  | 'default'
  | 'primary'
  | 'secondary'
  | 'success'
  | 'warning'
  | 'error'
  | 'info'
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Rating, Grid } from 'core'
import { useState } from 'react'
import { Umbrella, Zap } from '@bolio-ui/icons'

export const meta = {
  title: 'Rating',
  description: 'Pick or show a score with stars or any other icon.',
  sidebar: 'components',
  group: 'Components',
  index: 30
}

## Rating

Pick or show a score with stars or any other icon. The value only changes when the user clicks or uses the arrow keys, and hovering shows a preview.

<Playground
  title="Default"
  desc="Control it with `value` and `onChange`, or start it with `initialValue`."
  scope={{ Rating, Grid, useState }}
  code={`
() => {
  const [value, setValue] = useState(3)
  return (
    <Grid.Container gap={2}>
      <Grid>
        <Rating value={value} onChange={setValue} />
      </Grid>
      <Grid>Selection: {value}</Grid>
    </Grid.Container>
  )
}
`}
/>

<Playground
  title="Types"
  desc="Pass the property `type` to change the color."
  scope={{ Rating, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Rating type="default" initialValue={3} />
  </Grid>
  <Grid>
    <Rating type="primary" initialValue={3} />
  </Grid>
  <Grid>
    <Rating type="secondary" initialValue={3} />
  </Grid>
  <Grid>
    <Rating type="success" initialValue={3} />
  </Grid>
  <Grid>
    <Rating type="warning" initialValue={3} />
  </Grid>
  <Grid>
    <Rating type="error" initialValue={3} />
  </Grid>
  <Grid>
    <Rating type="info" initialValue={3} />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Variants"
  desc="`outline` shows only the border of the empty icons, `filled` fills them with a soft color."
  scope={{ Rating, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Rating variant="outline" initialValue={3} />
  </Grid>
  <Grid>
    <Rating variant="filled" initialValue={3} />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Precision"
  desc="With `precision={0.5}` each icon can be picked by its half."
  scope={{ Rating, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Rating precision={0.5} initialValue={2.5} />
  </Grid>
  <Grid>
    <Rating precision={0.5} readOnly value={3.5} />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="States"
  desc="`readOnly` shows a score without picking, `disabled` blocks it, and `clearable` lets a second click on the same value clear it."
  scope={{ Rating, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Rating readOnly value={4} />
  </Grid>
  <Grid>
    <Rating disabled value={4} />
  </Grid>
  <Grid>
    <Rating clearable initialValue={2} />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Custom Amount"
  desc="Customize the amount of icons with `count`."
  scope={{ Rating, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Rating count={3} initialValue={2} />
  </Grid>
  <Grid>
    <Rating count={10} initialValue={7} />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Icon"
  desc="Use `icon` for the filled state and `emptyIcon` for the empty one. With `highlightSelectedOnly` only the picked icon is lit, good for faces or emojis."
  scope={{ Rating, Umbrella, Zap, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Rating initialValue={4} type="success" icon={<Umbrella />} />
  </Grid>
  <Grid>
    <Rating initialValue={3} type="error" icon={<Zap />} highlightSelectedOnly />
  </Grid>
</Grid.Container>
`}
/>

<Attributes edit="/content/docs/components/rating.mdx">
<Attributes.Title>Rating.Props</Attributes.Title>

| Attribute                 | Description                                         | Type                                       | Accepted values             | Default   |
| ------------------------- | --------------------------------------------------- | ------------------------------------------ | --------------------------- | --------- |
| **value**                 | current score, to control the component             | `number`                                   | `0` to `count`              | -         |
| **initialValue**          | score at the start                                  | `number`                                   | `0` to `count`              | `0`       |
| **onChange**              | called with the score the user picked               | `(value: number) => void`                  | -                           | -         |
| **onHoverChange**         | called with the previewed score, or `null` on leave | `(value: number \| null) => void`          | -                           | -         |
| **count**                 | amount of icons                                     | `number`                                   | -                           | `5`       |
| **precision**             | step of the score                                   | `RatingPrecision`                          | `1`, `0.5`                  | `1`       |
| **type**                  | color of the icons                                  | `RatingTypes`                              | [RatingTypes](#ratingtypes) | `default` |
| **variant**               | look of the empty icons                             | `RatingVariants`                           | `'outline', 'filled'`       | `outline` |
| **icon**                  | icon of the filled state                            | `React.ReactNode`                          | -                           | star      |
| **emptyIcon**             | icon of the empty state                             | `React.ReactNode`                          | -                           | `icon`    |
| **readOnly**              | show the score without picking                      | `boolean`                                  | -                           | `false`   |
| **disabled**              | block the component                                 | `boolean`                                  | -                           | `false`   |
| **clearable**             | a click on the current score clears it              | `boolean`                                  | -                           | `false`   |
| **highlightSelectedOnly** | light only the icon of the score                    | `boolean`                                  | -                           | `false`   |
| **getLabel**              | accessible name of each score                       | `(value: number, count: number) => string` | -                           | `3 of 5`  |
| ...                       | native props                                        | `HTMLAttributes`                           | -                           | -         |

<Attributes.Title>RatingTypes</Attributes.Title>

```ts
type RatingTypes =
  'default' | 'primary' | 'secondary' | 'success' | 'warning' | 'error' | 'info'
```

<Attributes.Title>Accessibility</Attributes.Title>

The component is a group of native radio buttons, so the arrow keys move the score and Tab leaves the group. Give it an `aria-label`. With `readOnly` or `disabled` it becomes an image named by `getLabel`.

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Row, Col, Card, Text } from 'core'

export const meta = {
  title: 'Row',
  description: 'A flex row that holds columns.',
  sidebar: 'components',
  group: 'Components',
  index: 46
}

## Row

A flex row that holds <a href="/docs/components/col">columns</a>. Each `Col` takes a number of twelfths of the row, so the spans in a row should add up to 12 or less.

<Playground
  desc="Three columns of the same size."
  scope={{ Row, Col, Card, Text }}
  code={`
<Row>
  <Col span={4}><Card><Text small>span 4</Text></Card></Col>
  <Col span={4}><Card><Text small>span 4</Text></Card></Col>
  <Col span={4}><Card><Text small>span 4</Text></Card></Col>
</Row>
`}
/>

<Playground
  title="Justify"
  desc="`justify` places the columns when they do not fill the row."
  scope={{ Row, Col, Card, Text }}
  code={`
<Row justify="space-between">
  <Col span={3}><Card><Text small>span 3</Text></Card></Col>
  <Col span={3}><Card><Text small>span 3</Text></Card></Col>
</Row>
`}
/>

<Playground
  title="Align"
  desc="`align` sets where the columns sit when the row is taller than them."
  scope={{ Row, Col, Card, Text }}
  code={`
<Row align="middle" style={{ height: 120 }}>
  <Col span={6}><Card><Text small>short</Text></Card></Col>
  <Col span={6}><Card><Text small>a taller<br />cell</Text></Card></Col>
</Row>
`}
/>

<Playground
  title="Gap"
  desc="`gap` adds space around the content of the columns."
  scope={{ Row, Col, Card, Text }}
  code={`
<Row gap={2}>
  <Col span={6}><Card><Text small>gap 2</Text></Card></Col>
  <Col span={6}><Card><Text small>gap 2</Text></Card></Col>
</Row>
`}
/>

<Attributes edit="/content/docs/components/row.mdx">
<Attributes.Title>Row.Props</Attributes.Title>

| Attribute     | Description                                              | Type                          | Accepted values                                            | Default |
| ------------- | -------------------------------------------------------- | ----------------------------- | ---------------------------------------------------------- | ------- |
| **justify**   | horizontal alignment of the columns                      | `string`                      | `start`, `end`, `center`, `space-around`, `space-between`  | `start` |
| **align**     | vertical alignment of the columns                        | `string`                      | `top`, `middle`, `bottom`                                  | `top`   |
| **gap**       | space around the content of the columns, in theme gaps   | `number`                      | -                                                          | `0`     |
| **component** | the element to render                                    | `keyof JSX.IntrinsicElements` | `'div', 'ul', 'section', ...`                              | `div`   |
| ...           | native props                                             | `HTMLAttributes`              | `'id', 'className', ...`                                   | -       |

The row does not wrap. If the spans add up to more than 12, the columns get narrower instead of going to the next line. Use a new `Row` for the next line, or use `Grid`, which wraps.

<Attributes.Title>Ref</Attributes.Title>

The `ref` points at the root element.

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Section, Container, Text, Button, useTheme } from 'core'

export const meta = {
  title: 'Section',
  description: 'A band of the page, with an optional background.',
  sidebar: 'components',
  group: 'Components',
  index: 48
}

## Section

A band of the page that groups related content, with an optional background. It renders a `section` element. Put a `Container` inside it to limit the width of the content.

<Playground
  desc="Without a background, a Section is transparent."
  scope={{ Section, Container, Text }}
  code={`
<Section>
  <Text>A section of the page.</Text>
</Section>
`}
/>

<Playground
  title="Background"
  desc="Use `bg` to paint the whole band, and a Container to keep the content narrow."
  scope={{ Section, Container, Text, useTheme }}
  code={`
() => {
  const theme = useTheme()
  return (
    <Section bg={theme.palette.accents_1} style={{ padding: 24 }}>
      <Container>
        <Text>A band with a background.</Text>
      </Container>
    </Section>
  )
}
`}
/>

<Playground
  title="Landing page bands"
  desc="Stack Sections to split a page into bands. Alternate the background to mark where one ends."
  scope={{ Section, Container, Text, Button, useTheme }}
  code={`
() => {
  const theme = useTheme()
  return (
    <>
      <Section style={{ padding: '32px 0' }}>
        <Container>
          <Text h3>Everything you need to ship</Text>
          <Text p type="secondary">Forms, tables and dialogs that work with your theme from the first line.</Text>
        </Container>
      </Section>
      <Section bg={theme.palette.accents_1} style={{ padding: '32px 0' }}>
        <Container>
          <Text h3>Start with the free plan</Text>
          <Text p type="secondary">No card needed. Upgrade when your team grows.</Text>
          <Button auto type="primary">Start for free</Button>
        </Container>
      </Section>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/components/section.mdx">
<Attributes.Title>Section.Props</Attributes.Title>

| Attribute | Description                    | Type             | Accepted values          | Default       |
| --------- | ------------------------------ | ---------------- | ------------------------ | ------------- |
| **bg**    | background color               | `string`         | any CSS color            | `transparent` |
| ...       | native props                   | `HTMLAttributes` | `'id', 'className', ...` | -             |

<Attributes.Title>Ref</Attributes.Title>

The `ref` points at the `section` element.

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { SegmentedControl, Grid, Text } from 'core'

export const meta = {
  title: 'Segmented Control',
  description:
    'A row of options where exactly one is selected, for switching a view or a setting in place.',
  sidebar: 'components',
  group: 'Components',
  index: 58
}

## Segmented Control

A row of options where exactly one is selected. Use it to switch a view or a
setting in place, like a period or a layout.

<Playground
  desc="Give each item a `value`, start on one with `initialValue` and name the group with `aria-label`."
  scope={{ SegmentedControl }}
  code={`
<SegmentedControl initialValue="week" aria-label="Period">
  <SegmentedControl.Item value="day">Day</SegmentedControl.Item>
  <SegmentedControl.Item value="week">Week</SegmentedControl.Item>
  <SegmentedControl.Item value="month">Month</SegmentedControl.Item>
</SegmentedControl>
`}
/>

<Playground
  title="Controlled"
  desc="Pass `value` and `onChange` to keep the selection in your own state."
  scope={{ SegmentedControl, Grid, Text }}
  code={`
() => {
  const [view, setView] = React.useState('list')
  return (
    <Grid.Container gap={2} direction="column">
      <Grid>
        <SegmentedControl value={view} onChange={setView} aria-label="View">
          <SegmentedControl.Item value="list">List</SegmentedControl.Item>
          <SegmentedControl.Item value="grid">Grid</SegmentedControl.Item>
          <SegmentedControl.Item value="board">Board</SegmentedControl.Item>
        </SegmentedControl>
      </Grid>
      <Grid>
        <Text p>Showing the {view} view.</Text>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Playground
  title="Full width"
  desc="With `fullWidth`, the group fills its container and the items share the space."
  scope={{ SegmentedControl }}
  code={`
<SegmentedControl fullWidth initialValue="yearly" aria-label="Billing">
  <SegmentedControl.Item value="monthly">Monthly</SegmentedControl.Item>
  <SegmentedControl.Item value="yearly">Yearly</SegmentedControl.Item>
</SegmentedControl>
`}
/>

<Playground
  title="Disabled"
  desc="Disable one item, or the whole group."
  scope={{ SegmentedControl, Grid }}
  code={`
<Grid.Container gap={2} direction="column">
  <Grid>
    <SegmentedControl initialValue="list" aria-label="View">
      <SegmentedControl.Item value="list">List</SegmentedControl.Item>
      <SegmentedControl.Item value="grid">Grid</SegmentedControl.Item>
      <SegmentedControl.Item value="board" disabled>Board</SegmentedControl.Item>
    </SegmentedControl>
  </Grid>
  <Grid>
    <SegmentedControl disabled initialValue="list" aria-label="View">
      <SegmentedControl.Item value="list">List</SegmentedControl.Item>
      <SegmentedControl.Item value="grid">Grid</SegmentedControl.Item>
    </SegmentedControl>
  </Grid>
</Grid.Container>
`}
/>

<Attributes edit="/content/docs/components/segmented-control.mdx">
<Attributes.Title>SegmentedControl.Props</Attributes.Title>

| Attribute        | Description                                  | Type                                | Accepted values           | Default |
| ---------------- | -------------------------------------------- | ----------------------------------- | ------------------------- | ------- |
| **value**        | selected item, to control it                 | `string` &#124; `number`            | -                         | -       |
| **initialValue** | item selected on the first render            | `string` &#124; `number`            | -                         | -       |
| **onChange**     | called with the `value` of the chosen item   | `(value: string \| number) => void` | -                         | -       |
| **disabled**     | disables every item                          | `boolean`                           | -                         | `false` |
| **fullWidth**    | fills the width of the container             | `boolean`                           | -                         | `false` |
| ...              | native props, passed to the `div`            | `HTMLAttributes`                    | `'aria-label', 'id', ...` | -       |

<Attributes.Title>SegmentedControl.Item.Props</Attributes.Title>

| Attribute    | Description                                  | Type                     | Accepted values | Default |
| ------------ | -------------------------------------------- | ------------------------ | --------------- | ------- |
| **value**    | identifies the item in `value` and `onChange` | `string` &#124; `number` | -               | -       |
| **disabled** | the item cannot be chosen                    | `boolean`                | -               | `false` |
| ...          | native props, passed to the radio `input`    | `InputHTMLAttributes`    | `'id', ...`     | -       |

<Attributes.Title>Ref</Attributes.Title>

The `ref` of `SegmentedControl` points at the `div`, and the `ref` of each item at its radio `input`.

<Attributes.Title>Accessibility</Attributes.Title>

The group is a `radiogroup` and each item is a native radio, so a screen reader announces the name of the group, the option and its position. Name the group with `aria-label`. Tab moves focus into the group on the selected item, and the arrow keys move between the items and select the one in focus. The selected item is not shown by color alone: it also gets a raised background.

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Select, Grid, Code, Modal, useModal, Button, Text } from 'core'

export const meta = {
  title: 'Select',
  description: 'Display a dropdown list of items.',
  sidebar: 'components',
  group: 'Components',
  index: 31
}

## Select

Display a dropdown list of items.

The Select contain an additional Hooks, see subsection [useModal](/docs/hooks/use-modal) for details.

<Playground
  desc="Basic usage."
  scope={{ Select, Grid }}
  code={`
() => {
  const handler = (val) => console.log(val)
  return (
    <Grid.Container gap={2}>
      <Grid>
        <Select placeholder="Select one" onChange={handler}>
          <Select.Option value="1">Value 1</Select.Option>
          <Select.Option value="2">Value 2</Select.Option>
        </Select>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Playground
  title="Type"
  desc="Differentiate states by color."
  scope={{ Select, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Select placeholder="Default">
      <Select.Option value="1">Value 1</Select.Option>
      <Select.Option value="2">Value 2</Select.Option>
    </Select>
  </Grid>
  <Grid>
    <Select type="primary" initialValue="1">
      <Select.Option value="1">Value 1</Select.Option>
      <Select.Option value="2">Value 2</Select.Option>
    </Select>
  </Grid>
  <Grid>
    <Select type="secondary" initialValue="2">
      <Select.Option value="1">Value 1</Select.Option>
      <Select.Option value="2">Value 2</Select.Option>
    </Select>
  </Grid>
  <Grid>
    <Select type="success" initialValue="1">
      <Select.Option value="1">Value 1</Select.Option>
      <Select.Option value="2">Value 2</Select.Option>
    </Select>
  </Grid>
  <Grid>
    <Select type="warning" initialValue="2">
      <Select.Option value="1">Value 1</Select.Option>
      <Select.Option value="2">Value 2</Select.Option>
    </Select>
  </Grid>
  <Grid>
    <Select type="error" initialValue="1">
      <Select.Option value="1">Value 1</Select.Option>
      <Select.Option value="2">Value 2</Select.Option>
    </Select>
  </Grid>
  <Grid>
    <Select type="info" initialValue="2">
      <Select.Option value="1">Value 1</Select.Option>
      <Select.Option value="2">Value 2</Select.Option>
    </Select>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Variants"
  desc="Use `filled`, `light`, `ghost` or `subtle` with a `type` to change the surface of the field."
  scope={{ Select, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Select type="primary" filled placeholder="Primary filled"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
  <Grid>
    <Select type="secondary" filled placeholder="Secondary filled"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
  <Grid>
    <Select type="success" filled placeholder="Success filled"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
  <Grid>
    <Select type="warning" filled placeholder="Warning filled"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
  <Grid>
    <Select type="error" filled placeholder="Error filled"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
  <Grid>
    <Select type="info" filled placeholder="Info filled"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
  <Grid>
    <Select type="primary" light placeholder="Primary light"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
  <Grid>
    <Select type="secondary" light placeholder="Secondary light"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
  <Grid>
    <Select type="success" light placeholder="Success light"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
  <Grid>
    <Select type="warning" light placeholder="Warning light"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
  <Grid>
    <Select type="error" light placeholder="Error light"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
  <Grid>
    <Select type="info" light placeholder="Info light"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
  <Grid>
    <Select type="primary" ghost placeholder="Primary ghost"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
  <Grid>
    <Select type="secondary" ghost placeholder="Secondary ghost"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
  <Grid>
    <Select type="success" ghost placeholder="Success ghost"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
  <Grid>
    <Select type="warning" ghost placeholder="Warning ghost"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
  <Grid>
    <Select type="error" ghost placeholder="Error ghost"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
  <Grid>
    <Select type="info" ghost placeholder="Info ghost"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
  <Grid>
    <Select type="primary" subtle placeholder="Primary subtle"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
  <Grid>
    <Select type="secondary" subtle placeholder="Secondary subtle"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
  <Grid>
    <Select type="success" subtle placeholder="Success subtle"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
  <Grid>
    <Select type="warning" subtle placeholder="Warning subtle"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
  <Grid>
    <Select type="error" subtle placeholder="Error subtle"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
  <Grid>
    <Select type="info" subtle placeholder="Info subtle"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Variants"
  desc="Use `filled`, `light`, `ghost` or `subtle` with a `type` to change the surface of the field."
  scope={{ Select, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Select type="primary" filled placeholder="Primary filled"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
  <Grid>
    <Select type="secondary" filled placeholder="Secondary filled"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
  <Grid>
    <Select type="success" filled placeholder="Success filled"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
  <Grid>
    <Select type="warning" filled placeholder="Warning filled"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
  <Grid>
    <Select type="error" filled placeholder="Error filled"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
  <Grid>
    <Select type="info" filled placeholder="Info filled"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
  <Grid>
    <Select type="primary" light placeholder="Primary light"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
  <Grid>
    <Select type="secondary" light placeholder="Secondary light"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
  <Grid>
    <Select type="success" light placeholder="Success light"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
  <Grid>
    <Select type="warning" light placeholder="Warning light"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
  <Grid>
    <Select type="error" light placeholder="Error light"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
  <Grid>
    <Select type="info" light placeholder="Info light"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
  <Grid>
    <Select type="primary" ghost placeholder="Primary ghost"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
  <Grid>
    <Select type="secondary" ghost placeholder="Secondary ghost"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
  <Grid>
    <Select type="success" ghost placeholder="Success ghost"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
  <Grid>
    <Select type="warning" ghost placeholder="Warning ghost"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
  <Grid>
    <Select type="error" ghost placeholder="Error ghost"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
  <Grid>
    <Select type="info" ghost placeholder="Info ghost"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
  <Grid>
    <Select type="primary" subtle placeholder="Primary subtle"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
  <Grid>
    <Select type="secondary" subtle placeholder="Secondary subtle"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
  <Grid>
    <Select type="success" subtle placeholder="Success subtle"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
  <Grid>
    <Select type="warning" subtle placeholder="Warning subtle"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
  <Grid>
    <Select type="error" subtle placeholder="Error subtle"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
  <Grid>
    <Select type="info" subtle placeholder="Info subtle"><Select.Option value="1">Option 1</Select.Option><Select.Option value="2">Option 2</Select.Option></Select>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Disabled"
  desc="Disable all options."
  scope={{ Select, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Select placeholder="Select one" disabled>
      <Select.Option value="1">Value 1</Select.Option>
      <Select.Option value="2">Value 2</Select.Option>
    </Select>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Disabled Option"
  desc="disable specified options."
  scope={{ Select, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Select placeholder="Select one">
      <Select.Option value="1" disabled>
        Value 1
      </Select.Option>
      <Select.Option value="2">Value 2</Select.Option>
    </Select>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Without Icon"
  desc="Hide icon on right."
  scope={{ Select, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Select placeholder="Select one" pure>
      <Select.Option value="1">Value 1</Select.Option>
      <Select.Option value="2">Value 2</Select.Option>
    </Select>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Labels"
  desc="show data as a group."
  scope={{ Select, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Select placeholder="Technologies">
      <Select.Option label>JavaScript</Select.Option>
      <Select.Option value="react">React</Select.Option>
      <Select.Option value="angular">Angular</Select.Option>
      <Select.Option label>Ruby</Select.Option>
      <Select.Option value="rails">Rails</Select.Option>
      <Select.Option value="php">PHP</Select.Option>
    </Select>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Divider"
  desc="You can use the divider of the `Select` with the property `divider`."
  scope={{ Select, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Select placeholder="Technologies">
      <Select.Option value="react">React</Select.Option>
      <Select.Option value="angular">Angular</Select.Option>
      <Select.Option divider />
      <Select.Option value="rails">Rails</Select.Option>
      <Select.Option value="php">PHP</Select.Option>
    </Select>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Multiple"
  desc="`Select` supports multiple values to be selected."
  scope={{ Select, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Select
      placeholder="Technologies"
      multiple
      width="200px"
      initialValue={['1', '3', '4', '6']}
    >
      <Select.Option value="1">React</Select.Option>
      <Select.Option value="2">Angular</Select.Option>
      <Select.Option value="3">Vue</Select.Option>
      <Select.Option divider />
      <Select.Option value="4">Rails</Select.Option>
      <Select.Option value="5">PHP</Select.Option>
      <Select.Option divider />
      <Select.Option value="6">Express</Select.Option>
      <Select.Option value="7">Koa</Select.Option>
    </Select>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Multiple Without Clear"
  desc="`Select` supports multiple values to be selected without the clear icon."
  scope={{ Select, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Select
      placeholder="Technologies"
      multiple
      width="200px"
      clearable={false}
      initialValue={['1', '3', '4', '6']}
    >
      <Select.Option value="1">React</Select.Option>
      <Select.Option value="2">Angular</Select.Option>
      <Select.Option value="3">Vue</Select.Option>
      <Select.Option divider />
      <Select.Option value="4">Rails</Select.Option>
      <Select.Option value="5">PHP</Select.Option>
      <Select.Option divider />
      <Select.Option value="6">Express</Select.Option>
      <Select.Option value="7">Koa</Select.Option>
    </Select>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Compose"
  desc="Use with other components."
  scope={{ Select, Code, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Select placeholder="Value one" initialValue="1">
      <Select.Option value="1">
        <Code>TypeScript</Code>
      </Select.Option>
      <Select.Option value="2">
        <Code>JavaScript</Code>
      </Select.Option>
    </Select>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Over Width"
  desc="`Option` to show more text with adaptive width."
  scope={{ Select, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Select placeholder="Choose one" value="1" width="150px">
      <Select.Option value="1">Truncate an overly long string</Select.Option>
      <Select.Option value="2">Option 2</Select.Option>
    </Select>
  </Grid>
  <Grid>
    <Select
      placeholder="Choose one"
      value="1"
      width="150px"
      disableMatchWidth
    >
      <Select.Option value="1">
        Autoscale option width when text is too long
      </Select.Option>
      <Select.Option value="2">Option 2</Select.Option>
    </Select>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Set parent element"
  desc="you can specify the container for drop-down box rendering."
  scope={{ Select, Grid, useModal, Modal, Button, Code, Grid }}
  code={`
() => {
  const { visible, setVisible, bindings } = useModal()
  return (
    <Grid.Container gap={2}>
      <Grid>
        <Button auto onClick={() => setVisible(true)}>Show more</Button>
        <Modal {...bindings}>
          <Modal.Title>Modal</Modal.Title>
          <Modal.Content id="customModalSelect">
            <Select placeholder="Choose one" initialValue="1"
              getPopupContainer={() => document.getElementById('customModalSelect')}>
              <Select.Option value="1"><Code>TypeScript</Code></Select.Option>
              <Select.Option value="2"><Code>JavaScript</Code></Select.Option>
            </Select>
            <p>Scroll through the content to see the changes.</p>
            <div style={{ height: '1000px' }}></div>
            <p>Scroll through the content to see the changes.</p>
          </Modal.Content>
          <Modal.Action passive onClick={() => setVisible(false)}>Cancel</Modal.Action>
        </Modal>
      </Grid>
    </Grid.Container>
  )
}`}
/>

<Playground
  title="Filter bar"
  desc="Keep the chosen values in state and say what they produce. A `Select` per filter reads better than one long list."
  scope={{ Select, Grid, Text }}
  code={`
() => {
  const [status, setStatus] = React.useState('open')
  const [sort, setSort] = React.useState('recent')
  return (
    <Grid.Container gap={2} alignItems="center">
      <Grid>
        <Select value={status} onChange={setStatus}>
          <Select.Option value="open">Open</Select.Option>
          <Select.Option value="closed">Closed</Select.Option>
          <Select.Option value="all">All</Select.Option>
        </Select>
      </Grid>
      <Grid>
        <Select value={sort} onChange={setSort}>
          <Select.Option value="recent">Most recent</Select.Option>
          <Select.Option value="oldest">Oldest</Select.Option>
          <Select.Option value="comments">Most comments</Select.Option>
        </Select>
      </Grid>
      <Grid>
        <Text small type="secondary">Showing {status} issues, {sort}.</Text>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Attributes edit="/content/docs/components/select.mdx">
<Attributes.Title>Select.Props</Attributes.Title>

| Attribute                   | Description                                              | Type                                                | Accepted values             | Default         |
| --------------------------- | -------------------------------------------------------- | --------------------------------------------------- | --------------------------- | --------------- |
| **value**                   | selected value                                           | `string`, `string[]`                                | -                           | -               |
| **initialValue**            | initial value                                            | `string`, `string[]`                                | -                           | -               |
| **placeholder**             | placeholder string                                       | `string`                                            | -                           | -               |
| **width**                   | css width value of select                                | `string`                                            | -                           | `initial`       |
| **type**                    | current type                                             | `SelectTypes`                                       | [SelectTypes](#selecttypes) | `default`       |
| **icon**                    | icon component                                           | `ComponentType`                                     | -                           | `SVG Component` |
| **pure**                    | remove icon component                                    | `boolean`                                           | -                           | `false`         |
| **multiple**                | support multiple selection                               | `boolean`                                           | -                           | `false`         |
| **clearable**               | add clear icon on multiple selection (ignored otherwise) | `boolean`                                           | -                           | `true`          |
| **disabled**                | disable current radio                                    | `boolean`                                           | -                           | `false`         |
| **rounded**                 | round the corners                                        | `boolean`                                           | -                           | `false`         |
| **filled**                  | filled variant                                           | `boolean`                                           | -                           | `false`         |
| **light**                   | light variant                                            | `boolean`                                           | -                           | `false`         |
| **ghost**                   | outline variant                                          | `boolean`                                           | -                           | `false`         |
| **subtle**                  | subtle variant                                           | `boolean`                                           | -                           | `false`         |
| **rounded**                 | round the corners                                        | `boolean`                                           | -                           | `false`         |
| **filled**                  | filled variant                                           | `boolean`                                           | -                           | `false`         |
| **light**                   | light variant                                            | `boolean`                                           | -                           | `false`         |
| **ghost**                   | outline variant                                          | `boolean`                                           | -                           | `false`         |
| **subtle**                  | subtle variant                                           | `boolean`                                           | -                           | `false`         |
| **onChange**                | selected value                                           | <Code>(val: string &#124; string[]) => void </Code> | -                           | -               |
| **dropdownClassName**       | className of dropdown menu                               | `string`                                            | -                           | -               |
| **dropdownStyle**           | style of dropdown menu                                   | `object`                                            | -                           | -               |
| **disableMatchWidth**       | disable Option from follow Select width                  | `boolean`                                           | -                           | `false`         |
| **getPopupContainer**       | dropdown render parent element, the default is `body`    | `() => HTMLElement`                                 | -                           | -               |
| **onDropdownVisibleChange** | dropdown change events                                   | `(visible: boolean) => void`                        | -                           | -               |
| **ref**                     | forwardRef                                               | `SelectRef`                                         | [SelectRef](#selectref)     | -               |
| ...                         | native props                                             | `HTMLAttributes`                                    | `'name', 'alt', ...`        | -               |

<Attributes.Title>Select.Option.Props</Attributes.Title>

| Attribute           | Description            | Type             | Accepted values     | Default |
| ------------------- | ---------------------- | ---------------- | ------------------- | ------- |
| **value**(required) | unique ident value     | `string`         | -                   | -       |
| **disabled**        | disable current option | `boolean`        | -                   | `false` |
| **divider**         | display a line         | `boolean`        | -                   | `false` |
| **label**           | display a group title  | `boolean`        | -                   | `false` |
| ...                 | native props           | `HTMLAttributes` | `'name', 'id', ...` | -       |

<Attributes.Title>SelectRef</Attributes.Title>

```ts
type SelectRef = {
  focus: () => void
  blur: () => void
  scrollTo?: (options?: ScrollToOptions) => void
}
```

<Attributes.Title>SelectTypes</Attributes.Title>

```ts
type SelectTypes =
  'default' | 'primary' | 'secondary' | 'success' | 'warning' | 'error' | 'info'
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Skeleton, Grid, Text, Button } from 'core'

export const meta = {
  title: 'Skeleton',
  description:
    'A placeholder in the shape of the content while it loads, so the layout does not jump.',
  sidebar: 'components',
  group: 'Components',
  index: 50
}

## Skeleton

A placeholder in the shape of the content while it loads, so the layout does
not jump when the content arrives.

<Playground
  desc="A line fills its container by default. Set the size with `width` and `height`."
  scope={{ Skeleton, Grid }}
  code={`
<Grid.Container gap={2} direction="column">
  <Grid>
    <Skeleton width="60%" />
  </Grid>
  <Grid>
    <Skeleton height="120px" />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Lines"
  desc="Use `lines` for a paragraph. The last line is shorter, like real text."
  scope={{ Skeleton }}
  code={`
<Skeleton lines={3} />
`}
/>

<Playground
  title="Circle"
  desc="Use `circle` for an avatar. It is as tall as it is wide unless `height` is set."
  scope={{ Skeleton, Grid }}
  code={`
<Grid.Container gap={2} alignItems="center">
  <Grid>
    <Skeleton circle width="48px" />
  </Grid>
  <Grid xs>
    <Skeleton lines={2} />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="With content"
  desc="Wrap the content and pass `loading`: the placeholder shows while it is `true`, and the content after."
  scope={{ Skeleton, Text, Button, Grid }}
  code={`
() => {
  const [loading, setLoading] = React.useState(true)
  return (
    <Grid.Container gap={2} direction="column">
      <Grid>
        <Skeleton lines={2} loading={loading}>
          <Text my={0}>The content shows up here once it has loaded.</Text>
        </Skeleton>
      </Grid>
      <Grid>
        <Button auto scale={0.75} onClick={() => setLoading(!loading)}>
          {loading ? 'Show content' : 'Show placeholder'}
        </Button>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Attributes edit="/content/docs/components/skeleton.mdx">
<Attributes.Title>Skeleton.Props</Attributes.Title>

| Attribute   | Description                                                   | Type               | Accepted values            | Default |
| ----------- | ------------------------------------------------------------- | ------------------ | -------------------------- | ------- |
| **width**   | width of the placeholder; a number is a multiple of the theme unit | `string` / `number` | `'60%'`, `'48px'`, ... | `100%`, `2.5em` for a circle |
| **height**  | height of each line; a number is a multiple of the theme unit | `string` / `number` | `'120px'`, ...             | `1em`, the width for a circle |
| **lines**   | number of lines; the last one is shorter                      | `number`           | -                          | `1`     |
| **circle**  | round shape, for avatars                                      | `boolean`          | -                          | `false` |
| **loading** | with children, shows the placeholder while `true`             | `boolean`          | -                          | `true`  |
| ...         | native props, passed to the root element                      | `HTMLAttributes`   | `'id', 'className', ...`   | -       |

<Attributes.Title>Ref</Attributes.Title>

The `ref` points at the root element of the placeholder. With children and `loading={false}`, the children render alone and the `ref` is not used.

<Attributes.Title>Accessibility</Attributes.Title>

The placeholder has `aria-hidden`, so screen readers skip it. When it wraps content, the wrapper has `aria-busy="true"` while loading. With `prefers-reduced-motion`, the shimmer stops and the shapes stay still.

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Slider, Grid, Text } from 'core'
import { useState } from 'react'

export const meta = {
  title: 'Slider',
  description: 'Display the current value and an inputable range.',
  sidebar: 'components',
  group: 'Components',
  index: 32
}

## Slider

Display the current value and an inputable range.

<Playground
  desc="Accept clicks or drag actions."
  scope={{ Slider, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid xs={12} md={12}>
    <Slider initialValue={40} />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Type"
  desc="Differentiate states by color."
  scope={{ Slider, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid xs={12} md={12}>
    <Slider initialValue={40} />
  </Grid>
  <Grid xs={12} md={12}>
    <Slider type="primary" initialValue={20} />
  </Grid>
  <Grid xs={12} md={12}>
    <Slider type="secondary" initialValue={70} />
  </Grid>
  <Grid xs={12} md={12}>
    <Slider type="success" initialValue={60} />
  </Grid>
  <Grid xs={12} md={12}>
    <Slider type="warning" initialValue={10} />
  </Grid>
  <Grid xs={12} md={12}>
    <Slider type="error" initialValue={80} />
  </Grid>
  <Grid xs={12} md={12}>
    <Slider type="info" initialValue={90} />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Disabled"
  desc="Do not respond to drag and click."
  scope={{ Slider, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid xs={12} md={12}>
    <Slider initialValue={50} disabled />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Step"
  desc="Different granularity."
  scope={{ Slider, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid xs={12} md={12}>
    <Slider step={10} showMarkers width="75%" />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Range"
  desc="Specifies the maximum or minimum value of the Slider."
  scope={{ Slider, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid xs={12} md={12}>
    <Slider
      step={5}
      max={50}
      min={10}
      initialValue={25}
      showMarkers
      width="75%"
    />
  </Grid>
  <Grid xs={12} md={12}>
    <Slider
      step={0.2}
      max={1}
      min={0.2}
      initialValue={0.4}
      showMarkers
      width="75%"
    />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Event"
  desc="Get event when slide."
  scope={{ Slider, Grid, useState }}
  code={`
() => {
  const [value, setValue] = useState()
  const handler = (val) => {
    console.log(val)
    setValue(val)
  }
  return (
    <Grid.Container gap={2}>
      <Grid xs={12} md={12}>
        <Slider value={value} onChange={handler} width="50%" />
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Playground
  title="Budget"
  desc="Show the chosen value as text next to the `Slider`, and set `min`, `max` and `step` to the values that make sense."
  scope={{ Slider, Grid, Text }}
  code={`
() => {
  const [budget, setBudget] = React.useState(500)
  return (
    <Grid.Container direction="column" gap={1}>
      <Grid>
        <Text my={0}>Monthly budget: <b>{'$' + budget}</b></Text>
      </Grid>
      <Grid>
        <Slider value={budget} onChange={setBudget} min={100} max={1000} step={50} hideValue />
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Attributes edit="/content/docs/components/slider.mdx">
<Attributes.Title>Slider.Props</Attributes.Title>

| Attribute        | Description                                        | Type                    | Accepted values                  | Default   |
| ---------------- | -------------------------------------------------- | ----------------------- | -------------------------------- | --------- |
| **initialValue** | initial value                                      | `number`                | -                                | 0         |
| **value**        | slider value                                       | `number`                | -                                | 0         |
| **type**         | current type                                       | `SliderTypes`           | [SliderTypes](#slidertypes)      | `default` |
| **step**         | the granularity the slider can step through values | `number`                | -                                | 1         |
| **max**          | the maximum value of slider                        | `number`                | -                                | 100       |
| **min**          | the minimum value of slider                        | `number`                | -                                | 0         |
| **disabled**     | disable slider interaction                         | `boolean`               | `false`                          |
| **showMarkers**  | show each marker                                   | `boolean`               | -                                | `false`   |
| **hideValue**    | hide slider value                                  | `boolean`               | -                                | `false`   |
| **onChange**     | called when the value of silder changes            | `(val: number) => void` | -                                | -         |
| ...              | native props                                       | `HTMLAttributes`        | `'id', 'name', 'className', ...` | -         |

<Attributes.Title>SliderTypes</Attributes.Title>

```ts
type SliderTypes =
  | 'default'
  | 'primary'
  | 'secondary'
  | 'success'
  | 'warning'
  | 'error'
  | 'info'
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Snippet, Grid, Code } from 'core'

export const meta = {
  title: 'Snippet',
  description: 'Display a snippet of copyable code for the command line.',
  sidebar: 'components',
  group: 'Components',
  index: 33
}

## Snippet

Display a snippet of copyable code for the command line.

<Playground
  desc="Basic Usage"
  scope={{ Snippet, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Snippet text="yarn add @bolio-ui/core" width="300px" />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Width"
  desc="Specify width manually."
  scope={{ Snippet, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Snippet text="yarn add @bolio-ui/core" width="100%" />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Types"
  desc="Show different states with colors."
  scope={{ Snippet, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Snippet text="yarn add @bolio-ui/core" width="300px" />
  </Grid>
  <Grid>
    <Snippet text="yarn add @bolio-ui/core" type="primary" width="300px" />
  </Grid>
  <Grid>
    <Snippet text="yarn add @bolio-ui/core" type="secondary" width="300px" />
  </Grid>
  <Grid>
    <Snippet text="yarn add @bolio-ui/core" type="success" width="300px" />
  </Grid>
  <Grid>
    <Snippet text="yarn add @bolio-ui/core" type="warning" width="300px" />
  </Grid>
  <Grid>
    <Snippet text="yarn add @bolio-ui/core" type="error" width="300px" />
  </Grid>
  <Grid>
    <Snippet text="yarn add @bolio-ui/core" type="lite" width="300px" />
  </Grid>
  <Grid>
    <Snippet text="yarn add @bolio-ui/core" type="dark" width="300px" />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Rounded"
  desc="You can completely round the corners of any type of `Snippet` with the `rounded` property."
  scope={{ Snippet, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Snippet text="yarn add @bolio-ui/core" width="300px" rounded />
  </Grid>
  <Grid>
    <Snippet
      text="yarn add @bolio-ui/core"
      type="primary"
      width="300px"
      rounded
    />
  </Grid>
  <Grid>
    <Snippet
      text="yarn add @bolio-ui/core"
      type="secondary"
      width="300px"
      rounded
    />
  </Grid>
  <Grid>
    <Snippet
      text="yarn add @bolio-ui/core"
      type="success"
      width="300px"
      rounded
    />
  </Grid>
  <Grid>
    <Snippet
      text="yarn add @bolio-ui/core"
      type="warning"
      width="300px"
      rounded
    />
  </Grid>
  <Grid>
    <Snippet
      text="yarn add @bolio-ui/core"
      type="error"
      width="300px"
      rounded
    />
  </Grid>
  <Grid>
    <Snippet
      text="yarn add @bolio-ui/core"
      type="lite"
      width="300px"
      rounded
    />
  </Grid>
  <Grid>
    <Snippet
      text="yarn add @bolio-ui/core"
      type="dark"
      width="300px"
      rounded
    />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Multi Line"
  desc="You can use multi line of the `Snippet` with the array in `text` prop."
  scope={{ Snippet, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Snippet text={['cd project', 'now']} width="300px" />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Without Copy"
  desc="Hide icon for copy. (disable copy)"
  scope={{ Snippet, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Snippet copy="prevent" text="yarn add @bolio-ui/core" width="300px" />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Custom Symbol"
  desc="You can custom symbol of the `Snippet` with the property `symbol`."
  scope={{ Snippet, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Snippet symbol=">" text="yarn add @bolio-ui/core" width="300px" />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Custom Toast"
  desc="You can custom toast of the `Snippet` with the property `toastText` and `toastType`."
  scope={{ Snippet, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Snippet
      toastText="Code copied!"
      toastType="secondary"
      text="yarn add @bolio-ui/core"
      width="300px"
    />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Filled"
  desc="Show different states filled with colors."
  scope={{ Snippet, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Snippet
      text="yarn add @bolio-ui/core"
      type="primary"
      filled
      width="300px"
    />
  </Grid>
  <Grid>
    <Snippet
      text="yarn add @bolio-ui/core"
      type="secondary"
      filled
      width="300px"
    />
  </Grid>
  <Grid>
    <Snippet
      text="yarn add @bolio-ui/core"
      type="success"
      filled
      width="300px"
    />
  </Grid>
  <Grid>
    <Snippet
      text="yarn add @bolio-ui/core"
      type="warning"
      filled
      width="300px"
    />
  </Grid>
  <Grid>
    <Snippet
      text="yarn add @bolio-ui/core"
      type="error"
      filled
      width="300px"
    />
  </Grid>
  <Grid>
    <Snippet
      text="yarn add @bolio-ui/core"
      type="info"
      filled
      width="300px"
    />
  </Grid>
</Grid.Container>
`}
/>

<Attributes edit="/content/docs/components/snippet.mdx">
<Attributes.Title>Snippet.Props</Attributes.Title>

| Attribute     | Description             | Type                | Accepted values                  | Default                |
| ------------- | ----------------------- | ------------------- | -------------------------------- | ---------------------- |
| **text**      | code snippet            | `string` `string[]` | -                                | -                      |
| **type**      | snippet types           | `SnippetTypes`      | [SnippetTypes](#snippettypes)    | `default`              |
| **filled**    | filled variant          | `boolean`           | -                                | `false`                |
| **light**     | light variant           | `boolean`           | -                                | `false`                |
| **ghost**     | outline variant         | `boolean`           | -                                | `false`                |
| **subtle**    | subtle variant          | `boolean`           | -                                | `false`                |
| **width**     | set CSS string          | `string`            | -                                | `initial`              |
| **copy**      | function of copy button | `CopyTypes`         | [CopyTypes](#copytypes)          | `default`              |
| **symbol**    | symbol snippet          | `string`            | -                                | `$`                    |
| **toastText** | toast text              | `string`            | -                                | `Copied to clipboard!` |
| **toastType** | toast type              | `ToastTypes`        | [ToastTypes](#toasttypes)        | `success`              |
| ...           | native props            | `HTMLAttributes`    | `'id', 'name', 'className', ...` | -                      |

<Attributes.Title>SnippetTypes</Attributes.Title>

```ts
type SnippetTypes =
  | 'default'
  | 'primary'
  | 'secondary'
  | 'success'
  | 'warning'
  | 'error'
  | 'info'
```

<Attributes.Title>CopyTypes</Attributes.Title>

```ts
type CopyTypes = 'default' | 'silent' | 'prevent'
```

<Attributes.Title>ToastTypes</Attributes.Title>

```ts
type ToastTypes =
  | 'default'
  | 'primary'
  | 'secondary'
  | 'success'
  | 'warning'
  | 'error'
  | 'info'
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Spacer, Grid, Input, Button, useTheme } from 'core'

export const meta = {
  title: 'Spacer',
  description: 'Provide empty space.',
  sidebar: 'components',
  group: 'Components',
  index: 34
}

## Spacer

Provide empty space.

<Playground
  title="Vertical"
  desc="The basic `Spacer` vertical usage."
  scope={{ Spacer, Grid, useTheme }}
  code={`
() => {
  const theme = useTheme()
  const block = (color) => ({ background: color, borderRadius: theme.layout.radius })
  return (
    <Grid.Container>
      <Grid xs={12} style={block(theme.palette.accents_2)}>
        <Spacer h={3} />
      </Grid>
      <Spacer h={2} />
      <Grid xs={12} style={block(theme.palette.accents_3)}>
        <Spacer h={3} />
      </Grid>
      <Spacer h={2} />
      <Grid xs={12} style={block(theme.palette.accents_4)}>
        <Spacer h={3} />
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Playground
  title="Horizontal"
  desc="The basic `Spacer` horizontal usage."
  scope={{ Spacer, Grid, useTheme }}
  code={`
() => {
  const theme = useTheme()
  const block = { background: theme.palette.accents_3, borderRadius: theme.layout.radius }
  return (
    <Grid.Container>
      <Grid xs={5} style={block} />
      <Spacer w={2} />
      <Grid xs={5} style={block} />
    </Grid.Container>
  )
}
`}
/>

<Playground
  title="Spacing a form"
  desc="Use a smaller Spacer between related fields and a larger one before the action."
  scope={{ Spacer, Input, Button }}
  code={`
<div style={{ maxWidth: 320 }}>
  <Input floating width="100%">Email</Input>
  <Spacer h={1} />
  <Input.Password floating width="100%">Password</Input.Password>
  <Spacer h={1.5} />
  <Button type="primary" width="100%">Sign in</Button>
</div>
`}
/>

<Attributes edit="/content/docs/components/spacer.mdx">
<Attributes.Title>Spacer.Props</Attributes.Title>

| Attribute  | Description    | Type               | Accepted values          | Default |
| ---------- | -------------- | ------------------ | ------------------------ | ------- |
| **w**      | x-axis spacing | `number` / `float` | -                        | 1       |
| **h**      | y-axis spacing | `number` / `float` | -                        | 1       |
| **inline** | inline space   | `boolean`          | -                        | `false` |
| ...        | native props   | `HTMLAttributes`   | `'id', 'className', ...` | -       |

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Spinner, Grid, Card, Button, Text } from 'core'

export const meta = {
  title: 'Spinner',
  description: 'Indicate an action running in the background.',
  sidebar: 'components',
  group: 'Components',
  index: 35
}

## Spinner

Indicate an action running in the background.

As an indicator of load waiting, see also component [Loading](/docs/components/loading).

<Playground
  desc="The basic `Spinner` usage."
  scope={{ Spinner, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Spinner scale={2} />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Loading a panel"
  desc="Show the `Spinner` where the content will appear, and swap it for the content when it arrives."
  scope={{ Spinner, Card, Button, Text, Grid }}
  code={`
() => {
  const [loading, setLoading] = React.useState(false)
  const refresh = () => {
    setLoading(true)
    setTimeout(() => setLoading(false), 1500)
  }
  return (
    <Card bordered width="100%">
      <Grid.Container justify="space-between" alignItems="center">
        <Grid>
          <Text b>Recent invoices</Text>
        </Grid>
        <Grid>
          <Button auto scale={0.75} disabled={loading} onClick={refresh}>
            Refresh
          </Button>
        </Grid>
      </Grid.Container>
      <div style={{ minHeight: 96, display: 'flex', alignItems: 'center', justifyContent: 'center' }}>
        {loading ? <Spinner scale={1.5} /> : <Text p>3 invoices are waiting for payment.</Text>}
      </div>
    </Card>
  )
}
`}
/>

<Playground
  title="Inline with text"
  desc="A small `Spinner` next to a short message tells what is running."
  scope={{ Spinner, Text, Grid }}
  code={`
<Grid.Container gap={1} alignItems="center">
  <Grid>
    <Spinner scale={0.8} />
  </Grid>
  <Grid>
    <Text small type="secondary">Saving your changes</Text>
  </Grid>
</Grid.Container>
`}
/>

<Attributes edit="/content/docs/components/spinner.mdx">
<Attributes.Title>Spinner.Props</Attributes.Title>

| Attribute | Description  | Type             | Accepted values          | Default |
| --------- | ------------ | ---------------- | ------------------------ | ------- |
| ...       | native props | `HTMLAttributes` | `'id', 'className', ...` | -       |

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Splitter, Text, useTheme } from 'core'

export const meta = {
  title: 'Splitter',
  description:
    'Panels that share a space, with a line between them that the user drags to resize them.',
  sidebar: 'components',
  group: 'Components',
  index: 68
}

## Splitter

Panels that share a space, with a line between them that the user drags, or moves
with the arrow keys, to give more room to one of them. The Splitter fills its
container, so the container needs a height.

<Playground
  desc="Put `Splitter.Panel` elements inside. `defaultSize` is a percent of the space the panels share, and the panels without one split the rest."
  scope={{ Splitter, Text, useTheme }}
  code={`
() => {
  const theme = useTheme()
  return (
    <div style={{ height: 200, border: '1px solid ' + theme.palette.border, borderRadius: theme.layout.radius }}>
      <Splitter>
        <Splitter.Panel defaultSize={30} style={{ padding: 12 }}>
          <Text b>Sidebar</Text>
        </Splitter.Panel>
        <Splitter.Panel style={{ padding: 12 }}>
          <Text b>Content</Text>
        </Splitter.Panel>
      </Splitter>
    </div>
  )
}
`}
/>

<Playground
  title="Vertical"
  desc="Set `direction` to `vertical` to stack the panels, like an editor above a console."
  scope={{ Splitter, Text, useTheme }}
  code={`
() => {
  const theme = useTheme()
  return (
    <div style={{ height: 240, border: '1px solid ' + theme.palette.border, borderRadius: theme.layout.radius }}>
      <Splitter direction="vertical">
        <Splitter.Panel style={{ padding: 12 }}>
          <Text b>Editor</Text>
        </Splitter.Panel>
        <Splitter.Panel defaultSize={35} minSize={15} style={{ padding: 12 }}>
          <Text b>Console</Text>
        </Splitter.Panel>
      </Splitter>
    </div>
  )
}
`}
/>

<Playground
  title="Limits and three panels"
  desc="`minSize` and `maxSize` keep a panel from being squeezed or stretched too far. A line only moves the two panels next to it. `onResize` receives the size of every panel, to save the layout."
  scope={{ Splitter, Text, useTheme }}
  code={`
() => {
  const theme = useTheme()
  const [sizes, setSizes] = React.useState([20, 55, 25])
  return (
    <div>
      <div style={{ height: 200, border: '1px solid ' + theme.palette.border, borderRadius: theme.layout.radius }}>
        <Splitter onResize={setSizes}>
          <Splitter.Panel defaultSize={20} minSize={10} maxSize={35} style={{ padding: 12 }}>
            <Text small>Files</Text>
          </Splitter.Panel>
          <Splitter.Panel defaultSize={55} minSize={30} style={{ padding: 12 }}>
            <Text small>Editor</Text>
          </Splitter.Panel>
          <Splitter.Panel defaultSize={25} minSize={10} style={{ padding: 12 }}>
            <Text small>Outline</Text>
          </Splitter.Panel>
        </Splitter>
      </div>
      <Text small type="secondary">{sizes.map((size) => Math.round(size) + '%').join(' / ')}</Text>
    </div>
  )
}
`}
/>

<Attributes edit="/content/docs/components/splitter.mdx">
<Attributes.Title>Splitter.Props</Attributes.Title>

| Attribute        | Description                                                             | Type                           | Accepted values           | Default      |
| ---------------- | ----------------------------------------------------------------------- | ------------------------------ | ------------------------- | ------------ |
| **direction**    | `horizontal` puts the panels side by side, `vertical` stacks them       | `string`                       | `'horizontal', 'vertical'` | `horizontal` |
| **onResize**     | called with the size of every panel, in percent, when one of them changes | `(sizes: number[]) => void`  | -                         | -            |
| **handleLabel**  | name of the lines, for screen readers                                   | `string`                       | -                         | `Resize`     |
| ...              | native props, passed to the root `div`                                  | `HTMLAttributes`               | `'id', 'style', ...`      | -            |

<Attributes.Title>Splitter.Panel.Props</Attributes.Title>

| Attribute       | Description                                                                          | Type     | Accepted values | Default |
| --------------- | ------------------------------------------------------------------------------------ | -------- | --------------- | ------- |
| **defaultSize** | percent of the space the panels share; the panels without one split what is left     | `number` | `0` to `100`    | -       |
| **minSize**     | smallest size the panel can have, in percent                                         | `number` | `0` to `100`    | `0`     |
| **maxSize**     | largest size the panel can have, in percent                                          | `number` | `0` to `100`    | `100`   |
| ...             | native props, passed to the panel `div`                                              | `HTMLAttributes` | `'className', 'style', ...` | - |

<Attributes.Title>Behavior</Attributes.Title>

- • **Sizes** are percents of the space the panels share, without the lines, so the panels stay in proportion when the container is resized.
- • **A line** moves the panel before it and the one after it, by the same amount, as far as the limits of both allow.
- • **Overflow**: each panel scrolls its own content.
- • **Panels that come or go** start the sizes again from the `defaultSize` values.

<Attributes.Title>Ref</Attributes.Title>

The `ref` of `Splitter` points at the root `div`, and the `ref` of a panel at its `div`.

<Attributes.Title>Accessibility</Attributes.Title>

Each line is a `separator` that can be focused, with `aria-valuenow`, `aria-valuemin` and `aria-valuemax` for the size of the panel before it, and `aria-controls` pointing at that panel. The arrow keys that go along the splitter move it by 1%, or by 10% with Shift: Left and Right when the panels are side by side, Up and Down when they are stacked. Home and End go to the smallest and the largest size the limits allow. Name the lines with `handleLabel`.

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Stat, Grid, Card, Progress, SegmentedControl } from 'core'

export const meta = {
  title: 'Stat',
  description: 'Show a number with its label and trend.',
  sidebar: 'components',
  group: 'Components',
  index: 53
}

## Stat

Show a number with its label and trend.

<Playground
  title="General"
  desc="The basic `Stat` usage. A trend that starts with `-` is shown as a drop."
  scope={{ Stat, Grid, Card }}
  code={`
<Grid.Container gap={2}>
  <Grid xs={12} md={4}>
    <Card bordered width="100%">
      <Stat label="Revenue" value="$48,200" change="+12.4% this month" />
    </Card>
  </Grid>
  <Grid xs={12} md={4}>
    <Card bordered width="100%">
      <Stat label="Active users" value="3,842" change="+4.1% this week" />
    </Card>
  </Grid>
  <Grid xs={12} md={4}>
    <Card bordered width="100%">
      <Stat label="Churn" value="1.8%" change="-0.3% this month" />
    </Card>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="With Extra"
  desc="Use `extra` for a small chart or an icon on the right."
  scope={{ Stat, Card, Progress }}
  code={`
<Card bordered width="320px">
  <Stat
    label="Storage"
    value="72%"
    change="+6% this month"
    extra={<Progress circular value={72} type="primary" scale={1.2} />}
  />
</Card>
`}
/>

<Playground
  title="Dashboard with a period"
  desc="Pair the `Stat` cards with a `SegmentedControl` that changes the period they show."
  scope={{ Stat, Grid, Card, SegmentedControl }}
  code={`
() => {
  const periods = {
    week: [
      ['Revenue', '$11,300', '+3.2% vs last week'],
      ['Active users', '2,914', '+1.1% vs last week'],
      ['Churn', '0.4%', '-0.1% vs last week']
    ],
    month: [
      ['Revenue', '$48,200', '+12.4% vs last month'],
      ['Active users', '3,842', '+4.1% vs last month'],
      ['Churn', '1.8%', '-0.3% vs last month']
    ],
    year: [
      ['Revenue', '$512,900', '+31.0% vs last year'],
      ['Active users', '3,842', '+58.2% vs last year'],
      ['Churn', '6.2%', '-1.4% vs last year']
    ]
  }
  const [period, setPeriod] = React.useState('month')
  return (
    <Grid.Container gap={2} direction="column">
      <Grid>
        <SegmentedControl value={period} onChange={setPeriod} aria-label="Period">
          <SegmentedControl.Item value="week">Week</SegmentedControl.Item>
          <SegmentedControl.Item value="month">Month</SegmentedControl.Item>
          <SegmentedControl.Item value="year">Year</SegmentedControl.Item>
        </SegmentedControl>
      </Grid>
      <Grid>
        <Grid.Container gap={2}>
          {periods[period].map(([label, value, change]) => (
            <Grid key={label} xs={12} md={4}>
              <Card bordered width="100%">
                <Stat label={label} value={value} change={change} />
              </Card>
            </Grid>
          ))}
        </Grid.Container>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Attributes edit="/content/docs/components/stat.mdx">
<Attributes.Title>Stat.Props</Attributes.Title>

| Attribute  | Description                                | Type             | Accepted values | Default |
| ---------- | ------------------------------------------ | ---------------- | --------------- | ------- |
| **label**  | what the number measures                   | `ReactNode`      | -               | -       |
| **value**  | the number                                 | `ReactNode`      | -               | -       |
| **change** | trend text, a leading `-` is shown as drop | `string`         | -               | -       |
| **extra**  | chart or icon on the right                 | `ReactNode`      | -               | -       |
| ...        | native props                               | `HTMLAttributes` | -               | -       |


</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Stepper, Button, Grid } from 'core'

export const meta = {
  title: 'Stepper',
  description:
    'Shows the steps of a flow and which one the user is on, like a checkout or a signup.',
  sidebar: 'components',
  group: 'Components',
  index: 51
}

## Stepper

Shows the steps of a flow and which one the user is on, like a checkout or a
signup. The steps before `active` are completed.

<Playground
  desc="Pass the index of the current step in `active` and name the list with `aria-label`."
  scope={{ Stepper }}
  code={`
<Stepper active={1} aria-label="Checkout">
  <Stepper.Step label="Cart" description="Review the items" />
  <Stepper.Step label="Shipping" description="Where to deliver" />
  <Stepper.Step label="Payment" description="Card or invoice" />
</Stepper>
`}
/>

<Playground
  title="Clickable steps"
  desc="With `onStepClick`, each step is a button that receives its index. A step with `disabled` cannot be clicked."
  scope={{ Stepper, Button, Grid }}
  code={`
() => {
  const [active, setActive] = React.useState(0)
  return (
    <Grid.Container gap={2} direction="column">
      <Grid>
        <Stepper active={active} onStepClick={setActive} aria-label="Signup">
          <Stepper.Step label="Account" />
          <Stepper.Step label="Profile" />
          <Stepper.Step label="Confirm" />
        </Stepper>
      </Grid>
      <Grid>
        <Button auto scale={0.75} disabled={active === 0} onClick={() => setActive(active - 1)}>
          Back
        </Button>{' '}
        <Button auto scale={0.75} type="secondary" disabled={active === 3} onClick={() => setActive(active + 1)}>
          Next
        </Button>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Playground
  title="Error"
  desc="Mark a step that failed with `error`. It shows in red whether it is done or not."
  scope={{ Stepper }}
  code={`
<Stepper active={2} aria-label="Deploy">
  <Stepper.Step label="Build" description="2m 14s" />
  <Stepper.Step label="Test" description="3 failed" error />
  <Stepper.Step label="Release" />
</Stepper>
`}
/>

<Playground
  title="Vertical"
  desc='Use `orientation="vertical"` for narrow spaces or long descriptions.'
  scope={{ Stepper }}
  code={`
<Stepper active={1} orientation="vertical" aria-label="Onboarding">
  <Stepper.Step label="Create a project" description="Name it and pick a region" />
  <Stepper.Step label="Invite the team" description="They get an email with a link" />
  <Stepper.Step label="Deploy" description="Push to the main branch" />
</Stepper>
`}
/>

<Attributes edit="/content/docs/components/stepper.mdx">
<Attributes.Title>Stepper.Props</Attributes.Title>

| Attribute       | Description                                         | Type                      | Accepted values              | Default      |
| --------------- | --------------------------------------------------- | ------------------------- | ---------------------------- | ------------ |
| **active**      | index of the current step, from `0`                 | `number`                  | -                            | -            |
| **onStepClick** | called with the index of the clicked step; turns the steps into buttons | `(index: number) => void` | -    | -            |
| **orientation** | direction of the steps                              | `string`                  | `'horizontal', 'vertical'`   | `horizontal` |
| ...             | native props, passed to the `ol`                    | `OlHTMLAttributes`        | `'aria-label', 'id', ...`    | -            |

<Attributes.Title>Stepper.Step.Props</Attributes.Title>

| Attribute       | Description                                            | Type             | Accepted values | Default |
| --------------- | ------------------------------------------------------ | ---------------- | --------------- | ------- |
| **label**       | name of the step                                       | `ReactNode`      | -               | -       |
| **description** | text below the label                                   | `ReactNode`      | -               | -       |
| **icon**        | replaces the number, the check and the error mark      | `ReactNode`      | -               | -       |
| **error**       | the step failed                                        | `boolean`        | -               | `false` |
| **disabled**    | the step cannot be clicked, with `onStepClick`         | `boolean`        | -               | `false` |
| ...             | native props, passed to the `li`                       | `LiHTMLAttributes` | -             | -       |

<Attributes.Title>Ref</Attributes.Title>

The `ref` of `Stepper` points at the `ol`, and the `ref` of each step at its `li`.

<Attributes.Title>Accessibility</Attributes.Title>

The steps are an ordered list, so a screen reader hears how many there are and the position of each. Name the list with `aria-label`. The current step has `aria-current="step"`, and completed and failed steps say so in text, not only in color. With `onStepClick`, each step is a real button, reached with Tab.

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, PlaygroundTitle, Attributes } from 'src/components'
import { Table, Spacer, Code, Text, Button, Dot, Grid } from 'core'
import { useState } from 'react'

export const meta = {
  title: 'Table',
  description: 'Display tabular data in format.',
  sidebar: 'components',
  group: 'Components',
  index: 42
}

## Table

Display tabular data in format.

<Playground
  desc="Display formatted data in rows and columns."
  scope={{ Table }}
  code={`
() => {
  const data = [
    { property: 'type', description: 'Content type', type: 'secondary | warning', default: '-' },
    { property: 'Component', description: 'DOM element to use', type: 'string', default: '-' },
    { property: 'bold', description: 'Bold style', type: 'boolean', default: 'true' },
  ]
  return (
    <Table data={data}>
      <Table.Column prop="property" label="property" />
      <Table.Column prop="description" label="description" />
      <Table.Column prop="type" label="type" />
      <Table.Column prop="default" label="default" />
    </Table>
  )
}
`}
/>

<Playground
  title="compose"
  desc="Show other components in the table."
  scope={{ Table, Code, Text }}
  code={`
() => {
  const data = [
    { property: 'type', description: 'Content type', type: 'secondary | warning', default: '-' },
    { property: 'Component', description: 'DOM element to use', type: <Code>string</Code>, default: '-' },
    { property: <Text b>bold</Text>, description: 'Bold style', type: <Code>boolean</Code>, default: <Code>true</Code> },
  ]
  return (
    <Table data={data}>
      <Table.Column prop="property" label="property" />
      <Table.Column prop="description" label="description" />
      <Table.Column prop="type" label="type" />
      <Table.Column prop="default" label="default" />
    </Table>
  )
}
`}
/>

<Playground
  title="width"
  desc="Specifies the `width` of all or part of the columns."
  scope={{ Table, Code, Text }}
  code={`
() => {
  const data = [
    { property: 'type', description: 'Content type', type: 'secondary | warning', default: '-' },
    { property: 'Component', description: 'DOM element to use', type: <Code>string</Code>, default: '-' },
    { property: <Text b>bold</Text>, description: 'Bold style', type: <Code>boolean</Code>, default: <Code>true</Code> },
  ]
  return (
    <Table data={data}>
      <Table.Column prop="property" label="property" width={50} />
      <Table.Column prop="description" label="description" />
      <Table.Column prop="type" label="type" />
      <Table.Column prop="default" label="default" />
    </Table>
  )
}
`}
/>

<Playground
  title="actions"
  desc="Custom elements can be displayed in the table, and any changes will be immediately rendered."
  scope={{ Table, Text, Button }}
  code={`
() => {
  const dataSource = [
    { property: 'type', description: 'Content type', operation: '' },
    { property: 'Component', description: 'DOM element to use', operation: '' },
    { property: <Text b>bold</Text>, description: 'Bold style', operation: '' },
  ]
  const [data, setData] = React.useState(dataSource)
  const renderAction = (value, rowData, index) => {
    const removeHandler = () => {
      setData(last => last.filter((_, dataIndex) => dataIndex !== index))
    }
    return (
      <Button type="error" auto scale={1/3} font="12px" onClick={removeHandler}>Remove</Button>
    )
  }
  return (
  <Table data={data} onChange={value => setData(value)}>
    <Table.Column prop="property" label="property" />
    <Table.Column prop="description" label="description" />
    <Table.Column prop="operation" label="operation" width={150} render={renderAction} />
  </Table>
  )
}
`}
/>

<Playground
  title="update row"
  desc="You can use custom elements to update a specific row."
  scope={{ Table, Text, Button }}
  code={`
() => {
  const dataSource = [
    { property: 'type', description: 'Content type', operation: '' },
    { property: 'Component', description: 'DOM element to use', operation: '' },
    { property: <Text b>bold</Text>, description: 'Bold style', operation: '' },
  ]
  const [data, setData] = React.useState(dataSource)
  const renderAction = (value, rowData, rowIndex) => {
    const updateHandler = () => {
      setData(last => {
        return last.map((item, dataIndex) => {
          if (dataIndex !== rowIndex) return item
          return {
            ...item,
            property: Math.random().toString(16).slice(-5)
          }
        })
      })
    }
    return (
      <Button type="secondary" auto scale={1/3} font="12px" onClick={updateHandler}>Update</Button>
    )
  }
  return (
    <Table data={data} onChange={value => setData(value)}>
      <Table.Column prop="property" label="property" />
      <Table.Column prop="description" label="description" />
      <Table.Column prop="operation" label="operation" width={150} render={renderAction} />
    </Table>
  )
}
`}
/>

<Playground
  title="custom head"
  scope={{ Table, Code, Text }}
  code={`
() => {
  const data = [
    { property: 'type', description: 'Content type', type: 'secondary | warning', default: '-' },
    { property: 'Component', description: 'DOM element to use', type: <Code>string</Code>, default: '-' },
    { property: <Text b>bold</Text>, description: 'Bold style', type: <Code>boolean</Code>, default: <Code>true</Code> },
  ]
  return (
    <Table data={data}>
      <Table.Column prop="property" label="property" />
      <Table.Column prop="description" label="description" />
      <Table.Column prop="type">
        <Code>type</Code>
      </Table.Column>
      <Table.Column prop="default">
        <Text b>default</Text>
      </Table.Column>
    </Table>
  )
}
`}
/>

<Playground
  title="pagination"
  desc="Set `pagination` with a `pageSize` and the table slices `data` and shows a `Pagination` below it. The footer only appears when there is more than one page. `onRow` and `onCell` receive the index inside the current page."
  scope={{ Table }}
  code={`
() => {
  const data = Array.from({ length: 23 }, (_, index) => ({
    id: index + 1,
    name: 'Item ' + (index + 1),
  }))
  return (
    <Table data={data} pagination={{ pageSize: 5 }}>
      <Table.Column prop="id" label="id" />
      <Table.Column prop="name" label="name" />
    </Table>
  )
}
`}
/>

<Playground
  title="server pagination"
  desc="With `total`, `data` is already the current page: the table only shows the `Pagination`. Control `page` and load the rows in `onPageChange`."
  scope={{ Table, useState }}
  code={`
() => {
  const [page, setPage] = useState(1)
  const rows = Array.from({ length: 5 }, (_, index) => {
    const id = (page - 1) * 5 + index + 1
    return { id, name: 'Item ' + id }
  })
  return (
    <Table
      data={rows}
      pagination={{ pageSize: 5, total: 50, page, onPageChange: setPage }}
    >
      <Table.Column prop="id" label="id" />
      <Table.Column prop="name" label="name" />
    </Table>
  )
}
`}
/>

<PlaygroundTitle
  title="TypeScript Example"
  desc="Get a better experience in TS by specifying a generic type."
/>

```tsx
type User = {
  name: string
  role: string
  records: Array<{ date: string }>
}
const renderHandler: TableColumnRender<User> = (value, rowData, index) => {
  return <div>{rowData.date}</div>
}
const data: Array<User> = [
  { name: 'witt', role: 'admin', records: [{ date: '2021-05-01' }] }
]

const MyComponent = () => (
  <Table<User> data={data}>
    <Table.Column<User> prop="name" label="username" />
    <Table.Column<User> prop="role" label="role" />
    <Table.Column<User> prop="records" label="records" render={renderHandler} />
  </Table>
)
```

<Playground
  title="orders"
  desc="Use `render` to show a value as a status with a `Dot`, so the state reads before the word."
  scope={{ Table, Dot }}
  code={`
() => {
  const data = [
    { id: '#1042', customer: 'Ana Souza', status: 'paid', total: '$129.00' },
    { id: '#1043', customer: 'Rui Pires', status: 'pending', total: '$54.50' },
    { id: '#1044', customer: 'Marta Lima', status: 'refunded', total: '$89.90' }
  ]
  const types = { paid: 'success', pending: 'warning', refunded: 'error' }
  const renderStatus = (value) => <Dot type={types[value]}>{value}</Dot>
  return (
    <Table data={data}>
      <Table.Column prop="id" label="order" width={90} />
      <Table.Column prop="customer" label="customer" />
      <Table.Column prop="status" label="status" render={renderStatus} />
      <Table.Column prop="total" label="total" />
    </Table>
  )
}
`}
/>

<Playground
  title="sorting"
  desc="Add `sortable` to a column and its header becomes a button. A click sorts ascending, the next descending, and the third goes back to the order of the data. Numbers are compared by value."
  scope={{ Table }}
  code={`
() => {
  const invoices = [
    { id: 'INV-014', customer: 'Ana Souza', amount: 129, due: '2026-11-03' },
    { id: 'INV-009', customer: 'Rui Pires', amount: 1450, due: '2026-10-21' },
    { id: 'INV-021', customer: 'Marta Lima', amount: 89.9, due: '2026-12-01' },
    { id: 'INV-003', customer: 'Joao Reis', amount: 300, due: '2026-10-30' }
  ]
  const money = (value) => <span>{'$' + value.toFixed(2)}</span>
  return (
    <Table data={invoices} initialSort={{ prop: 'due', direction: 'asc' }}>
      <Table.Column prop="id" label="invoice" sortable />
      <Table.Column prop="customer" label="customer" sortable />
      <Table.Column prop="amount" label="amount" sortable render={money} />
      <Table.Column prop="due" label="due date" sortable />
    </Table>
  )
}
`}
/>

<Playground
  title="selection"
  desc="`selectable` adds a checkbox to each row and one in the header for the rows in view. Give each row a stable `rowKey`, and control `selectedKeys` to clear the selection after an action."
  scope={{ Table, Button, Text, Grid }}
  code={`
() => {
  const [rows, setRows] = React.useState([
    { id: 1, name: 'Ana Souza', role: 'Owner' },
    { id: 2, name: 'Rui Pires', role: 'Editor' },
    { id: 3, name: 'Marta Lima', role: 'Editor' },
    { id: 4, name: 'Joao Reis', role: 'Viewer' }
  ])
  const [selected, setSelected] = React.useState([])
  const remove = () => {
    setRows((last) => last.filter((row) => !selected.includes(row.id)))
    setSelected([])
  }
  return (
    <Grid.Container direction="column" gap={1}>
      <Grid>
        <Grid.Container gap={1} alignItems="center">
          <Grid>
            <Button auto type="error" scale={0.75} disabled={!selected.length} onClick={remove}>
              {selected.length ? 'Remove ' + selected.length + ' members' : 'Remove members'}
            </Button>
          </Grid>
          <Grid>
            <Text small type="secondary">{selected.length} of {rows.length} selected</Text>
          </Grid>
        </Grid.Container>
      </Grid>
      <Grid>
        <Table data={rows} selectable rowKey="id" selectedKeys={selected} onSelectionChange={setSelected}>
          <Table.Column prop="name" label="name" />
          <Table.Column prop="role" label="role" />
        </Table>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Playground
  title="data table"
  desc="Sorting, selection and pagination together. The rows are sorted before they are split in pages, and the selection is kept when you change the page."
  scope={{ Table, Text, Grid }}
  code={`
() => {
  const rows = Array.from({ length: 14 }, (_, index) => ({
    id: index + 1,
    name: 'Customer ' + (index + 1),
    orders: ((index * 7) % 11) + 1
  }))
  const [selected, setSelected] = React.useState([])
  return (
    <Grid.Container direction="column" gap={1}>
      <Grid>
        <Text small type="secondary">{selected.length} selected</Text>
      </Grid>
      <Grid>
        <Table
          data={rows}
          selectable
          rowKey="id"
          selectedKeys={selected}
          onSelectionChange={setSelected}
          pagination={{ pageSize: 5 }}
        >
          <Table.Column prop="name" label="customer" sortable />
          <Table.Column prop="orders" label="orders" sortable />
        </Table>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Attributes edit="/content/docs/components/table.mdx">
<Attributes.Title>Table.Props</Attributes.Title>

| Attribute        | Description                                  | Type                                                  | Accepted values    | Default |
| ---------------- | -------------------------------------------- | ----------------------------------------------------- | ------------------ | ------- |
| **data**         | data source                                  | `Array<T>`                                            | -                  | -       |
| **initialData**  | inital datas                                 | `Array<T>`                                            | -                  | `[]`    |
| **emptyText**    | displayed text when table's content is empty | `string`                                              | -                  | -       |
| **hover**        | table's hover effect                         | `boolean`                                             | -                  | `true`  |
| **onRow**        | callback row's content by click              | [TableOnRowClick](#tableonrowclick)                   | -                  | -       |
| **onCell**       | callback cell's content by click             | [TableOnCellClick](#tableoncellclick)                 | -                  | -       |
| **onChange**     | data change event                            | `(data: T) => void`                                   | -                  | -       |
| **pagination**   | split the rows in pages                      | [TablePagination](#tablepagination)                   | -                  | -       |
| **rowClassName** | set className to each row                    | [TableRowClassNameHandler](#tablerowclassnamehandler) | -                  | -       |
| **sort**         | the column the rows are sorted by, to control it | [TableSort](#tablesort) / `null`                  | -                  | -       |
| **initialSort**  | sort on the first render                     | [TableSort](#tablesort) / `null`                      | -                  | `null`  |
| **onSortChange** | called with the new sort, or `null` when it is cleared | `(sort: TableSort \| null) => void`        | -                  | -       |
| **selectable**   | a checkbox on each row, and one in the header | `boolean`                                            | -                  | `false` |
| **rowKey**       | what identifies a row: a prop, or a function. The position in `data` when missing | `keyof T` / `(row: T) => string \| number` | -        | -       |
| **selectedKeys** | keys of the selected rows, to control them   | `Array<string \| number>`                             | -                  | -       |
| **initialSelectedKeys** | keys of the rows selected on the first render | `Array<string \| number>`                       | -                  | `[]`    |
| **onSelectionChange** | called with the keys and the rows selected | `(keys, rows: T[]) => void`                         | -                  | -       |
| **selectRowLabel** | name of the checkbox of a row, for screen readers | `string`                                         | -                  | `Select row` |
| **selectAllLabel** | name of the checkbox in the header         | `string`                                              | -                  | `Select all rows` |
| ...              | native props                                 | `TableHTMLAttributes`                                 | `'id', 'name' ...` | -       |

<Attributes.Title>Table.Column.Props</Attributes.Title>

| Attribute          | Description                            | Type                                    | Accepted values | Default |
| ------------------ | -------------------------------------- | --------------------------------------- | --------------- | ------- |
| **prop**(required) | table-column's prop                    | `string`                                | -               | -       |
| **label**          | table-column's label                   | `string`                                | -               | -       |
| **width**          | width number (px)                      | `number`                                | -               | -       |
| **className**      | set className to each column           | `string`                                | -               | -       |
| **sortable**       | the header becomes a button that sorts the rows | `boolean`                      | -               | `false` |
| **sorter**         | how two rows compare, when the default order does not fit | `(a: T, b: T) => number` | -               | -       |
| **render**         | render returns elements in all columns | [TableColumnRender](#tablecolumnrender) | -               | -       |

<Attributes.Title>TableSort</Attributes.Title>

```ts
type TableSort = { prop: string; direction: 'asc' | 'desc' }
```

<Attributes.Title>Sorting and selection</Attributes.Title>

- • **Order**: numbers are compared by value, and any other value as text, where `item 2` comes before `item 10`. Use `sorter` on a column for anything else. The header has `aria-sort`, and the sorted column shows an arrow.
- • **Server rows**: with `pagination.total`, the rows are the ones of the server, so the table does not sort them. It only calls `onSortChange`, and you send the new order with the data.
- • **Selection keys**: the selection is kept by key, so it survives a sort and a change of page. `onSelectionChange` receives the rows that are in `data`, which are only the current page when the rows are on the server.
- • **Select all**: the checkbox in the header selects the rows in view, the current page. It is checked when all of them are selected, and in between when only some are.

<Attributes.Title>TablePagination</Attributes.Title>

| Attribute        | Description                                    | Type                     | Accepted values | Default |
| ---------------- | ---------------------------------------------- | ------------------------ | --------------- | ------- |
| **pageSize**     | rows in each page                              | `number`                 | -               | -       |
| **page**         | current page, to control it                    | `number`                 | -               | `1`     |
| **onPageChange** | called with the page the user picked           | `(page: number) => void` | -               | -       |
| **total**        | all the rows on the server, `data` is the page | `number`                 | -               | -       |

<Attributes.Title>TableOnRowClick</Attributes.Title>

```ts
type TableOnRowClick<T> = (rowData: T, rowIndex: number) => void
```

<Attributes.Title>TableOnCellClick</Attributes.Title>

```ts
type TableOnCellClick<T> = (
  value: T[keyof T],
  rowIndex: number,
  colunmIndex: number
) => void
```

<Attributes.Title>TableRowClassNameHandler</Attributes.Title>

```ts
type TableRowClassNameHandler<T> = (rowData: T, rowIndex: number) => string
```

<Attributes.Title>TableColumnRender</Attributes.Title>

```ts
type TableColumnRender<T extends Record> = (
  value: T[keyof T],
  rowData: T,
  rowIndex: number
) => JSX.Element | void
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Tabs, Grid, Text, Button, Code, useTabs, Input, Spacer } from 'core'
import { useState } from 'react'
import { Instagram, Facebook } from '@bolio-ui/icons'

export const meta = {
  title: 'Tabs',
  description: 'Display tab content.',
  sidebar: 'components',
  group: 'Components',
  index: 36
}

## Tabs

Display tab content.

The Tabs contain an additional Hooks, see subsection [useTabs](/docs/hooks/use-tabs) for details.

<Playground
  scope={{ Tabs, Grid }}
  desc="Toggle display of different templates."
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Tabs initialValue="1">
      <Tabs.Item label="Declarative" value="1">
        React makes it painless to create interactive UIs. Design simple views
        for each state in your application, and React will efficiently update
        and render just the right components when your data changes.
      </Tabs.Item>
      <Tabs.Item label="Component-Based" value="2">
        Build encapsulated components that manage their own state, then
        compose them to make complex UIs.
      </Tabs.Item>
    </Tabs>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Disabled"
  desc="You can change disabled `Tabs` with the property `disabled`."
  scope={{ Tabs, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Tabs initialValue="1">
      <Tabs.Item label="Declarative" value="1">
        React makes it painless to create interactive UIs. Design simple views
        for each state in your application, and React will efficiently update
        and render just the right components when your data changes.
      </Tabs.Item>
      <Tabs.Item label="Component-Based" value="2" disabled />
    </Tabs>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Slide"
  desc="The `slide` prop replaces the per tab underline with a single indicator that slides to the selected tab."
  scope={{ Tabs, Grid }}
  code={`
<Tabs initialValue="1" slide>
  <Tabs.Item label="Overview" value="1">
    A summary of the project.
  </Tabs.Item>
  <Tabs.Item label="Activity" value="2">
    Everything that changed this week.
  </Tabs.Item>
  <Tabs.Item label="Settings" value="3">
    Names, members and billing.
  </Tabs.Item>
</Tabs>
`}
/>

<Playground
  title="Hide Divider"
  desc="`Tabs` component with a hide divider functionality."
  scope={{ Tabs, Text, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Tabs initialValue="react" hideDivider>
      <Tabs.Item label="Declarative" value="react">
        <Text mt={0}>
          React makes it painless to create interactive UIs. Design simple
          views for each state in your application, and React will efficiently
          update and render just the right components when your data changes.
        </Text>
      </Tabs.Item>
      <Tabs.Item label="Component-Based" value="component-based">
        <Text mt={0}>
          Build encapsulated components that manage their own state, then
          compose them to make complex UIs.
        </Text>
      </Tabs.Item>
    </Tabs>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Hide Border"
  desc="`Tabs` component with a hide border functionality."
  scope={{ Tabs, Text, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Tabs initialValue="react" hideDivider hideBorder leftSpace={0}>
      <Tabs.Item label="Declarative" value="react">
        <Text mt={0}>
          React makes it painless to create interactive UIs. Design simple
          views for each state in your application, and React will efficiently
          update and render just the right components when your data changes.
        </Text>
      </Tabs.Item>
      <Tabs.Item label="Component-Based" value="component-based">
        <Text mt={0}>
          Build encapsulated components that manage their own state, then
          compose them to make complex UIs.
        </Text>
      </Tabs.Item>
    </Tabs>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="With Icon"
  desc="Show icon component on label button."
  scope={{ Tabs, Instagram, Facebook, Text, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Tabs initialValue="1" align="center" leftSpace={0}>
      <Tabs.Item
        label={
          <>
            <Instagram /> Instagram
          </>
        }
        value="1"
      >
        <Text mt={0}>Hello, this is my profile.</Text>
      </Tabs.Item>
      <Tabs.Item
        label={
          <>
            <Facebook /> Facebook
          </>
        }
        value="2"
      >
        <Text mt={0}>Hi, this is my page.</Text>
      </Tabs.Item>
    </Tabs>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Scroll Behavior"
  desc="If all tabs cannot fit in the width then then hidden tabs can be accessed through user agent scrolling mechanisms (e.g. left/right swipe, shift-mousewheel, etc.)"
  scope={{ Tabs, Instagram, Facebook, Text, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Tabs initialValue="1">
      <Tabs.Item label="Home" value="1">
        <Text>Hello!</Text>
      </Tabs.Item>
      <Tabs.Item label="About" value="2">
        <Text>Cool stuff.</Text>
      </Tabs.Item>
      <Tabs.Item label="About Us" value="3">
        <Text>Good people.</Text>
      </Tabs.Item>
      <Tabs.Item label="Features" value="4">
        <Text>Amazing.</Text>
      </Tabs.Item>
      <Tabs.Item label="Pricing" value="5">
        <Text>Very low.</Text>
      </Tabs.Item>
      <Tabs.Item label="Docs" value="6">
        <Text>Clear.</Text>
      </Tabs.Item>
      <Tabs.Item label="Profile" value="7">
        <Text>Extraordinary person.</Text>
      </Tabs.Item>
      <Tabs.Item label="Settings" value="8">
        <Text>Easy to tweak.</Text>
      </Tabs.Item>
      <Tabs.Item label="Dashboard" value="9">
        <Text>Charts.</Text>
      </Tabs.Item>
      <Tabs.Item label="Policies" value="10">
        <Text>Privacy focused.</Text>
      </Tabs.Item>
    </Tabs>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Imperatively"
  desc="Control components with imperatively style."
  scope={{ Tabs, Button, Grid, Code, Text, useState }}
  code={`
() => {
  const [value, setValue] = useState('1')
  const switchHandler = () => setValue('2')
  const changeHandler = val => setValue(val)
  return (
    <Grid.Container gap={2}>
      <Grid>
        <Button scale={1/3} font="12px" onClick={switchHandler}><Text>Select <Code>Component-Based</Code></Text></Button>
      </Grid>
      <Grid>
        <Tabs value={value} onChange={changeHandler}>
          <Tabs.Item label="declarative" value="1">React makes it painless to create interactive UIs. Design simple views for each state in your application, and React will efficiently update and render just the right components when your data changes.</Tabs.Item>
          <Tabs.Item label="component-based" value="2">Build encapsulated components that manage their own state, then compose them to make complex UIs.</Tabs.Item>
        </Tabs>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Playground
  title="Settings page"
  desc="Group a page by topic. Each tab holds the fields and the action for that topic only."
  scope={{ Tabs, Input, Text, Button, Spacer }}
  code={`
<Tabs initialValue="profile">
  <Tabs.Item label="Profile" value="profile">
    <Spacer h={1} />
    <Input floating width="100%" initialValue="Ada Lovelace">Name</Input>
    <Spacer h={1} />
    <Button auto type="primary">Save profile</Button>
  </Tabs.Item>
  <Tabs.Item label="Billing" value="billing">
    <Spacer h={1} />
    <Text p>You are on the Pro plan. The next charge of $12 is on Nov 3.</Text>
    <Button auto>Manage plan</Button>
  </Tabs.Item>
  <Tabs.Item label="Team" value="team">
    <Spacer h={1} />
    <Text p>3 members have access to this workspace.</Text>
    <Button auto>Invite a teammate</Button>
  </Tabs.Item>
</Tabs>
`}
/>

<Attributes edit="/content/docs/components/tabs.mdx">
<Attributes.Title>Tabs.Props</Attributes.Title>

| Attribute            | Description                             | Type                    | Accepted values                 | Default |
| -------------------- | --------------------------------------- | ----------------------- | ------------------------------- | ------- |
| **initialValue**     | initial value                           | `string`                | -                               | -       |
| **value**            | current selected value                  | `string`                | -                               | -       |
| **hideDivider**      | hide default divider                    | `boolean`               | -                               | `false` |
| **hideBorder**       | hide border on active                   | `boolean`               | -                               | `false` |
| **slide**            | sliding indicator under the active tab  | `boolean`               | -                               | `false` |
| **leftSpace**        | space area on the left side             | `CSSProperties`         | -                               | `12px`  |
| **onChange**         | change event                            | `(val: string) => void` | -                               | -       |
| **align**            | horizontal alignment of each child item | `justifyContent`        | -                               | `left`  |
| **activeClassName**  | className of active child item          | `string`                | -                               | -       |
| **activeStyles**     | style of active child item              | `object`                | -                               | -       |
| **hoverHeightRatio** | height percentage of highlight block    | `number`                | -                               | 0.7     |
| **hoverWidthRatio**  | width percentage of highlight block     | `number`                | -                               | 1.15    |
| ...                  | native props                            | `HTMLAttributes`        | `'alt', 'id', 'className', ...` | -       |

<Attributes.Title alias="Tabs.Tab">Tabs.Item.Props</Attributes.Title>

| Attribute           | Description         | Type      | Accepted values | Default |
| ------------------- | ------------------- | --------- | --------------- | ------- |
| **label**(required) | display tab's label | `string`  | -               | -       |
| **value**(required) | unique ident value  | `string`  | -               | -       |
| **disabled**        | disable current tab | `boolean` | -               | `false` |

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Tag, Grid, Text } from 'core'

export const meta = {
  title: 'Tag',
  description: 'Display a unique keyword, optionally as a part of a set.',
  sidebar: 'components',
  group: 'Components',
  index: 37
}

## Tag

Display a unique keyword, optionally as a part of a set.

<Playground
  desc="The basic `Tag` usage."
  scope={{ Tag, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Tag>Status: Unstable</Tag>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Types"
  desc="Show different states with colors."
  scope={{ Tag, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Tag>Default</Tag>
  </Grid>
  <Grid>
    <Tag type="primary">Primary</Tag>
  </Grid>
  <Grid>
    <Tag type="secondary">Secondary</Tag>
  </Grid>
  <Grid>
    <Tag type="success">Success</Tag>
  </Grid>
  <Grid>
    <Tag type="warning">Warning</Tag>
  </Grid>
  <Grid>
    <Tag type="error">Error</Tag>
  </Grid>
  <Grid>
    <Tag type="dark">Dark</Tag>
  </Grid>
  <Grid>
    <Tag type="lite">Lite</Tag>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Invert"
  desc="Invert color and background."
  scope={{ Tag, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Tag invert>Default</Tag>
  </Grid>
  <Grid>
    <Tag type="primary" invert>Primary</Tag>
  </Grid>
  <Grid>
    <Tag type="secondary" invert>Secondary</Tag>
  </Grid>
  <Grid>
    <Tag type="success" invert>Success</Tag>
  </Grid>
  <Grid>
    <Tag type="warning" invert>Warning</Tag>
  </Grid>
  <Grid>
    <Tag type="error" invert>Error</Tag>
  </Grid>
  <Grid>
    <Tag type="dark" invert>Dark</Tag>
  </Grid>
  <Grid>
    <Tag type="lite" invert>Lite</Tag>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Article header"
  desc="Tags beside a title classify the content. Keep each one to a word or two."
  scope={{ Tag, Text }}
  code={`
<div>
  <Text h4 my={0}>Designing accessible forms</Text>
  <div style={{ display: 'flex', flexWrap: 'wrap', gap: 8, marginTop: 8 }}>
    <Tag type="success" light>Published</Tag>
    <Tag subtle>Accessibility</Tag>
    <Tag subtle>Forms</Tag>
    <Tag>5 min read</Tag>
  </div>
</div>
`}
/>

<Attributes edit="/content/docs/components/tag.mdx">
<Attributes.Title>Tag.Props</Attributes.Title>

| Attribute  | Description                 | Type                  | Accepted values          | Default   |
| ---------- | --------------------------- | --------------------- | ------------------------ | --------- |
| **type**   | tag type                                    | [TagTypes](#tagtypes) | -                        | `default` |
| **invert** | filled variant: invert color and background | `boolean`              | -                        | `false`   |
| **light**  | light variant: tinted background            | `boolean`              | -                        | `false`   |
| **subtle** | subtle variant: no background               | `boolean`              | -                        | `false`   |
| ...        | native props                                | `HTMLAttributes`       | `'id', 'className', ...` | -         |

<Attributes.Title>TagTypes</Attributes.Title>

```ts
type TagTypes =
  | 'default'
  | 'secondary'
  | 'success'
  | 'warning'
  | 'error'
  | 'dark'
  | 'lite'
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { TagsInput, Grid, Text } from 'core'

export const meta = {
  title: 'Tags Input',
  description:
    'A field where each entry becomes a tag, for lists like skills, topics or email addresses.',
  sidebar: 'components',
  group: 'Components',
  index: 59
}

## Tags Input

A field where each entry becomes a tag. Enter or a comma ends a tag, and the
remove button or Backspace takes it out.

<Playground
  desc="Name the field with `aria-label`, or with a label passed as children."
  scope={{ TagsInput, Grid }}
  code={`
<Grid.Container gap={2} direction="column">
  <Grid>
    <TagsInput aria-label="Skills" placeholder="Add a skill" initialValue={['React', 'TypeScript']} />
  </Grid>
  <Grid>
    <TagsInput placeholder="Add a topic">Topics</TagsInput>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Controlled"
  desc="Pass `value` and `onChange` to keep the tags in your own state. `onChange` receives the whole list."
  scope={{ TagsInput, Grid, Text }}
  code={`
() => {
  const [tags, setTags] = React.useState(['design'])
  return (
    <Grid.Container gap={2} direction="column">
      <Grid>
        <TagsInput aria-label="Topics" value={tags} onChange={setTags} />
      </Grid>
      <Grid>
        <Text p>{tags.length} tags: {tags.join(', ')}</Text>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Playground
  title="Limit and duplicates"
  desc="`max` ignores the tags past it. A tag already in the list is skipped, unless `allowDuplicates` is set."
  scope={{ TagsInput, Grid }}
  code={`
<Grid.Container gap={2} direction="column">
  <Grid>
    <TagsInput aria-label="Up to 3 tags" max={3} placeholder="Up to 3 tags" initialValue={['one']} />
  </Grid>
  <Grid>
    <TagsInput aria-label="Repeated tags" allowDuplicates placeholder="Repeats allowed" initialValue={['go', 'go']} />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Variants"
  desc="Use `filled`, `light`, `ghost` or `subtle` with a `type` to change the surface of the field."
  scope={{ TagsInput, Grid }}
  code={`
<Grid.Container gap={2} direction="column">
  <Grid>
    <TagsInput type="primary" filled aria-label="Filled" initialValue={['one', 'two']} />
  </Grid>
  <Grid>
    <TagsInput type="success" light aria-label="Light" initialValue={['one', 'two']} />
  </Grid>
  <Grid>
    <TagsInput type="warning" subtle aria-label="Subtle" initialValue={['one', 'two']} />
  </Grid>
  <Grid>
    <TagsInput type="info" ghost rounded aria-label="Ghost" initialValue={['one', 'two']} />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Error"
  desc="`error` marks the field as invalid and shows `errorMessage` below it."
  scope={{ TagsInput }}
  code={`
<TagsInput error errorMessage="Add at least one tag." aria-label="Tags" />
`}
/>

<Playground
  title="Disabled and read only"
  desc="Both lock the field and the remove buttons."
  scope={{ TagsInput, Grid }}
  code={`
<Grid.Container gap={2} direction="column">
  <Grid>
    <TagsInput disabled aria-label="Disabled" initialValue={['one', 'two']} />
  </Grid>
  <Grid>
    <TagsInput readOnly aria-label="Read only" initialValue={['one', 'two']} />
  </Grid>
</Grid.Container>
`}
/>

<Attributes edit="/content/docs/components/tags-input.mdx">
<Attributes.Title>TagsInput.Props</Attributes.Title>

| Attribute           | Description                                              | Type                         | Accepted values                                                       | Default   |
| ------------------- | -------------------------------------------------------- | ---------------------------- | --------------------------------------------------------------------- | --------- |
| **value**           | tags, to control the field                               | `string[]`                   | -                                                                     | -         |
| **initialValue**    | tags on the first render                                 | `string[]`                   | -                                                                     | `[]`      |
| **onChange**        | called with the whole list when a tag is added or removed | `(tags: string[]) => void`  | -                                                                     | -         |
| **max**             | most tags the field holds; the next ones are ignored     | `number`                     | -                                                                     | -         |
| **allowDuplicates** | accepts a tag that is already in the list                | `boolean`                    | -                                                                     | `false`   |
| **type**            | color of the field                                       | `string`                     | `'default', 'primary', 'secondary', 'success', 'warning', 'error', 'info'` | `default` |
| **rounded**         | rounded corners                                          | `boolean`                    | -                                                                     | `false`   |
| **filled**          | filled surface                                           | `boolean`                    | -                                                                     | `false`   |
| **light**           | light surface                                            | `boolean`                    | -                                                                     | `false`   |
| **ghost**           | ghost surface                                            | `boolean`                    | -                                                                     | `false`   |
| **subtle**          | subtle surface                                           | `boolean`                    | -                                                                     | `false`   |
| **disabled**        | locks the field                                          | `boolean`                    | -                                                                     | `false`   |
| **readOnly**        | shows the tags without changing them                     | `boolean`                    | -                                                                     | `false`   |
| **error**           | marks the field as invalid                               | `boolean`                    | -                                                                     | `false`   |
| **errorMessage**    | text shown below the field with `error`                  | `string`                     | -                                                                     | -         |
| ...                 | native props, passed to the `input`                      | `InputHTMLAttributes`        | `'placeholder', 'aria-label', 'id', ...`                              | -         |

<Attributes.Title>Adding and removing tags</Attributes.Title>

- • **Enter** turns the text into a tag. With an empty field, Enter works as usual, so a form can still submit.
- • **A comma** ends a tag, typed or pasted, so `a, b, c` becomes three tags.
- • **Leaving the field** adds the text that is still in it.
- • **Backspace** on an empty field removes the last tag, and each tag also has a remove button.
- • Spaces around a tag are trimmed, and empty tags are ignored.

<Attributes.Title>Ref</Attributes.Title>

The `ref` points at the `input`.

<Attributes.Title>Accessibility</Attributes.Title>

The field is a native text input, so a label passed as children, or `aria-label`, names it. Each remove button is named after its tag, like "Remove React", and sits in the tab order. `error` sets `aria-invalid` and links the message with `aria-describedby`.

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Text, Grid } from 'core'

export const meta = {
  title: 'Text',
  description: 'Display text using well-defined typographic styles.',
  sidebar: 'components',
  group: 'Components',
  index: 38
}

## Text

Display text using well-defined typographic styles.

<Playground
  title="Headings"
  desc="Use `Text` to standardize text content."
  scope={{ Text, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Text h1>Hello my friend, have fun with Bolio UI 🥷🏼</Text>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Paragraph"
  desc="Add `p` and `b` attributes to a `Text`."
  scope={{ Text, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Text p>
      Make your development more creative and with amazing tools for React.
    </Text>
    <Text p b>
      Make your development more creative and with amazing tools for React.
    </Text>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Small"
  desc="Add `small` attributes to a Text."
  scope={{ Text, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Text small>
      React makes it painless to create interactive UIs. Design simple views
      for each state in your application, and React will efficiently update
      and render just the right components when your data changes.
    </Text>
    <Text small i>
      React makes it painless to create interactive UIs. Design simple views
      for each state in your application, and React will efficiently update
      and render just the right components when your data changes.
    </Text>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Blockquote"
  desc="Add `blockquote` attributes to a Text."
  scope={{ Text, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Text blockquote my={0}>
      Build encapsulated components that manage their own state, then compose
      them to make complex UIs.
    </Text>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Types"
  desc="You can change the color of the `Text` with the property `type`."
  scope={{ Text, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Text b i style={{ letterSpacing: '0.6px' }}>
      <Grid>
        <Text span type="default">
          Text colored
        </Text>
      </Grid>
      <Grid>
        <Text span type="primary">
          Text colored
        </Text>
      </Grid>
      <Grid>
        <Text span type="secondary">
          Text colored
        </Text>
      </Grid>
      <Grid>
        <Text span type="success">
          Text colored
        </Text>
      </Grid>
      <Grid>
        <Text span type="warning">
          Text colored
        </Text>
      </Grid>
      <Grid>
        <Text span type="error">
          Text colored
        </Text>
      </Grid>
      <Grid>
        <Text span type="info">
          Text colored
        </Text>
      </Grid>
    </Text>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Sizes"
  desc="`Text` of different sizes."
  scope={{ Text, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Text font="12px" mt={0}>
      Font Size: 12px;
    </Text>
    <Text font="14px">Font Size: 14px;</Text>
    <Text font="1rem">Font Size: 1rem;</Text>
    <Text scale={1.25} mb={0}>
      Font Size Scale: 1.25;
    </Text>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Compose"
  desc="Effect of multiple `Text` stacks"
  scope={{ Text, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Text p mt={0}>
      Build encapsulated components that manage their own state, then compose
      them to make complex UIs.
    </Text>
    <Text mb={0}>
      <Text small del>
        Since component logic is written in JavaScript instead of templates,
        you can easily pass rich data through your app and keep state out of
        the DOM.
      </Text>
      <Text small b>
        We don’t make assumptions about the rest of your technology stack, so
        you can develop new features in React without rewriting existing code.
      </Text>
    </Text>
  </Grid>
</Grid.Container>
`}
/>

<Attributes edit="/content/docs/components/text.mdx">
<Attributes.Title>Text.Props</Attributes.Title>

| Attribute      | Description    | Type             | Accepted values          | Default   |
| -------------- | -------------- | ---------------- | ------------------------ | --------- |
| **p**          | component name | `boolean`        | -                        | `true`    |
| **h1 - h6**    | component name | `boolean`        | -                        | `false`   |
| **small**      | component name | `boolean`        | -                        | `false`   |
| **span**       | component name | `boolean`        | -                        | `false`   |
| **del**        | component name | `boolean`        | -                        | `false`   |
| **i**          | component name | `boolean`        | -                        | `false`   |
| **em**         | component name | `boolean`        | -                        | `false`   |
| **b**          | component name | `boolean`        | -                        | `false`   |
| **blockquote** | component name | `boolean`        | -                        | `false`   |
| **type**       | text type      | `TextTypes`      | [TextTypes](#texttypes)  | `default` |
| ...            | native props   | `HTMLAttributes` | `'id', 'className', ...` | -         |

<Attributes.Title>TextTypes</Attributes.Title>

```ts
type TextTypes =
  | 'default'
  | 'primary'
  | 'secondary'
  | 'success'
  | 'warning'
  | 'error'
  | 'info'
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Textarea, Grid, useInput, Button, Code } from 'core'
import { useState } from 'react'

export const meta = {
  title: 'Textarea',
  description: 'Retrieve multi-line user input.',
  sidebar: 'components',
  group: 'Components',
  index: 39
}

## Textarea

Retrieve multi-line user input.

<Playground
  desc="Basic usage."
  scope={{ Textarea, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Textarea placeholder="Enter a message." />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Disabled"
  desc="Disable interactive textarea."
  scope={{ Textarea, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Textarea
      width="100%"
      disabled
      placeholder="This documentation always reflects the latest stable version of React. Since React 16, you can find older versions of the documentation on a separate page. Note that documentation for past versions is snapshotted at the time of the release, and isn’t being continuously updated."
    />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Type"
  desc="Differentiate states by color."
  scope={{ Textarea, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Textarea height="65px" value="Default" />
  </Grid>
  <Grid>
    <Textarea type="primary" height="65px" value="Primary" />
  </Grid>
  <Grid>
    <Textarea type="secondary" height="65px" value="Secondary" />
  </Grid>
  <Grid>
    <Textarea type="success" height="65px" value="Success" />
  </Grid>
  <Grid>
    <Textarea type="warning" height="65px" value="Warning" />
  </Grid>
  <Grid>
    <Textarea type="error" height="65px" value="Error" />
  </Grid>
  <Grid>
    <Textarea type="info" height="65px" value="Info" />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Variants"
  desc="Use `filled`, `light`, `ghost` or `subtle` to change the surface of any colored `Textarea`."
  scope={{ Textarea, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Textarea type="primary" height="65px" placeholder="Primary filled" filled />
  </Grid>
  <Grid>
    <Textarea type="secondary" height="65px" placeholder="Secondary filled" filled />
  </Grid>
  <Grid>
    <Textarea type="success" height="65px" placeholder="Success filled" filled />
  </Grid>
  <Grid>
    <Textarea type="warning" height="65px" placeholder="Warning filled" filled />
  </Grid>
  <Grid>
    <Textarea type="error" height="65px" placeholder="Error filled" filled />
  </Grid>
  <Grid>
    <Textarea type="info" height="65px" placeholder="Info filled" filled />
  </Grid>
  <Grid>
    <Textarea type="primary" height="65px" placeholder="Primary light" light />
  </Grid>
  <Grid>
    <Textarea type="secondary" height="65px" placeholder="Secondary light" light />
  </Grid>
  <Grid>
    <Textarea type="success" height="65px" placeholder="Success light" light />
  </Grid>
  <Grid>
    <Textarea type="warning" height="65px" placeholder="Warning light" light />
  </Grid>
  <Grid>
    <Textarea type="error" height="65px" placeholder="Error light" light />
  </Grid>
  <Grid>
    <Textarea type="info" height="65px" placeholder="Info light" light />
  </Grid>
  <Grid>
    <Textarea type="primary" height="65px" placeholder="Primary ghost" ghost />
  </Grid>
  <Grid>
    <Textarea type="secondary" height="65px" placeholder="Secondary ghost" ghost />
  </Grid>
  <Grid>
    <Textarea type="success" height="65px" placeholder="Success ghost" ghost />
  </Grid>
  <Grid>
    <Textarea type="warning" height="65px" placeholder="Warning ghost" ghost />
  </Grid>
  <Grid>
    <Textarea type="error" height="65px" placeholder="Error ghost" ghost />
  </Grid>
  <Grid>
    <Textarea type="info" height="65px" placeholder="Info ghost" ghost />
  </Grid>
  <Grid>
    <Textarea type="primary" height="65px" placeholder="Primary subtle" subtle />
  </Grid>
  <Grid>
    <Textarea type="secondary" height="65px" placeholder="Secondary subtle" subtle />
  </Grid>
  <Grid>
    <Textarea type="success" height="65px" placeholder="Success subtle" subtle />
  </Grid>
  <Grid>
    <Textarea type="warning" height="65px" placeholder="Warning subtle" subtle />
  </Grid>
  <Grid>
    <Textarea type="error" height="65px" placeholder="Error subtle" subtle />
  </Grid>
  <Grid>
    <Textarea type="info" height="65px" placeholder="Info subtle" subtle />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Rounded"
  desc="You can completely round the corners of any type of `Textarea` with the `rounded` property."
  scope={{ Textarea, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Textarea type="primary" height="65px" placeholder="Primary" rounded />
  </Grid>
  <Grid>
    <Textarea type="secondary" height="65px" placeholder="Secondary" rounded />
  </Grid>
  <Grid>
    <Textarea type="success" height="65px" placeholder="Success" rounded />
  </Grid>
  <Grid>
    <Textarea type="warning" height="65px" placeholder="Warning" rounded />
  </Grid>
  <Grid>
    <Textarea type="error" height="65px" placeholder="Error" rounded />
  </Grid>
  <Grid>
    <Textarea type="info" height="65px" placeholder="Info" rounded />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Get Change"
  desc="Capture changes in textarea."
  scope={{ Textarea, Grid, useState }}
  code={`
() => {
  const [value, setValue] = useState()
  const handler = (e) => {
    setValue(e.target.value)
    console.log(e.target.value)
  }
  return (
    <Grid.Container gap={2}>
      <Grid>
        <Textarea
          width="100%"
          value={value}
          onChange={handler}
          placeholder="This documentation always reflects the latest stable version of React. Since React 16, you can find older versions of the documentation on a separate page. Note that documentation for past versions is snapshotted at the time of the release, and isn’t being continuously updated."
        />
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Playground
  title="With useInput"
  desc="Use `hooks` to capture changes."
  scope={{ Textarea, useInput, Button, Grid }}
  code={`
() => {
  const { setState, reset, bindings } = useInput(
    'This documentation always reflects the latest stable version of React. Since React 16, you can find older versions of the documentation on a separate page. Note that documentation for past versions is snapshotted at the time of the release, and isn’t being continuously updated.'
  )
  return (
    <Grid.Container gap={2}>
      <Grid>
        <Textarea width="100%" {...bindings} />
      </Grid>
      <Grid>
        <Button
          auto
          type="secondary"
          scale={1 / 3}
          onClick={() => setState(Math.random().toString(32))}
        >
          insert value
        </Button>
      </Grid>
      <Grid>
        <Button auto scale={1 / 3} onClick={() => reset()}>
          clear value
        </Button>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Playground
  title="Imperative API"
  desc="Update component in an uncontrolled way."
  scope={{ Textarea, Grid, Button }}
  code={`
() => {
  const ref = React.useRef(null)
  const setChange = () => {
    ref && (ref.current.value = Math.random().toString(32))
  }
  return (
    <Grid.Container gap={2}>
      <Grid>
        <Textarea initialValue="Text Here" onChange={e => console.log(e.target.value)} ref={ref} />
      </Grid>
      <Grid>
        <Button auto type="secondary" scale={1/3} onClick={setChange}>Set Value</Button>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Attributes edit="/content/docs/components/textarea.mdx">
<Attributes.Title alias="Input.Textarea">Textarea.Props</Attributes.Title>

| Attribute        | Description     | Type                             | Accepted values                  | Default   |
| ---------------- | --------------- | -------------------------------- | -------------------------------- | --------- |
| **value**        | textarea value  | `string`                         | -                                | -         |
| **initialValue** | textarea value  | `string`                         | -                                | -         |
| **placeholder**  | placeholder     | `string`                         | -                                | -         |
| **type**         | current type    | `TextareaTypes`                  | [TextareaTypes](#textareatypes)  | `default` |
| **readOnly**     | native attr     | `boolean`                        | -                                | `false`   |
| **disabled**     | disable input   | `boolean`                        | -                                | `false`   |
| **rounded**      | round corners   | `boolean`                        | -                                | `false`   |
| **filled**       | filled variant  | `boolean`                        | -                                | `false`   |
| **light**        | light variant   | `boolean`                        | -                                | `false`   |
| **ghost**        | outline variant | `boolean`                        | -                                | `false`   |
| **subtle**       | subtle variant  | `boolean`                        | -                                | `false`   |
| **onChange**     | change event    | `(e: React.ChangeEvent) => void` | -                                | -         |
| **resize**       | CSS attribute   | `CSSResize`                      | [CSSResize](#cssresize)          | `none`    |
| ...              | native props    | `TextareaHTMLAttributes`         | `'form', 'id', 'className', ...` | -         |

<Attributes.Title>useInput</Attributes.Title>

```ts
type useInput = (initialValue: string) => {
  state: string
  setState: Dispatch<SetStateAction<string>>
  currentRef: MutableRefObject<string>
  reset: () => void
  bindings: {
    value: string
    onChange: (event: React.ChangeEvent<HTMLInputElement>) => void
  }
}
```

<Attributes.Title>TextareaTypes</Attributes.Title>

```ts
type TextareaTypes =
  'default' | 'primary' | 'secondary' | 'success' | 'warning' | 'error' | 'info'
```

<Attributes.Title>CSSResize</Attributes.Title>

```ts
type CSSResize =
  'none' | 'both' | 'horizontal' | 'vertical' | 'initial' | 'inherit'
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Timeline } from 'core'
import { GitCommit, Check, Package, Truck, MapPin, MessageSquare, UserPlus, FileText } from '@bolio-ui/icons'

export const meta = {
  title: 'Timeline',
  description: 'List events in order, such as a changelog or an activity feed.',
  sidebar: 'components',
  group: 'Components',
  index: 55
}

## Timeline

List events in order, such as a changelog or an activity feed.

<Playground
  title="General"
  desc="The basic `Timeline` usage."
  scope={{ Timeline }}
  code={`
<Timeline>
  <Timeline.Item title="Order placed" time="Mon, 9:41">
    We received your order and are preparing it.
  </Timeline.Item>
  <Timeline.Item title="Shipped" time="Tue, 14:05">
    The package left the warehouse.
  </Timeline.Item>
  <Timeline.Item title="Delivered" time="Thu, 10:12" />
</Timeline>
`}
/>

<Playground
  title="With Icons"
  desc="Replace the dot with any icon using `icon`."
  scope={{ Timeline, GitCommit, Check }}
  code={`
<Timeline>
  <Timeline.Item icon={<GitCommit />} title="v2.1.0" time="Oct 2">
    Added spotlight to Card and Button.
  </Timeline.Item>
  <Timeline.Item icon={<GitCommit />} title="v2.0.1" time="Sep 21">
    Fixed ButtonGroup ghost borders.
  </Timeline.Item>
  <Timeline.Item icon={<Check />} title="v2.0.0" time="Sep 1">
    First stable release.
  </Timeline.Item>
</Timeline>
`}
/>

<Playground
  title="Order tracking"
  desc="Use an icon for each stage, and write the time in the same format on every item."
  scope={{ Timeline, Package, Truck, MapPin, Check }}
  code={`
<Timeline>
  <Timeline.Item icon={<Package />} title="Order packed" time="Mon, 09:41">
    Your 2 items are ready at the warehouse.
  </Timeline.Item>
  <Timeline.Item icon={<Truck />} title="On the way" time="Tue, 14:05">
    The carrier picked up the package in Lisbon.
  </Timeline.Item>
  <Timeline.Item icon={<MapPin />} title="Out for delivery" time="Thu, 08:30">
    Arrives today between 10:00 and 13:00.
  </Timeline.Item>
  <Timeline.Item icon={<Check />} title="Delivered" time="Thu, 10:12" />
</Timeline>
`}
/>

<Playground
  title="Activity feed"
  desc="Name who did what in the title and keep the detail short."
  scope={{ Timeline, MessageSquare, UserPlus, FileText }}
  code={`
<Timeline>
  <Timeline.Item icon={<MessageSquare />} title="Ana commented" time="2 min ago">
    “The new pricing table looks good to ship.”
  </Timeline.Item>
  <Timeline.Item icon={<FileText />} title="Rui edited Pricing.md" time="1 hour ago" />
  <Timeline.Item icon={<UserPlus />} title="Marta joined the team" time="Yesterday" />
</Timeline>
`}
/>

<Attributes edit="/content/docs/components/timeline.mdx">
<Attributes.Title>Timeline.Props</Attributes.Title>

| Attribute | Description  | Type            | Accepted values | Default |
| --------- | ------------ | --------------- | --------------- | ------- |
| ...       | native props | `HTMLAttributes` | -              | -       |


<Attributes.Title>Timeline.Item.Props</Attributes.Title>

| Attribute | Description                  | Type             | Accepted values | Default |
| --------- | ---------------------------- | ---------------- | --------------- | ------- |
| **title** | event title                  | `ReactNode`      | -               | -       |
| **time**  | date or time beside the title | `ReactNode`     | -               | -       |
| **icon**  | replaces the default dot     | `ReactNode`      | -               | -       |
| ...       | native props                 | `HTMLAttributes` | -               | -       |

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Toggle, Grid, Card, Text } from 'core'
import { Sun, Moon } from '@bolio-ui/icons'

export const meta = {
  title: 'Toggle',
  description: 'Displays a boolean value.',
  sidebar: 'components',
  group: 'Components',
  index: 40
}

## Toggle

Displays a boolean value.

<Playground
  desc="The basic `Toggle` usage."
  scope={{ Toggle, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Toggle scale={2} />
  </Grid>
  <Grid>
    <Toggle scale={2} initialChecked />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Type"
  desc="Differentiate states by color."
  scope={{ Toggle, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Toggle type="default" scale={2} initialChecked />
  </Grid>
  <Grid>
    <Toggle type="primary" scale={2} initialChecked />
  </Grid>
  <Grid>
    <Toggle type="secondary" scale={2} initialChecked />
  </Grid>
  <Grid>
    <Toggle type="success" scale={2} initialChecked />
  </Grid>
  <Grid>
    <Toggle type="warning" scale={2} initialChecked />
  </Grid>
  <Grid>
    <Toggle type="error" scale={2} initialChecked />
  </Grid>
  <Grid>
    <Toggle type="info" scale={2} initialChecked />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="With Icons"
  desc="Show an icon inside the thumb with `icon`, and a different one when checked with `checkedIcon`."
  scope={{ Toggle, Grid, Sun, Moon }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Toggle scale={1.5} icon={<Sun />} checkedIcon={<Moon />} />
  </Grid>
  <Grid>
    <Toggle scale={1.5} type="success" initialChecked icon={<Sun />} checkedIcon={<Moon />} />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Disabled"
  desc="You can change disabled `Toggle` with the property `disabled`."
  scope={{ Toggle, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Toggle scale={2} disabled />
  </Grid>
  <Grid>
    <Toggle scale={2} initialChecked disabled />
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Get Change"
  desc="Capture changes in `Toggle`."
  scope={{ Toggle, Grid }}
  code={`
() => {
  const handler = event => {
    console.log(event.target.checked)
  }
  return (
    <Grid.Container gap={2}>
      <Grid>
        <Toggle onChange={handler} scale={2} />
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Playground
  title="Notification settings"
  desc="Put the label and what it does on the left and the `Toggle` on the right, and name each switch with `aria-label`."
  scope={{ Toggle, Card, Text }}
  code={`
() => {
  const [prefs, setPrefs] = React.useState({ email: true, push: false, news: false })
  const rows = [
    ['email', 'Email', 'Comments and mentions'],
    ['push', 'Push', 'Alerts on your phone'],
    ['news', 'Newsletter', 'One email a month']
  ]
  const update = (key) => (event) =>
    setPrefs((last) => ({ ...last, [key]: event.target.checked }))
  return (
    <Card bordered width="100%">
      {rows.map(([key, label, hint]) => (
        <div key={key} style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between', padding: '8px 0' }}>
          <div>
            <Text p my={0}><b>{label}</b></Text>
            <Text small type="secondary">{hint}</Text>
          </div>
          <Toggle checked={prefs[key]} onChange={update(key)} aria-label={label} />
        </div>
      ))}
    </Card>
  )
}
`}
/>

<Attributes edit="/content/docs/components/toggle.mdx">
<Attributes.Title>Toggle.Props</Attributes.Title>

| Attribute          | Description               | Type                  | Accepted values                    | Default   |
| ------------------ | ------------------------- | --------------------- | ---------------------------------- | --------- |
| **checked**        | checked or not            | `boolean`             | -                                  | -         |
| **initialChecked** | checked or not on initial | `boolean`             | -                                  | `false`   |
| **onChange**       | change event handler      | `ToggleEvent`         | -                                  | -         |
| **type**           | current type              | `ToggleTypes`         | [ToggleTypes](#toggletypes)        | `default` |
| **disabled**       | disable toggle            | `boolean`             | -                                  | `false`   |
| **icon**           | icon inside the thumb     | `ReactNode`           | -                                  | -         |
| **checkedIcon**    | icon when checked, falls back to `icon` | `ReactNode` | -                              | -         |
| ...                | native props              | `LabelHTMLAttributes` | `'from', 'name', 'className', ...` | -         |

<Attributes.Title>ToggleEvent</Attributes.Title>

```ts
interface ToggleEventTarget {
  checked: boolean
}

export interface ToggleEvent {
  target: ToggleEventTarget
  stopPropagation: () => void
  preventDefault: () => void
  nativeEvent: React.ChangeEvent
}
```

<Attributes.Title>ToggleTypes</Attributes.Title>

```ts
type ToggleTypes =
  | 'default'
  | 'primary'
  | 'secondary'
  | 'success'
  | 'warning'
  | 'error'
  | 'info'
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Toolbar, Button, Chip, Text } from 'core'

export const meta = {
  title: 'Toolbar',
  description: 'Group related controls in one tab stop and move between them with the arrow keys.',
  sidebar: 'components',
  group: 'Components',
  index: 56
}

## Toolbar

Group related controls in one tab stop and move between them with the arrow keys.

<Playground
  title="General"
  desc="Tab enters the `Toolbar` once and leaves it on the next Tab. Inside, the arrow keys, Home and End move the focus. Give it an `aria-label`."
  scope={{ Toolbar, Button }}
  code={`
<Toolbar aria-label="Text formatting">
  <Button auto scale={0.75} subtle>Bold</Button>
  <Button auto scale={0.75} subtle>Italic</Button>
  <Button auto scale={0.75} subtle>Underline</Button>
  <Toolbar.Separator />
  <Button auto scale={0.75} subtle>Link</Button>
  <Button auto scale={0.75} subtle disabled>Image</Button>
</Toolbar>
`}
/>

<Playground
  title="Vertical"
  desc="With `orientation` set to vertical, the Up and Down arrows move the focus."
  scope={{ Toolbar, Button }}
  code={`
<Toolbar orientation="vertical" aria-label="Zoom">
  <Button auto scale={0.75} subtle>Zoom in</Button>
  <Button auto scale={0.75} subtle>Zoom out</Button>
  <Toolbar.Separator />
  <Button auto scale={0.75} subtle>Fit to screen</Button>
</Toolbar>
`}
/>

<Playground
  title="Editor actions"
  desc="Mix buttons and chips. The text below shows which formats are on."
  scope={{ Toolbar, Button, Chip, Text }}
  code={`
() => {
  const [formats, setFormats] = React.useState(['bold'])
  const toggle = (name) =>
    setFormats((current) => current.includes(name) ? current.filter((f) => f !== name) : [...current, name])
  return (
    <>
      <Toolbar aria-label="Formatting">
        {['bold', 'italic', 'underline'].map((name) => (
          <Chip key={name} checked={formats.includes(name)} onChange={() => toggle(name)} style={{ textTransform: 'capitalize' }}>
            {name}
          </Chip>
        ))}
        <Toolbar.Separator />
        <Button auto scale={0.75} subtle onClick={() => setFormats([])}>Clear</Button>
      </Toolbar>
      <Text small type="secondary">{formats.length ? 'On: ' + formats.join(', ') : 'No format is on.'}</Text>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/components/toolbar.mdx">
<Attributes.Title>Toolbar.Props</Attributes.Title>

| Attribute       | Description                                       | Type                         | Accepted values | Default      |
| --------------- | ------------------------------------------------- | ---------------------------- | --------------- | ------------ |
| **orientation** | direction of the row and of the arrow keys        | `'horizontal' \| 'vertical'` | -               | `horizontal` |
| ...             | native props, such as `aria-label`                | `HTMLAttributes`             | -               | -            |

<Attributes.Title>Toolbar.Separator.Props</Attributes.Title>

| Attribute | Description  | Type             | Accepted values | Default |
| --------- | ------------ | ---------------- | --------------- | ------- |
| ...       | native props | `HTMLAttributes` | -               | -       |

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Tooltip, Grid, Button, Link, Badge, Code, Text } from 'core'

export const meta = {
  title: 'Tooltip',
  description: 'Displays additional information on hover.',
  sidebar: 'components',
  group: 'Components',
  index: 41
}

## Tooltip

Displays additional information on hover.

<Playground
  desc="Basic usage."
  scope={{ Tooltip, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Tooltip text={'Push to Git and your website is live.'}>Tooltip</Tooltip>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Trigger"
  desc="Trigger by click."
  scope={{ Tooltip, Grid }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Tooltip
      text={'Push to Git and your website is live.'}
      trigger="click"
      type="dark"
    >
      Click me
    </Tooltip>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="With Components"
  desc="Combined with different components."
  scope={{ Tooltip, Button, Link, Grid, Badge }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Tooltip text={'Push to Git and your website is live.'} type="dark">
      <Button auto scale={1 / 2}>
        Button
      </Button>
    </Tooltip>
  </Grid>
  <Grid>
    <Tooltip text={'Push to Git and your website is live.'} type="dark">
      <Badge>1000+</Badge>
    </Tooltip>
  </Grid>
  <Grid>
    <Tooltip text={'Push to Git and your website is live.'} type="dark">
      <Link href="#" color>
        Hyperlink
      </Link>
    </Tooltip>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Custom Content"
  desc="You can customize the pop-up content."
  scope={{ Tooltip, Grid, Code, Text }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Tooltip
      text={
        <>
          Perfect for working with a <Code>CMS</Code>.
        </>
      }
    >
      Top
    </Tooltip>
  </Grid>
  <Grid>
    <Tooltip
      text={
        <>
          <Text b>Perfect</Text> for working with a CMS.
        </>
      }
      placement="bottom"
    >
      Bottom
    </Tooltip>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Types"
  desc="Different state."
  scope={{ Tooltip, Grid, Code, Text }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Tooltip text="Perfect for working with a CMS." type="dark">
      Dark
    </Tooltip>
  </Grid>
  <Grid>
    <Tooltip text="Perfect for working with a CMS." type="success">
      Success
    </Tooltip>
  </Grid>
  <Grid>
    <Tooltip text="Perfect for working with a CMS." type="warning">
      Warning
    </Tooltip>
  </Grid>
  <Grid>
    <Tooltip text="Perfect for working with a CMS." type="error">
      Error
    </Tooltip>
  </Grid>
  <Grid>
    <Tooltip text="Perfect for working with a CMS." type="secondary">
      Secondary
    </Tooltip>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Variant"
  desc="Special styles."
  scope={{ Tooltip, Grid, Code, Text }}
  code={`
<Grid.Container gap={2}>
  <Grid>
    <Tooltip text="Push to Git and your website is live." type="lite">
      Lite
    </Tooltip>
  </Grid>
  <Grid>
    <Tooltip text="Push to Git and your website is live." hideArrow>
      No Arrow
    </Tooltip>
  </Grid>
</Grid.Container>
`}
/>

<Playground
  title="Placements"
  desc="There are 12 `placement` options available."
  scope={{ Tooltip, Grid }}
  code={`
() => {
  const text = 'HTTP is stateless, but not sessionless'
  return (
    <Grid.Container gap={2} justify="center" alignItems="center">
      <Grid xs={4} justify="flex-end">
        <Tooltip text={text} placement="topStart" type="dark">
          topStart
        </Tooltip>
      </Grid>
      <Grid xs={4} justify="center">
        <Tooltip text={text} placement="top" type="dark">
          top
        </Tooltip>
      </Grid>
      <Grid xs={4}>
        <Tooltip text={text} placement="topEnd" type="dark">
          topEnd
        </Tooltip>
      </Grid>
      <Grid xs={3} justify="flex-end">
        <Tooltip text={text} placement="leftStart" type="dark">
          leftStart
        </Tooltip>
      </Grid>
      <Grid xs={6} />
      <Grid xs={3}>
        <Tooltip text={text} placement="rightStart" type="dark">
          rightStart
        </Tooltip>
      </Grid>
      <Grid xs={3} justify="flex-end">
        <Tooltip text={text} placement="left" type="dark">
          left
        </Tooltip>
      </Grid>
      <Grid xs={6} />
      <Grid xs={3}>
        <Tooltip text={text} placement="right" type="dark">
          right
        </Tooltip>
      </Grid>
      <Grid xs={3} justify="flex-end">
        <Tooltip text={text} placement="leftEnd" type="dark">
          leftEnd
        </Tooltip>
      </Grid>
      <Grid xs={6} />
      <Grid xs={3}>
        <Tooltip text={text} placement="rightEnd" type="dark">
          rightEnd
        </Tooltip>
      </Grid>
      <Grid xs={4} justify="flex-end">
        <Tooltip text={text} placement="bottomStart" type="dark">
          bottomStart
        </Tooltip>
      </Grid>
      <Grid xs={4} justify="center">
        <Tooltip text={text} placement="bottom" type="dark">
          bottom
        </Tooltip>
      </Grid>
      <Grid xs={4}>
        <Tooltip text={text} placement="bottomEnd" type="dark">
          bottomEnd
        </Tooltip>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Attributes edit="/content/docs/components/tooltip.mdx">
<Attributes.Title>Tooltip.Props</Attributes.Title>

| Attribute           | Description                                                | Type                          | Accepted values | Default   |
| ------------------- | ---------------------------------------------------------- | ----------------------------- | --------------- | --------- |
| **text**            | text of pop-up                                             | `string` `React.ReactNode`    | -               | -         |
| **visible**         | visible or not                                             | `boolean`                     | -               | `false`   |
| **initialVisible**  | visible on initial                                         | `boolean`                     | -               | `false`   |
| **hideArrow**       | hide arrow icon                                            | `boolean`                     | -               | `false`   |
| **type**            | preset style type                                          | [TooltipTypes](#tooltiptypes) | -               | `default` |
| **light**           | light variant: tinted background                           | `boolean`                     | -               | `false`   |
| **ghost**           | outline variant: page background, colored border           | `boolean`                     | -               | `false`   |
| **subtle**          | subtle variant: no background                               | `boolean`                     | -               | `false`   |
| **placement**       | position of the tooltip relative to the target             | [Placement](#placement)       | -               | `top`     |
| **trigger**         | tooltip trigger mode                                       | `'click' / 'hover'`           | -               | `hover`   |
| **enterDelay**(ms)  | delay before tooltip is shown                              | `number`                      | -               | `100`     |
| **leaveDelay**(ms)  | delay before tooltip is hidden (only work in 'hover' mode) | `number`                      | -               | `150`     |
| **offset**(px)      | distance between pop-up and target                         | `number`                      | -               | `12`      |
| **portalClassName** | className of pop-up box                                    | `string`                      | -               | -         |
| **onVisibleChange** | call when visibility of the tooltip is changed             | `(visible: boolean) => void`  | -               | -         |
| ...                 | native props                                               | `HTMLAttributes`              | `'id' ...`      | -         |

<Attributes.Title>TooltipTypes</Attributes.Title>

```ts
type TooltipTypes =
  | 'default'
  | 'secondary'
  | 'success'
  | 'warning'
  | 'error'
  | 'dark'
  | 'lite'
```

<Attributes.Title>Placement</Attributes.Title>

```ts
type Placement = 'top'
  | 'topStart',
  | 'topEnd',
  | 'left',
  | 'leftStart',
  | 'leftEnd',
  | 'bottom',
  | 'bottomStart',
  | 'bottomEnd',
  | 'right',
  | 'rightStart',
  | 'rightEnd',
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Tour, Button, Grid, Card, Text, Input } from 'core'

export const meta = {
  title: 'Tour',
  description:
    'A guided walk through a page: each step highlights an element and explains it.',
  sidebar: 'components',
  group: 'Components',
  index: 70
}

## Tour

A guided walk through a page. Each step highlights an element and explains it in a
card next to it, with buttons to go forward and back. Use it the first time
someone opens a page with parts that are not obvious.

<Playground
  desc="Each step has a `title`, a `content` and a `target`, a CSS selector of the element to highlight. `open` and `onClose` are yours to keep."
  scope={{ Tour, Button, Grid, Input, Card, Text }}
  code={`
() => {
  const [open, setOpen] = React.useState(false)
  return (
    <>
      <Grid.Container gap={2} alignItems="center">
        <Grid>
          <Input id="tour-search" placeholder="Search invoices" />
        </Grid>
        <Grid>
          <Button id="tour-filter" auto>Filters</Button>
        </Grid>
        <Grid>
          <Button id="tour-export" auto type="primary">Export</Button>
        </Grid>
        <Grid>
          <Button auto ghost onClick={() => setOpen(true)}>Take the tour</Button>
        </Grid>
      </Grid.Container>
      <Tour
        open={open}
        onClose={() => setOpen(false)}
        steps={[
          { target: '#tour-search', title: 'Find an invoice', content: 'Type a name or a number and the list narrows as you write.' },
          { target: '#tour-filter', title: 'Narrow the list', content: 'Filter by status, date or amount.' },
          { target: '#tour-export', title: 'Take it with you', content: 'Export the invoices you see as a CSV file.' }
        ]}
      />
    </>
  )
}
`}
/>

<Playground
  title="Controlled and without a target"
  desc="`current` and `onCurrentChange` keep the step in your state, and `onFinish` runs when the last one is done, for example to remember that the tour was seen. A step without a `target`, like a welcome, is centered."
  scope={{ Tour, Button, Grid, Text }}
  code={`
() => {
  const [open, setOpen] = React.useState(false)
  const [current, setCurrent] = React.useState(0)
  const [seen, setSeen] = React.useState(false)
  return (
    <>
      <Grid.Container gap={2} alignItems="center">
        <Grid>
          <Button id="tour-start" auto type="primary" onClick={() => { setCurrent(0); setOpen(true) }}>
            Start
          </Button>
        </Grid>
        <Grid>
          <Text small type="secondary">
            {seen ? 'Tour done.' : 'Step ' + (current + 1) + ' of 2.'}
          </Text>
        </Grid>
      </Grid.Container>
      <Tour
        open={open}
        current={current}
        onCurrentChange={setCurrent}
        onFinish={() => setSeen(true)}
        onClose={() => setOpen(false)}
        steps={[
          { title: 'Welcome', content: 'A short walk through the page. It takes a minute.' },
          { target: '#tour-start', title: 'Start again', content: 'You can come back to the tour from this button.' }
        ]}
      />
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/components/tour.mdx">
<Attributes.Title>Tour.Props</Attributes.Title>

| Attribute            | Description                                                   | Type                                       | Accepted values | Default |
| -------------------- | ------------------------------------------------------------- | ------------------------------------------ | --------------- | ------- |
| **steps**            | the steps of the tour                                         | [TourStep](#tourstep)`[]`                  | -               | -       |
| **open**             | shows the tour                                                | `boolean`                                  | -               | -       |
| **onClose**          | called on Skip, on Escape and when the last step is done      | `() => void`                               | -               | -       |
| **current**          | the step in view, to control it                               | `number`                                   | -               | -       |
| **initialCurrent**   | the step on the first render                                  | `number`                                   | -               | `0`     |
| **onCurrentChange**  | called with the new step                                      | `(index: number) => void`                  | -               | -       |
| **onFinish**         | called when the last step is done, before `onClose`           | `() => void`                               | -               | -       |
| **previousLabel**    | name of the button to go back                                 | `string`                                   | -               | `Back`  |
| **nextLabel**        | name of the button to go forward                              | `string`                                   | -               | `Next`  |
| **finishLabel**      | name of the button of the last step                           | `string`                                   | -               | `Done`  |
| **skipLabel**        | name of the button that closes the tour                       | `string`                                   | -               | `Skip`  |
| **stepLabel**        | text with the position of the step                            | `(index: number, count: number) => string` | -               | `1 of 3` |
| **spotlightPadding** | space between the target and the highlight, in px             | `number`                                   | -               | `6`     |
| ...                  | native props, passed to the root `div`                        | `HTMLAttributes`                           | `'id', ...`     | -       |

<Attributes.Title>TourStep</Attributes.Title>

| Attribute   | Description                                                                               | Type                                              | Accepted values | Default |
| ----------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------- | --------------- | ------- |
| **title**   | name of the step                                                                          | `ReactNode`                                       | -               | -       |
| **content** | the explanation                                                                           | `ReactNode`                                       | -               | -       |
| **target**  | what the step points at: a CSS selector, an element, or a function that returns one       | `string` / `HTMLElement` / `() => HTMLElement`    | -               | -       |

<Attributes.Title>Behavior</Attributes.Title>

- • **Highlight**: the page is dimmed, and the target is left clear, with a little space around it. It follows the target when the page scrolls or the window is resized.
- • **Scrolling**: the target is scrolled into view when its step comes.
- • **Card**: it opens under the target, and above it when there is not room below. It stays inside the screen.
- • **No target**: without a `target`, or when it is not found, the card is centered and nothing is highlighted.
- • **Closing**: Skip and Escape call `onClose`, and so does the last step, after `onFinish`. The focus goes back to where it was.

<Attributes.Title>Ref</Attributes.Title>

The `ref` points at the root `div`, which covers the screen.

<Attributes.Title>Accessibility</Attributes.Title>

The card is a modal `dialog`, named by the title and described by the content, and it takes the focus on every step. Tab and Shift Tab cycle through its buttons, and Escape closes it. The position of the step is also a text, like "2 of 3". The page behind is dimmed but not hidden, so keep the text of the step complete enough to stand on its own.

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Tree, Grid, Text, Code } from 'core'

export const meta = {
  title: 'Tree',
  description:
    'A list of nodes that open to show their children, for files, categories or any nested data.',
  sidebar: 'components',
  group: 'Components',
  index: 63
}

## Tree

A list of nodes that open to show their children, for files, categories or any
nested data. Pass the nodes in `data`. Clicking a node selects it, and a node
with children also opens or closes.

<Playground
  desc="Each node has a unique `value` and a `label`, and `children` for the nodes inside it. Name the tree with `aria-label`."
  scope={{ Tree }}
  code={`
<Tree
  aria-label="Project files"
  initialExpanded={['src']}
  data={[
    {
      value: 'src',
      label: 'src',
      children: [
        {
          value: 'components',
          label: 'components',
          children: [
            { value: 'button', label: 'Button.tsx' },
            { value: 'input', label: 'Input.tsx' }
          ]
        },
        { value: 'index', label: 'index.ts' }
      ]
    },
    { value: 'package', label: 'package.json' },
    { value: 'readme', label: 'README.md' }
  ]}
/>
`}
/>

<Playground
  title="Controlled"
  desc="Use `value` and `onChange` for the selected node, and `expanded` and `onExpandedChange` for the open ones."
  scope={{ Tree, Grid, Text }}
  code={`
() => {
  const [value, setValue] = React.useState('index')
  const [expanded, setExpanded] = React.useState(['src'])
  return (
    <Grid.Container gap={2} direction="column">
      <Grid>
        <Tree
          aria-label="Project files"
          value={value}
          onChange={setValue}
          expanded={expanded}
          onExpandedChange={setExpanded}
          data={[
            {
              value: 'src',
              label: 'src',
              children: [
                { value: 'index', label: 'index.ts' },
                { value: 'app', label: 'App.tsx' }
              ]
            },
            { value: 'package', label: 'package.json' }
          ]}
        />
      </Grid>
      <Grid>
        <Text p>Selected: {value}. Open: {expanded.join(', ') || 'none'}.</Text>
      </Grid>
    </Grid.Container>
  )
}
`}
/>

<Playground
  title="Icons and disabled nodes"
  desc="`icon` shows any element before the label. A node with `disabled` is skipped by the keyboard and cannot be selected."
  scope={{ Tree }}
  code={`
() => {
  const icon = (path) => (
    <svg viewBox="0 0 24 24" width="1em" height="1em" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round">
      <path d={path} />
    </svg>
  )
  const folder = icon('M3 7a2 2 0 0 1 2-2h4l2 2h8a2 2 0 0 1 2 2v8a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z')
  const file = icon('M14 3H7a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V8zM14 3v5h5')
  return (
    <Tree
      aria-label="Documents"
      initialExpanded={['docs']}
      data={[
        {
          value: 'docs',
          label: 'Documents',
          icon: folder,
          children: [
            { value: 'contract', label: 'Contract.pdf', icon: file },
            { value: 'invoice', label: 'Invoice.pdf', icon: file },
            { value: 'draft', label: 'Draft.docx', icon: file, disabled: true }
          ]
        },
        { value: 'photos', label: 'Photos', icon: folder, children: [{ value: 'trip', label: 'Trip.png', icon: file }] }
      ]}
    />
  )
}
`}
/>

<Attributes edit="/content/docs/components/tree.mdx">
<Attributes.Title>Tree.Props</Attributes.Title>

| Attribute            | Description                                              | Type                                             | Accepted values           | Default |
| -------------------- | -------------------------------------------------------- | ------------------------------------------------ | ------------------------- | ------- |
| **data**             | the nodes of the first level                             | `TreeNodeData[]`                                 | -                         | -       |
| **value**            | selected node, to control it                             | `string` / `null`                                | -                         | -       |
| **initialValue**     | node selected on the first render                        | `string` / `null`                                | -                         | `null`  |
| **onChange**         | called with the `value` and the node that was selected   | <Code>(value: string, node: TreeNodeData) =&gt; void</Code> | -              | -       |
| **expanded**         | `value` of the open nodes, to control them               | `string[]`                                       | -                         | -       |
| **initialExpanded**  | `value` of the nodes open on the first render            | `string[]`                                       | -                         | `[]`    |
| **onExpandedChange** | called with the `value` of every open node               | `(expanded: string[]) => void`                   | -                         | -       |
| ...                  | native props, passed to the `ul`                         | `HTMLAttributes`                                 | `'aria-label', 'id', ...` | -       |

<Attributes.Title>TreeNodeData</Attributes.Title>

| Attribute    | Description                                          | Type             | Accepted values | Default |
| ------------ | ---------------------------------------------------- | ---------------- | --------------- | ------- |
| **value**    | identifies the node, unique in the whole tree        | `string`         | -               | -       |
| **label**    | content of the node                                  | `ReactNode`      | -               | -       |
| **icon**     | shown before the label                               | `ReactNode`      | -               | -       |
| **disabled** | the node cannot be selected and is skipped by the keys | `boolean`      | -               | `false` |
| **children** | the nodes inside this one                            | `TreeNodeData[]` | -               | -       |

<Attributes.Title>Keyboard</Attributes.Title>

- • **Up and Down** move the focus to the previous and the next node in view.
- • **Right** opens a closed node, and on an open one goes to its first child.
- • **Left** closes an open node, and on a closed one goes to its parent.
- • **Home and End** go to the first and the last node in view.
- • **Enter and Space** select the node, and a node with children also opens or closes.

<Attributes.Title>Ref</Attributes.Title>

The `ref` points at the `ul` of the tree.

<Attributes.Title>Accessibility</Attributes.Title>

The tree follows the ARIA tree pattern: `tree`, `treeitem` and `group`, with `aria-expanded` on the nodes that have children, `aria-selected`, `aria-level` and `aria-disabled`. Each node is named by its own label, not by the text of its children. Only one node is in the tab order, the selected one or the first, and the arrow keys move the focus between the others. Name the tree with `aria-label`.

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Button, Spacer, Text, useBodyScroll } from 'core'

export const meta = {
  title: 'useBodyScroll',
  description:
    'Disable scrolling behavior for body or any element, it is useful for displaying popup element or menus.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 1
}

## useBodyScroll

Disable scrolling behavior for body or any element, it is useful for displaying popup element or menus.

If the page's scrollbar is set to a user-defined `width` before scrolling is disabled, a `paddingRight` value will be added after disabling to adapt.

<Playground
  desc="Click button to disable scrolling."
  scope={{ Button, Spacer, Text, useBodyScroll }}
  code={`
() => {
  const [hidden, setHidden] = useBodyScroll()
  return (
    <>
      <Text small b type={hidden ? 'error' : 'default'}>{hidden ? 'Body disabled.' : 'Body can be scrolled.'}</Text>
      <Spacer h={.75} />
      <Button scale={0.5} type="success-light" auto onClick={() => setHidden(true)}>disable scroll</Button>
      <Button ml="20px" scale={0.5} type="secondary-light" auto onClick={() => setHidden(false)}>reset</Button>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-body-scroll.mdx">
<Attributes.Title>useBodyScroll</Attributes.Title>

```ts
type BodyScrollOptions = {
  delayReset: number  // resume scrolling after a delay, default is 0
}

const useBodyScroll = (
  elementRef?: RefObject<HTMLElement> | null,
  options?: BodyScrollOptions,
) => [boolean, Dispatch<SetStateAction<boolean>>]
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Layout, Playground, Attributes } from 'src/components'
import { Button, useTheme } from 'core'

export const meta = {
  title: 'useClasses',
  description:
    'Technically, this is not a hooks, it just uses the nomenclature of hooks as well.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 2
}

## useClasses

Technically, this is not a hooks, it just uses the nomenclature of hooks as well.
`useClasses` is used to mix strings, objects, expressions, etc. into class-names, and remove the extra space characters.
It is actually similar in function to [classnames](https://www.npmjs.com/package/classnames), but much more compact and lower of size.

The original purpose of creating an additional hooks instead of using a package from the community was to reduce the size of the package,
there are not a lot of complex class-names expressions to deal with in _Bolio UI_, just for regular space sign removal.

### Basic usage

Remove spaces from multiple characters：

```tsx
import { useClasses } from '@bolio-ui/core'

export default ({ className }) => {
  const myClass = 'button'

  // output -> "button "
  return <div className={`${myClass} ${className}`} />

  // output -> "button"
  return <div className={useClasses(myClass, className)} />
}
```

Add an expression based on class-names:

```tsx
export default ({ className }) => {
  const classes = useClasses('button', isHover ? 'hover' : 'base', className)

  // output -> "button hover"
  // output -> "button base"
  return <div className={classes} />
}
```

### Parse Object

For more complex scenarios, we can use hooks to parse an object and output a string:

```tsx
export default ({ active, disabled }) => {
  const classes = useClasses('button', {
    active,
    'button-disabled': disabled
  })

  // output -> "button active"
  // output -> "button active button-disabled"
  return <div className={classes} />
}
```

### Boundary Scenes

Any value that can be implicitly typed to false will be ignored:

```tsx
useClasses('') // output -> ""
useClasses(null) // output -> ""
useClasses('btn', undefined) // output -> "btn"
useClasses({ actived: null }) // output -> ""
useClasses(0) // output -> ""
useClasses(false, 'btn', '') // output -> "btn"
```

<Attributes edit="/content/docs/hooks/use-classes.mdx">
<Attributes.Title>useClasses</Attributes.Title>

```ts
type useClasses = (
  input: string | Object | null | undefined | boolean | number
) => string
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Card, Spacer, useClickAway } from 'core'

export const meta = {
  title: 'useClickAway',
  description: 'Detect if a click event happened outside an element.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 3
}

## useClickAway

Detect if a click event happened outside an element.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="Click outside the green card to trigger the callback."
  scope={{ useClickAway }}
  code={`
() => {
  const ref = React.useRef()
  const [count, setCount] = React.useState(0)
  useClickAway(ref, () => setCount(last => last + 1))
  return (
    <div ref={ref} style={{ background: 'green', display: 'flex' }}>
      <p style={{ fontSize: '2rem' }}>{count}</p>
    </div>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-click-away.mdx">
<Attributes.Title>useClickAway</Attributes.Title>

```ts
const useClickAway = (
  ref: MutableRefObject<HTMLElement | null>,
  handler: (event: MouseEvent) => void,
) => void
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { useClipboard, Link, Button, useToasts, Spacer } from 'core'

export const meta = {
  title: 'useClipboard',
  description: 'Copy string to clipboard.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 4
}

## useClipboard

Copy string to clipboard.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  scope={{ useClipboard, Button, useToasts }}
  code={`
() => {
  const { setToast } = useToasts()
  const { copy } = useClipboard()
  const handler = () => {
    copy('Hi, Bolio-UI')
    setToast({ text: 'Text copied.' })
  }
  return (
    <>
      <Button scale={0.5} auto onClick={handler}>Copy</Button>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-clipboard.mdx">
<Attributes.Title>useClipboard</Attributes.Title>

```ts
type UseClipboardOptions = {
  onError: Function
}

type CopyResult = {
  copy: (text: string) => void
}

const useClipboard = (options?: UseClipboardOptions) => CopyResult
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Button, Text, useCollapse } from 'core'

export const meta = {
  title: 'useCollapse',
  description: 'Animate the height of an element when it opens and closes.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 61
}

## useCollapse

Animate the height of an element when it opens and closes.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="Spread the style and onTransitionEnd on the element that grows and shrinks."
  scope={{ Button, Text, useCollapse }}
  code={`
() => {
  const [opened, setOpened] = React.useState(false)
  const { ref, style, onTransitionEnd } = useCollapse({ opened })
  return (
    <>
      <Button auto scale={0.6} onClick={() => setOpened(!opened)}>{opened ? 'Close' : 'Open'}</Button>
      <div ref={ref} style={style} onTransitionEnd={onTransitionEnd}>
        <Text>This content animates its height.</Text>
        <Text>It keeps the natural height when it is open.</Text>
      </div>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-collapse.mdx">
<Attributes.Title>useCollapse</Attributes.Title>

```ts
const useCollapse = <T extends HTMLElement = HTMLElement>(options: {
  opened: boolean
  duration?: number
}) => {
  ref: RefObject<T | null>
  style: CSSProperties
  onTransitionEnd: () => void
}
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Text, useColorScheme } from 'core'

export const meta = {
  title: 'useColorScheme',
  description: 'Detect the color scheme of the system, light or dark.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 14
}

## useColorScheme

Detect the color scheme of the system, light or dark.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="It follows the system, not the theme of the site."
  scope={{ Text, useColorScheme }}
  code={`
() => {
  const scheme = useColorScheme()
  return <Text>System scheme: {scheme}</Text>
}
`}
/>

<Attributes edit="/content/docs/hooks/use-color-scheme.mdx">
<Attributes.Title>useColorScheme</Attributes.Title>

```ts
const useColorScheme = () => 'light' | 'dark'
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Button, Text, useCounter } from 'core'

export const meta = {
  title: 'useCounter',
  description: 'Keep a number with increment, decrement, set and reset handlers, optionally clamped to a range.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 15
}

## useCounter

Keep a number with increment, decrement, set and reset handlers, optionally clamped to a range.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="The value stays between min and max."
  scope={{ Button, Text, useCounter }}
  code={`
() => {
  const [count, { increment, decrement, reset }] = useCounter(3, { min: 0, max: 10 })
  return (
    <>
      <Text h3>{count}</Text>
      <Button auto scale={0.6} onClick={decrement}>-1</Button>
      <Button auto scale={0.6} onClick={increment} style={{ marginLeft: 8 }}>+1</Button>
      <Button auto scale={0.6} onClick={reset} style={{ marginLeft: 8 }}>Reset</Button>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-counter.mdx">
<Attributes.Title>useCounter</Attributes.Title>

```ts
const useCounter = (
  initialValue?: number,
  options?: { min?: number; max?: number },
) => [
  number,
  {
    increment: () => void
    decrement: () => void
    set: (value: number) => void
    reset: () => void
  },
]
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Layout, Playground, Attributes } from 'src/components'
import { useCurrentState, Link, Button, Spacer } from 'core'

export const meta = {
  title: 'useCurrentState',
  description:
    'Get the latest value in functional component. By default, `state` in a React function component can only get the value at render time, not the latest.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 5
}

## useCurrentState

Get **the latest value** in functional component. By default, `state` in a React function component
can only get the value at render time, not the latest.

This is a small tool to get the latest value, It is very useful in async actions such as `setTimeout`.
if you like a bigger solution,
try <Link target="_blank" color href="https://reactjs.org/docs/hooks-reference.html#usereducer">useReducer</Link>.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  scope={{ useCurrentState, Button }}
  code={`
() => {
  const [value, setValue] = React.useState(0)
  const [value2, setValue2, value2Ref] = useCurrentState(0)
  const handler = () => {
    setValue(pre => pre + 1)
    setValue2(pre => pre + 1)
    const str = \`render state: \${value}, the latest value: \${value2Ref.current}\`
    alert(str)
  }
  return (
    <Button scale={0.5} auto onClick={handler}>Click to show</Button>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-current-state.mdx">
<Attributes.Title>useCurrentState</Attributes.Title>

```ts
type CurrentStateType<S> = [
  S,
  Dispatch<SetStateAction<S>>,
  MutableRefObject<S>,
]

const useCurrentState<S> = (
  initialState: S | () => S,
) => CurrentStateType<S>
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Button, Text, Spacer, useDebouncedCallback } from 'core'

export const meta = {
  title: 'useDebouncedCallback',
  description: 'Create a function that runs only after it stops being called for the given time.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 16
}

## useDebouncedCallback

Create a function that runs only after it stops being called for the given time.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="The callback runs once, 400ms after the last click."
  scope={{ Button, Text, Spacer, useDebouncedCallback }}
  code={`
() => {
  const [count, setCount] = React.useState(0)
  const [clicks, setClicks] = React.useState(0)
  const save = useDebouncedCallback((value) => setCount(value), 400)
  return (
    <>
      <Button auto scale={0.6} onClick={() => { setClicks(clicks + 1); save(clicks + 1) }}>Click</Button>
      <Spacer h={0.5} />
      <Text>Clicks: {clicks}, saved: {count}</Text>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-debounced-callback.mdx">
<Attributes.Title>useDebouncedCallback</Attributes.Title>

```ts
const useDebouncedCallback = <A extends unknown[]>(
  callback: (...args: A) => void,
  wait: number,
) => ((...args: A) => void) & { cancel: () => void }
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Text, Input, Spacer, useDebouncedState } from 'core'

export const meta = {
  title: 'useDebouncedState',
  description: 'Keep a state whose updates are applied only after the user stops changing it.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 62
}

## useDebouncedState

Keep a state whose updates are applied only after the user stops changing it.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="The value changes 500ms after the last keystroke."
  scope={{ Text, Input, Spacer, useDebouncedState }}
  code={`
() => {
  const [value, setValue] = useDebouncedState('', 500)
  return (
    <>
      <Input placeholder="Type something" onChange={(e) => setValue(e.target.value)} />
      <Spacer h={0.5} />
      <Text>Value: {value}</Text>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-debounced-state.mdx">
<Attributes.Title>useDebouncedState</Attributes.Title>

```ts
const useDebouncedState = <T>(
  initialValue: T,
  wait: number,
  options?: { leading?: boolean },
) => [T, (value: T) => void]
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Text, Input, Spacer, useDebouncedValue } from 'core'

export const meta = {
  title: 'useDebouncedValue',
  description: 'Delay a value until it stops changing for the given time.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 17
}

## useDebouncedValue

Delay a value until it stops changing for the given time.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="The debounced value follows the input 500ms after the last keystroke."
  scope={{ Text, Input, Spacer, useDebouncedValue }}
  code={`
() => {
  const [value, setValue] = React.useState('')
  const [debounced] = useDebouncedValue(value, 500)
  return (
    <>
      <Input placeholder="Type something" value={value} onChange={(e) => setValue(e.target.value)} />
      <Spacer h={0.5} />
      <Text>Debounced: {debounced}</Text>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-debounced-value.mdx">
<Attributes.Title>useDebouncedValue</Attributes.Title>

```ts
const useDebouncedValue = <T>(
  value: T,
  wait: number,
  options?: { leading?: boolean },
) => [T, () => void]
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Button, Text, useDidUpdate } from 'core'

export const meta = {
  title: 'useDidUpdate',
  description: 'Run an effect only when the dependencies change, not on the first render.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 18
}

## useDidUpdate

Run an effect only when the dependencies change, not on the first render.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="The counter of updates ignores the first render."
  scope={{ Button, Text, useDidUpdate }}
  code={`
() => {
  const [count, setCount] = React.useState(0)
  const [updates, setUpdates] = React.useState(0)
  useDidUpdate(() => setUpdates((u) => u + 1), [count])
  return (
    <>
      <Text>Count: {count}, updates: {updates}</Text>
      <Button auto scale={0.6} onClick={() => setCount(count + 1)}>Increment</Button>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-did-update.mdx">
<Attributes.Title>useDidUpdate</Attributes.Title>

```ts
const useDidUpdate = (
  fn: EffectCallback,
  dependencies?: DependencyList,
) => void
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Button, Modal, useDisclosure } from 'core'

export const meta = {
  title: 'useDisclosure',
  description: 'Control the open state of a modal, drawer or any other disclosure, with optional callbacks.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 19
}

## useDisclosure

Control the open state of a modal, drawer or any other disclosure, with optional callbacks.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="Open and close a modal from the handlers."
  scope={{ Button, Modal, useDisclosure }}
  code={`
() => {
  const [opened, { open, close }] = useDisclosure(false)
  return (
    <>
      <Button auto scale={0.6} onClick={open}>Open modal</Button>
      <Modal visible={opened} onClose={close}>
        <Modal.Title>Disclosure</Modal.Title>
        <Modal.Action passive onClick={close}>Close</Modal.Action>
      </Modal>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-disclosure.mdx">
<Attributes.Title>useDisclosure</Attributes.Title>

```ts
const useDisclosure = (
  initialState?: boolean,
  options?: { onOpen?: () => void; onClose?: () => void },
) => [
  boolean,
  { open: () => void; close: () => void; toggle: () => void },
]
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Input, useDocumentTitle } from 'core'

export const meta = {
  title: 'useDocumentTitle',
  description: 'Set the title of the page and update it when the value changes.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 20
}

## useDocumentTitle

Set the title of the page and update it when the value changes.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="The title of the tab follows the input."
  scope={{ Input, useDocumentTitle }}
  code={`
() => {
  const [title, setTitle] = React.useState('Bolio UI')
  useDocumentTitle(title)
  return <Input value={title} onChange={(e) => setTitle(e.target.value)} />
}
`}
/>

<Attributes edit="/content/docs/hooks/use-document-title.mdx">
<Attributes.Title>useDocumentTitle</Attributes.Title>

```ts
const useDocumentTitle = (title: string) => void
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Text, useDocumentVisibility } from 'core'

export const meta = {
  title: 'useDocumentVisibility',
  description: 'Detect when the tab is visible or hidden.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 21
}

## useDocumentVisibility

Detect when the tab is visible or hidden.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="Switch to another tab and back to see the value change."
  scope={{ Text, useDocumentVisibility }}
  code={`
() => {
  const visibility = useDocumentVisibility()
  return <Text>The tab is {visibility}</Text>
}
`}
/>

<Attributes edit="/content/docs/hooks/use-document-visibility.mdx">
<Attributes.Title>useDocumentVisibility</Attributes.Title>

```ts
const useDocumentVisibility = () => 'visible' | 'hidden'
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Button, Spacer, useDrag } from 'core'

export const meta = {
  title: 'useDrag',
  description: 'Drag an element with the pointer and read how far it moved.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 63
}

## useDrag

Drag an element with the pointer and read how far it moved.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="Drag the box, the position is kept between drags."
  scope={{ Button, Spacer, useDrag }}
  code={`
() => {
  const { ref, position, dragging, reset } = useDrag()
  return (
    <>
      <div ref={ref} style={{ width: 120, padding: 16, border: '1px solid currentColor', cursor: dragging ? 'grabbing' : 'grab', touchAction: 'none', userSelect: 'none', transform: 'translate(' + position.x + 'px, ' + position.y + 'px)' }}>Drag me</div>
      <Spacer h={0.5} />
      <Button auto scale={0.6} onClick={reset}>Reset</Button>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-drag.mdx">
<Attributes.Title>useDrag</Attributes.Title>

```ts
const useDrag = <T extends HTMLElement = HTMLElement>() => {
  ref: RefObject<T | null>
  dragging: boolean
  position: { x: number; y: number }
  reset: () => void
}
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Text, useElementSize } from 'core'

export const meta = {
  title: 'useElementSize',
  description: 'Get the width and height of an element and keep them updated.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 22
}

## useElementSize

Get the width and height of an element and keep them updated.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="Resize the textarea to see its size change."
  scope={{ Text, useElementSize }}
  code={`
() => {
  const { ref, width, height } = useElementSize()
  return (
    <>
      <Text>{Math.round(width)} x {Math.round(height)}</Text>
      <textarea ref={ref} style={{ resize: 'both', width: 240, height: 80 }} />
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-element-size.mdx">
<Attributes.Title>useElementSize</Attributes.Title>

```ts
const useElementSize = <T extends HTMLElement = HTMLElement>() => {
  ref: RefObject<T | null>
  width: number
  height: number
}
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Button, useEventListener } from 'core'

export const meta = {
  title: 'useEventListener',
  description: 'Attach an event listener to an element and remove it when the component unmounts.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 23
}

## useEventListener

Attach an event listener to an element and remove it when the component unmounts.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="Count the clicks of an element without writing the effect."
  scope={{ Button, useEventListener }}
  code={`
() => {
  const [count, setCount] = React.useState(0)
  const ref = useEventListener('click', () => setCount((c) => c + 1))
  return <Button ref={ref} auto scale={0.6}>Clicked {count} times</Button>
}
`}
/>

<Attributes edit="/content/docs/hooks/use-event-listener.mdx">
<Attributes.Title>useEventListener</Attributes.Title>

```ts
const useEventListener = <
  K extends keyof HTMLElementEventMap,
  T extends HTMLElement = HTMLElement,
>(
  type: K,
  listener: (event: HTMLElementEventMap[K]) => void,
  options?: boolean | AddEventListenerOptions,
) => RefObject<T | null>
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Button, Text, useEyeDropper } from 'core'

export const meta = {
  title: 'useEyeDropper',
  description: 'Pick a color from anywhere on the screen with the EyeDropper API.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 64
}

## useEyeDropper

Pick a color from anywhere on the screen with the EyeDropper API.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="It works in browsers that support the EyeDropper API."
  scope={{ Button, Text, useEyeDropper }}
  code={`
() => {
  const { supported, open } = useEyeDropper()
  const [color, setColor] = React.useState('')
  const pick = async () => {
    try {
      const result = await open()
      if (result) setColor(result.sRGBHex)
    } catch {
      // the user closed the picker
    }
  }
  return (
    <>
      <Button auto scale={0.6} disabled={!supported} onClick={pick}>Pick a color</Button>
      <Text>{supported ? color || 'No color yet' : 'EyeDropper is not supported'}</Text>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-eye-dropper.mdx">
<Attributes.Title>useEyeDropper</Attributes.Title>

```ts
const useEyeDropper = () => {
  supported: boolean
  open: (options?: {
    signal?: AbortSignal
  }) => Promise<{ sRGBHex: string } | undefined>
}
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Button, useFavicon } from 'core'

export const meta = {
  title: 'useFavicon',
  description: 'Set the favicon of the page and update it when the value changes.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 65
}

## useFavicon

Set the favicon of the page and update it when the value changes.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="The icon of the tab follows the choice."
  scope={{ Button, useFavicon }}
  code={`
() => {
  const [url, setUrl] = React.useState('')
  const red = 'data:image/svg+xml,' + encodeURIComponent('<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 10 10"><circle cx="5" cy="5" r="5" fill="red"/></svg>')
  useFavicon(url)
  return <Button auto scale={0.6} onClick={() => setUrl(red)}>Use a red icon</Button>
}
`}
/>

<Attributes edit="/content/docs/hooks/use-favicon.mdx">
<Attributes.Title>useFavicon</Attributes.Title>

```ts
const useFavicon = (url: string) => void
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Button, Text, useFetch } from 'core'

export const meta = {
  title: 'useFetch',
  description: 'Request data with fetch and get the loading state, the error and a way to refetch or abort.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 66
}

## useFetch

Request data with fetch and get the loading state, the error and a way to refetch or abort.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="Load a post when you click, with the loading state handled by the hook."
  scope={{ Button, Text, useFetch }}
  code={`
() => {
  const { data, loading, error, refetch } = useFetch('https://jsonplaceholder.typicode.com/posts/1', { autoInvoke: false })
  return (
    <>
      <Button auto scale={0.6} loading={loading} onClick={refetch}>Load post</Button>
      <Text>{error ? error.message : data ? data.title : 'Nothing loaded yet'}</Text>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-fetch.mdx">
<Attributes.Title>useFetch</Attributes.Title>

```ts
const useFetch = <T = unknown>(
  url: string,
  options?: RequestInit & { autoInvoke?: boolean },
) => {
  data: T | null
  loading: boolean
  error: Error | null
  refetch: () => Promise<T | null>
  abort: () => void
}
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Button, Text, useFileDialog } from 'core'

export const meta = {
  title: 'useFileDialog',
  description: 'Open the file dialog of the browser from any element and get the chosen files.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 67
}

## useFileDialog

Open the file dialog of the browser from any element and get the chosen files.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="Choose images and list their names."
  scope={{ Button, Text, useFileDialog }}
  code={`
() => {
  const { files, open, reset } = useFileDialog({ multiple: true, accept: 'image/*' })
  return (
    <>
      <Button auto scale={0.6} onClick={open}>Choose files</Button>
      <Button auto scale={0.6} onClick={reset} style={{ marginLeft: 8 }}>Reset</Button>
      <Text>{files && files.length ? Array.from(files).map((file) => file.name).join(', ') : 'No files'}</Text>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-file-dialog.mdx">
<Attributes.Title>useFileDialog</Attributes.Title>

```ts
const useFileDialog = (options?: {
  multiple?: boolean
  accept?: string
  capture?: string
  onChange?: (files: FileList | null) => void
}) => {
  files: FileList | null
  open: () => void
  reset: () => void
}
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, useFloatingWindow } from 'core'

export const meta = {
  title: 'useFloatingWindow',
  description: 'Build a floating window that the user drags by a handle and that stays inside the viewport.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 68
}

## useFloatingWindow

Build a floating window that the user drags by a handle and that stays inside the viewport.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="Drag the window by its title, it stays inside the viewport."
  scope={{ useFloatingWindow }}
  code={`
() => {
  const { ref, handleRef, style } = useFloatingWindow({ initialPosition: { x: 24, y: 120 } })
  return (
    <div ref={ref} style={{ ...style, zIndex: 100, width: 200, border: '1px solid currentColor', background: 'Canvas' }}>
      <div ref={handleRef} style={{ padding: 8, cursor: 'move', touchAction: 'none', borderBottom: '1px solid currentColor' }}>Drag here</div>
      <div style={{ padding: 8 }}>Floating content</div>
    </div>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-floating-window.mdx">
<Attributes.Title>useFloatingWindow</Attributes.Title>

```ts
const useFloatingWindow = <
  T extends HTMLElement = HTMLElement,
  H extends HTMLElement = HTMLElement,
>(options?: { initialPosition?: { x: number; y: number } }) => {
  ref: RefObject<T | null>
  handleRef: RefObject<H | null>
  style: CSSProperties
  dragging: boolean
}
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Button, useFocusReturn } from 'core'

export const meta = {
  title: 'useFocusReturn',
  description: 'Return the focus to the element that had it before something opened, such as a modal.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 69
}

## useFocusReturn

Return the focus to the element that had it before something opened, such as a modal.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="Close the box and the focus goes back to the button that opened it."
  scope={{ Button, useFocusReturn }}
  code={`
() => {
  const [opened, setOpened] = React.useState(false)
  useFocusReturn({ opened })
  return (
    <>
      <Button auto scale={0.6} onClick={() => setOpened(true)}>Open</Button>
      {opened && (
        <div style={{ marginTop: 8 }}>
          <Button auto scale={0.6} autoFocus onClick={() => setOpened(false)}>Close and return focus</Button>
        </div>
      )}
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-focus-return.mdx">
<Attributes.Title>useFocusReturn</Attributes.Title>

```ts
const useFocusReturn = (options: {
  opened: boolean
  shouldReturnFocus?: boolean
}) => () => void
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Button, Input, Spacer, useFocusTrap } from 'core'

export const meta = {
  title: 'useFocusTrap',
  description: 'Keep the focus inside an element while it is active, cycling with Tab.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 70
}

## useFocusTrap

Keep the focus inside an element while it is active, cycling with Tab.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="Press Tab inside the box, the focus never leaves it."
  scope={{ Button, Input, Spacer, useFocusTrap }}
  code={`
() => {
  const [active, setActive] = React.useState(false)
  const ref = useFocusTrap(active)
  return (
    <>
      <Button auto scale={0.6} onClick={() => setActive(!active)}>{active ? 'Release focus' : 'Trap focus'}</Button>
      <div ref={ref} style={{ marginTop: 8, padding: 16, border: '1px dashed currentColor' }}>
        <Input placeholder="First" />
        <Spacer h={0.5} />
        <Input placeholder="Second" />
      </div>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-focus-trap.mdx">
<Attributes.Title>useFocusTrap</Attributes.Title>

```ts
const useFocusTrap = <T extends HTMLElement = HTMLElement>(
  active?: boolean,
) => RefObject<T | null>
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Input, Spacer, useFocusWithin } from 'core'

export const meta = {
  title: 'useFocusWithin',
  description: 'Detect when the focus is inside an element or any of its children.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 24
}

## useFocusWithin

Detect when the focus is inside an element or any of its children.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="The border changes while any input inside has the focus."
  scope={{ Input, Spacer, useFocusWithin }}
  code={`
() => {
  const { ref, focused } = useFocusWithin()
  return (
    <div ref={ref} style={{ padding: 16, border: focused ? '2px solid currentColor' : '2px dashed currentColor' }}>
      <Input placeholder="First" />
      <Spacer h={0.5} />
      <Input placeholder="Second" />
    </div>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-focus-within.mdx">
<Attributes.Title>useFocusWithin</Attributes.Title>

```ts
const useFocusWithin = <T extends HTMLElement = HTMLElement>(options?: {
  onFocus?: (event: FocusEvent) => void
  onBlur?: (event: FocusEvent) => void
}) => {
  ref: RefObject<T | null>
  focused: boolean
}
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Button, Text, useForceUpdate } from 'core'

export const meta = {
  title: 'useForceUpdate',
  description: 'Get a function that renders the component again.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 25
}

## useForceUpdate

Get a function that renders the component again.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="The time changes on every render."
  scope={{ Button, Text, useForceUpdate }}
  code={`
() => {
  const forceUpdate = useForceUpdate()
  return (
    <>
      <Text>{new Date().toLocaleTimeString()}</Text>
      <Button auto scale={0.6} onClick={forceUpdate}>Render again</Button>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-force-update.mdx">
<Attributes.Title>useForceUpdate</Attributes.Title>

```ts
const useForceUpdate = () => () => void
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Button, useFullscreen } from 'core'

export const meta = {
  title: 'useFullscreen',
  description: 'Put an element, or the whole page, in fullscreen.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 26
}

## useFullscreen

Put an element, or the whole page, in fullscreen.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="Without a ref the whole page goes fullscreen."
  scope={{ Button, useFullscreen }}
  code={`
() => {
  const { ref, toggle, fullscreen } = useFullscreen()
  return (
    <div ref={ref} style={{ padding: 24 }}>
      <Button auto scale={0.6} onClick={toggle}>{fullscreen ? 'Exit fullscreen' : 'Enter fullscreen'}</Button>
    </div>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-fullscreen.mdx">
<Attributes.Title>useFullscreen</Attributes.Title>

```ts
const useFullscreen = <T extends HTMLElement = HTMLElement>() => {
  ref: RefObject<T | null>
  fullscreen: boolean
  enter: () => Promise<void>
  exit: () => Promise<void>
  toggle: () => Promise<void>
}
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Button, Text, useHash } from 'core'

export const meta = {
  title: 'useHash',
  description: 'Read and set the hash of the URL and keep it updated.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 27
}

## useHash

Read and set the hash of the URL and keep it updated.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="Change the hash and the value follows."
  scope={{ Button, Text, useHash }}
  code={`
() => {
  const [hash, setHash] = useHash()
  return (
    <>
      <Text>Hash: {hash || 'empty'}</Text>
      <Button auto scale={0.6} onClick={() => setHash('example')}>Set #example</Button>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-hash.mdx">
<Attributes.Title>useHash</Attributes.Title>

```ts
const useHash = () => [string, (value: string) => void]
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Text, useHeadroom } from 'core'

export const meta = {
  title: 'useHeadroom',
  description: 'Know when a fixed header should show or hide, based on the scroll direction.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 71
}

## useHeadroom

Know when a fixed header should show or hide, based on the scroll direction.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="Scroll the page down to hide the label and up to show it."
  scope={{ Text, useHeadroom }}
  code={`
() => {
  const pinned = useHeadroom({ fixedAt: 120 })
  return <Text>{pinned ? 'Header pinned' : 'Header hidden'}</Text>
}
`}
/>

<Attributes edit="/content/docs/hooks/use-headroom.mdx">
<Attributes.Title>useHeadroom</Attributes.Title>

```ts
const useHeadroom = (options?: {
  fixedAt?: number
  onPin?: () => void
  onFix?: () => void
  onRelease?: () => void
}) => boolean
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Text, useHover } from 'core'

export const meta = {
  title: 'useHover',
  description: 'Detect when the pointer is over an element.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 28
}

## useHover

Detect when the pointer is over an element.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="The text changes while the pointer is over the box."
  scope={{ Text, useHover }}
  code={`
() => {
  const { hovered, ref } = useHover()
  return (
    <div ref={ref} style={{ padding: 24, border: '1px dashed currentColor' }}>
      <Text>{hovered ? 'Hovered' : 'Hover me'}</Text>
    </div>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-hover.mdx">
<Attributes.Title>useHover</Attributes.Title>

```ts
const useHover = <T extends HTMLElement = HTMLElement>() => {
  hovered: boolean
  ref: RefObject<T | null>
}
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Text, useIdle } from 'core'

export const meta = {
  title: 'useIdle',
  description: 'Detect when the user has not interacted with the page for a while.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 29
}

## useIdle

Detect when the user has not interacted with the page for a while.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="Stay still for three seconds."
  scope={{ Text, useIdle }}
  code={`
() => {
  const idle = useIdle(3000, { initialState: false })
  return <Text>{idle ? 'Idle' : 'Active'}</Text>
}
`}
/>

<Attributes edit="/content/docs/hooks/use-idle.mdx">
<Attributes.Title>useIdle</Attributes.Title>

```ts
const useIdle = (
  timeout: number,
  options?: { events?: string[]; initialState?: boolean },
) => boolean
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Text, useInViewport } from 'core'

export const meta = {
  title: 'useInViewport',
  description: 'Detect whether an element is visible in the viewport.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 33
}

## useInViewport

Detect whether an element is visible in the viewport.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="The label follows the visibility of the box."
  scope={{ Text, useInViewport }}
  code={`
() => {
  const { ref, inViewport } = useInViewport()
  return (
    <>
      <Text>{inViewport ? 'Visible' : 'Out of the viewport'}</Text>
      <div ref={ref} style={{ padding: 24, border: '1px dashed currentColor' }}>Observed</div>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-in-viewport.mdx">
<Attributes.Title>useInViewport</Attributes.Title>

```ts
const useInViewport = <T extends HTMLElement = HTMLElement>() => {
  ref: (element: T | null) => void
  inViewport: boolean
}
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Button, Input, Spacer, useInputState } from 'core'

export const meta = {
  title: 'useInputState',
  description: 'Keep the value of an input in state, accepting the change event or a value.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 30
}

## useInputState

Keep the value of an input in state, accepting the change event or a value.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="Pass the handler straight to onChange, or call it with a value."
  scope={{ Button, Input, Spacer, useInputState }}
  code={`
() => {
  const [value, setValue] = useInputState('')
  return (
    <>
      <Input placeholder="Type something" value={value} onChange={setValue} />
      <Spacer h={0.5} />
      <Button auto scale={0.6} onClick={() => setValue('')}>Clear</Button>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-input-state.mdx">
<Attributes.Title>useInputState</Attributes.Title>

```ts
const useInputState = <T>(initialValue: T) => [
  T,
  (value: T | ChangeEvent<HTMLInputElement | HTMLTextAreaElement>) => void,
]
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { useInput, Input, Button, Spacer } from 'core'

export const meta = {
  title: 'useInput',
  description:
    'Provides automatic binding for component, which can reduce the amount of repetitive code and improve the development experience.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 6
}

## useInput

`useInput` provides automatic binding for component [Input](/docs/components/input), which can reduce the amount of repetitive code and improve the development experience.
Using this hooks behaves the same as if you had added `React.useState` manually.

<Playground
  desc="Use hooks to capture changes."
  scope={{ Input, useInput, Button, Spacer }}
  code={`
() => {
  const { state, setState, reset, bindings } = useInput('Bolio UI')
  React.useEffect(() => console.log(state), [state])
  return (
    <>
      <Input {...bindings} />
      <Spacer h={.5} />
      <Button auto type="secondary" scale={1/2} onClick={() => setState(Math.random().toString(32))}>set value</Button>
      <Button auto scale={1/2} ml="20px" onClick={() => reset()}>reset value</Button>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-input.mdx">
<Attributes.Title>useInput</Attributes.Title>

```ts
type useInput = (initialValue: string) => {
  state: string
  setState: Dispatch<SetStateAction<string>>
  currentRef: MutableRefObject<string>
  reset: () => void
  bindings: {
    value: string
    onChange: (event: React.ChangeEvent<HTMLInputElement>) => void
  }
}
```

<Attributes.Title>KeyboardOptions</Attributes.Title>

| Option         | Description                                        | Type         |
| -------------- | -------------------------------------------------- | ------------ |
| **state**      | the value of the Input                             | `string`     |
| **setState**   | same as React.setState                             | -            |
| **currentRef** | the current value of Input                         | `string`     |
| **reset**      | reset the value of Input                           | `() => void` |
| **bindings**   | auto-binding objects conforming to the Input props | -            |

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Text, useIntersection } from 'core'

export const meta = {
  title: 'useIntersection',
  description: 'Observe how much of an element is visible with an IntersectionObserver.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 31
}

## useIntersection

Observe how much of an element is visible with an IntersectionObserver.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="Scroll the page to change how much of the box is visible."
  scope={{ Text, useIntersection }}
  code={`
() => {
  const { ref, entry } = useIntersection({ threshold: [0, 0.5, 1] })
  return (
    <>
      <Text>Visible: {Math.round((entry?.intersectionRatio || 0) * 100)}%</Text>
      <div ref={ref} style={{ padding: 24, border: '1px dashed currentColor' }}>Observed</div>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-intersection.mdx">
<Attributes.Title>useIntersection</Attributes.Title>

```ts
const useIntersection = <T extends HTMLElement = HTMLElement>(
  options?: IntersectionObserverInit,
) => {
  ref: (element: T | null) => void
  entry: IntersectionObserverEntry | null
}
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Button, Text, useInterval } from 'core'

export const meta = {
  title: 'useInterval',
  description: 'Run a function on an interval that you can start and stop.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 32
}

## useInterval

Run a function on an interval that you can start and stop.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="A counter that ticks every second until you stop it."
  scope={{ Button, Text, useInterval }}
  code={`
() => {
  const [seconds, setSeconds] = React.useState(0)
  const interval = useInterval(() => setSeconds((s) => s + 1), 1000)
  return (
    <>
      <Text h3>{seconds}</Text>
      <Button auto scale={0.6} onClick={interval.toggle}>{interval.active ? 'Stop' : 'Start'}</Button>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-interval.mdx">
<Attributes.Title>useInterval</Attributes.Title>

```ts
const useInterval = (
  fn: () => void,
  interval: number,
  options?: { autoInvoke?: boolean },
) => {
  start: () => void
  stop: () => void
  toggle: () => void
  active: boolean
}
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Button, Text, useIsFirstRender } from 'core'

export const meta = {
  title: 'useIsFirstRender',
  description: 'Know whether the component is rendering for the first time.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 34
}

## useIsFirstRender

Know whether the component is rendering for the first time.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="It is true only on the first render."
  scope={{ Button, Text, useIsFirstRender }}
  code={`
() => {
  const first = useIsFirstRender()
  const [, setCount] = React.useState(0)
  return (
    <>
      <Text>First render: {String(first)}</Text>
      <Button auto scale={0.6} onClick={() => setCount((c) => c + 1)}>Render again</Button>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-is-first-render.mdx">
<Attributes.Title>useIsFirstRender</Attributes.Title>

```ts
const useIsFirstRender = () => boolean
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Text, useIsomorphicEffect } from 'core'

export const meta = {
  title: 'useIsomorphicEffect',
  description: 'Use useLayoutEffect in the browser and useEffect on the server, without the warning.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 35
}

## useIsomorphicEffect

Use useLayoutEffect in the browser and useEffect on the server, without the warning.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="Measure an element before the browser paints."
  scope={{ Text, useIsomorphicEffect }}
  code={`
() => {
  const ref = React.useRef(null)
  const [width, setWidth] = React.useState(0)
  useIsomorphicEffect(() => setWidth(ref.current.offsetWidth), [])
  return <div ref={ref}><Text>Width: {width}px</Text></div>
}
`}
/>

<Attributes edit="/content/docs/hooks/use-isomorphic-effect.mdx">
<Attributes.Title>useIsomorphicEffect</Attributes.Title>

```ts
const useIsomorphicEffect: typeof useEffect
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { useKeyboard, KeyCode, KeyMod, Keyboard, Input, Link } from 'core'

export const meta = {
  title: 'useKeyboard',
  description: 'React hooks for listen to multiple keyboard events.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 7
}

## useKeyboard

React hooks for listen to multiple keyboard events.

<Playground
  desc="Global keyboard events."
  scope={{ useKeyboard, KeyCode, KeyMod, Keyboard }}
  code={`
() => {
  useKeyboard(
    () => alert('save success!'),
    [KeyCode.KEY_S, KeyMod.CtrlCmd]
  )
  return <div>Press <Keyboard command scale={0.5}>S</Keyboard> to save.</div>
}
`}
/>

<Playground
  title="Element Event"
  desc="Keyboard events listening on elements."
  scope={{ useKeyboard, KeyCode, KeyMod, Keyboard, Input }}
  code={`
() => {
  const { bindings } = useKeyboard(
    () => alert('A is not allowed'),
    [KeyCode.KEY_A],
    { disableGlobalEvent: true },
  )
  return (
  <div>
    <p>Keyboard events are triggered only when the element is activated.</p>
    <Input {...bindings} placeholder="Press A" />
  </div>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-keyboard.mdx">
<Attributes.Title>useKeyboard</Attributes.Title>

```ts
type KeyboardOptions = {
  disableGlobalEvent: boolean,
  stopPropagation: boolean
  preventDefault: boolean
  capture: boolean
  event: 'keydown' | 'keypress' | 'keyup'
}

const useKeyboard = (
  handler: (event: React.KeyboardEvent) => void,
  keyBindings: Array<number> | number,
  options?: KeyboardOptions,
) => void
```

<Attributes.Title>KeyboardOptions</Attributes.Title>

| Option                 | Description                         | Type      | Accepted values                  | Default   |
| ---------------------- | ----------------------------------- | --------- | -------------------------------- | --------- |
| **disableGlobalEvent** | disable global events from document | `boolean` | -                                | `false`   |
| **stopPropagation**    | stop event Propagation              | `boolean` | -                                | `false`   |
| **preventDefault**     | block the default behavior of event | `boolean` | -                                | `true`    |
| **capture**            | set event type to "capture"         | `boolean` | -                                | `false`   |
| **event**              | keyboard event type                 | `string`  | `'keydown', 'keypress', 'keyup'` | `keydown` |

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Button, Text, useListState } from 'core'

export const meta = {
  title: 'useListState',
  description: 'Keep an array in state with handlers to append, insert, remove, reorder and filter items.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 36
}

## useListState

Keep an array in state with handlers to append, insert, remove, reorder and filter items.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="Add items to the end of the list and remove them by index."
  scope={{ Button, Link, Text, useListState }}
  code={`
() => {
  const [items, handlers] = useListState(['Apple', 'Banana'])
  return (
    <>
      {items.map((item, index) => (
        <Text key={item + index}>
          {item}{' '}
          <Link color href="#" onClick={(e) => { e.preventDefault(); handlers.remove(index) }}>remove</Link>
        </Text>
      ))}
      <Button auto scale={0.6} onClick={() => handlers.append('Item ' + (items.length + 1))}>Add item</Button>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-list-state.mdx">
<Attributes.Title>useListState</Attributes.Title>

```ts
const useListState = <T>(initialValue?: T[]) => [
  T[],
  {
    setState: (items: T[]) => void
    append: (...items: T[]) => void
    prepend: (...items: T[]) => void
    insert: (index: number, ...items: T[]) => void
    remove: (...indices: number[]) => void
    reorder: (move: { from: number; to: number }) => void
    setItem: (index: number, item: T) => void
    filter: (fn: (item: T, index: number) => boolean) => void
    apply: (fn: (item: T, index: number) => T) => void
  },
]
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Button, Input, Spacer, useLocalStorage } from 'core'

export const meta = {
  title: 'useLocalStorage',
  description: 'Keep a value in localStorage, in sync across components and tabs, safe for server rendering.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 37
}

## useLocalStorage

Keep a value in localStorage, in sync across components and tabs, safe for server rendering.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="The value survives a page reload."
  scope={{ Button, Input, Spacer, useLocalStorage }}
  code={`
() => {
  const [name, setName, removeName] = useLocalStorage({ key: 'bolio-ui-docs-name', defaultValue: '' })
  return (
    <>
      <Input placeholder="Your name" value={name} onChange={(e) => setName(e.target.value)} />
      <Spacer h={0.5} />
      <Button auto scale={0.6} onClick={removeName}>Clear</Button>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-local-storage.mdx">
<Attributes.Title>useLocalStorage</Attributes.Title>

```ts
const useLocalStorage = <T>(options: {
  key: string
  defaultValue: T
}) => [
  T,
  (value: T | ((current: T) => T)) => void,
  () => void,
]
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Button, useLogger } from 'core'

export const meta = {
  title: 'useLogger',
  description: 'Log the mount, the updates and the unmount of a component with its props, for debugging.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 72
}

## useLogger

Log the mount, the updates and the unmount of a component with its props, for debugging.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="Open the console to see the logs."
  scope={{ Button, useLogger }}
  code={`
() => {
  const [count, setCount] = React.useState(0)
  useLogger('Counter', [count])
  return <Button auto scale={0.6} onClick={() => setCount(count + 1)}>Count {count}</Button>
}
`}
/>

<Attributes edit="/content/docs/hooks/use-logger.mdx">
<Attributes.Title>useLogger</Attributes.Title>

```ts
const useLogger = (componentName: string, props: unknown[]) => void
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Button, useLongPress } from 'core'

export const meta = {
  title: 'useLongPress',
  description: 'Run a callback when an element is pressed and held, with mouse or touch.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 38
}

## useLongPress

Run a callback when an element is pressed and held, with mouse or touch.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="Hold the button for one second."
  scope={{ Button, useLongPress }}
  code={`
() => {
  const [count, setCount] = React.useState(0)
  const handlers = useLongPress(() => setCount((c) => c + 1), { threshold: 1000 })
  return <Button auto scale={0.6} {...handlers}>Held {count} times</Button>
}
`}
/>

<Attributes edit="/content/docs/hooks/use-long-press.mdx">
<Attributes.Title>useLongPress</Attributes.Title>

```ts
const useLongPress = (
  onLongPress: () => void,
  options?: { threshold?: number },
) => {
  onMouseDown: () => void
  onMouseUp: () => void
  onMouseLeave: () => void
  onTouchStart: () => void
  onTouchEnd: () => void
}
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Button, Text, useMap } from 'core'

export const meta = {
  title: 'useMap',
  description: 'Keep a Map in state that renders again when it changes.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 73
}

## useMap

Keep a Map in state that renders again when it changes.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="set, delete and clear render the component again."
  scope={{ Button, Text, useMap }}
  code={`
() => {
  const map = useMap([['a', 1]])
  return (
    <>
      <Text>{[...map].map(([key, value]) => key + '=' + value).join(', ') || 'empty'}</Text>
      <Button auto scale={0.6} onClick={() => map.set('k' + map.size, map.size)}>Add</Button>
      <Button auto scale={0.6} onClick={() => map.clear()} style={{ marginLeft: 8 }}>Clear</Button>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-map.mdx">
<Attributes.Title>useMap</Attributes.Title>

```ts
const useMap = <K, V>(
  initialState?: Iterable<readonly [K, V]>,
) => Map<K, V>
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Input, useMask } from 'core'

export const meta = {
  title: 'useMask',
  description: 'Format the value of an input with a mask, such as a phone number or a date.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 74
}

## useMask

Format the value of an input with a mask, such as a phone number or a date.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="# is a digit, A is a letter and * is any of them."
  scope={{ Input, useMask }}
  code={`
() => {
  const [phone, setPhone] = useMask({ mask: '(###) ###-####' })
  return <Input placeholder="(555) 123-4567" value={phone} onChange={setPhone} />
}
`}
/>

<Attributes edit="/content/docs/hooks/use-mask.mdx">
<Attributes.Title>useMask</Attributes.Title>

```ts
const useMask = (options: {
  mask: string
  initialValue?: string
}) => [
  string,
  (value: string | ChangeEvent<HTMLInputElement>) => void,
]
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, PlaygroundTitle, Attributes } from 'src/components'
import { useMediaQuery, Link, Code, Spacer } from 'core'

export const meta = {
  title: 'useMediaQuery',
  description:
    'CSS media query hooks, it is implemented through the `MediaQuery` API.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 8
}

## useMediaQuery

CSS media query hooks, it is implemented through the `MediaQuery` API.
If you just want to build the layout, try <Link color href="/docs/components/grid">Grid Component</Link>.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  scope={{ useMediaQuery, Code }}
  code={`
() => {
  const isXS = useMediaQuery('xs')
  const isSM = useMediaQuery('sm')
  const isMD = useMediaQuery('md')
  const isLG = useMediaQuery('lg')
  const isXL = useMediaQuery('xl')
  return (
    <>
      MediaQuery match: <Code>{isXS && 'xs'}{isSM && 'sm'}{isMD && 'md'}{isLG && 'lg'}{isXL && 'xl'}</Code>.
    </>
  )
}
`}
/>

<Playground
  title="Match Type"
  desc="You can choose to match up or down."
  scope={{ useMediaQuery, Code }}
  code={`
() => {
  const upMD = useMediaQuery('md', { match: 'up' })
  return (
    <>
      Current screen width <b>{upMD ? '>=' : '<='}</b> <Code>md</Code>.
    </>
  )
}
`}
/>

<PlaygroundTitle
  title="Custom Breakpoints"
  desc="Override the default breakpoints of the `@bolio-ui/core`."
/>

```tsx
const breakpoints: BolioUIThemesBreakpoints = {
  xs: { min: '0', max: '650px' },
  sm: { min: '650px', max: '900px' },
  md: { min: '900px', max: '1280px' },
  lg: { min: '1280px', max: '1920px' },
  xl: { min: '1920px', max: '10000px' }
}

const App = () => {
  const myTheme = Themes.createFromLight({
    type: 'myTheme',
    breakpoints
  })
  return (
    <BolioProvider themes={[myTheme]} themeType="myTheme">
      <CssBaseline />
      <AppComponent />
    </BolioProvider>
  )
}
```

<Attributes edit="/content/docs/hooks/use-media-query.mdx">
<Attributes.Title>useMediaQuery</Attributes.Title>

```ts
type ResponsiveBreakpoint = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'mobile'

type ResponsiveOptions = {
  match?: 'up' | 'down'
  ssrMatchMedia?: (query: string) => { matches: boolean }
}

const useMediaQuery = (
  breakpoint: ResponsiveBreakpoint,
  options?: ResponsiveOptions
) => boolean
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Button, Text, useMergedRef } from 'core'

export const meta = {
  title: 'useMergedRef',
  description: 'Merge several refs, callback or object, into one.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 39
}

## useMergedRef

Merge several refs, callback or object, into one.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="One element is read by two refs."
  scope={{ Button, Text, useMergedRef }}
  code={`
() => {
  const first = React.useRef(null)
  const second = React.useRef(null)
  const ref = useMergedRef(first, second)
  const [same, setSame] = React.useState('')
  return (
    <>
      <div ref={ref}>Merged</div>
      <Button auto scale={0.6} onClick={() => setSame(String(first.current === second.current))}>Compare</Button>
      <Text>Same element: {same}</Text>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-merged-ref.mdx">
<Attributes.Title>useMergedRef</Attributes.Title>

```ts
const useMergedRef = <T>(...refs: (Ref<T> | undefined)[]) =>
  (node: T | null) => void
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { useModal, Modal, Button } from 'core'

export const meta = {
  title: 'useModal',
  description:
    'Provides automatic binding for component, which can reduce the amount of repetitive code and improve the development experience.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 9
}

## useModal

`useModal` provides automatic binding for component [Modal](/docs/components/modal), which can reduce the amount of repetitive code and improve the development experience.
Using this hooks behaves the same as if you had added `React.useState` manually.

This hooks also supports use on [Select component](/docs/components/select 'Select Component').

<Playground
  desc="Use hooks to control `Modal`."
  scope={{ Modal, Button, useModal }}
  code={`
() => {
  const { visible, setVisible, bindings } = useModal()
  return (
    <>
      <Button auto onClick={() => setVisible(true)}>Show Modal</Button>
      <Modal {...bindings}>
        <Modal.Title>Modal</Modal.Title>
        <Modal.Subtitle>This is a modal</Modal.Subtitle>
        <Modal.Content>
          <p>Some content contained within the modal.</p>
        </Modal.Content>
        <Modal.Action passive onClick={() => setVisible(false)}>Cancel</Modal.Action>
        <Modal.Action>Submit</Modal.Action>
      </Modal>
    </>
  )
}`}
/>

<Attributes edit="/content/docs/hooks/use-modal.mdx" >
<Attributes.Title>useModal</Attributes.Title>

```ts
type useModal = (initialVisible: boolean) => {
  visible: boolean
  setVisible: Dispatch<SetStateAction<boolean>>
  setVisible: Dispatch<SetStateAction<boolean>>
  currentRef: MutableRefObject<boolean>
  bindings: {
    visible: boolean
    onClose: () => void
  }
}
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Text, useMounted } from 'core'

export const meta = {
  title: 'useMounted',
  description: 'Know whether the component has mounted in the browser.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 40
}

## useMounted

Know whether the component has mounted in the browser.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="It is false on the server and on the first render."
  scope={{ Text, useMounted }}
  code={`
() => {
  const mounted = useMounted()
  return <Text>{mounted ? 'Mounted' : 'Rendering'}</Text>
}
`}
/>

<Attributes edit="/content/docs/hooks/use-mounted.mdx">
<Attributes.Title>useMounted</Attributes.Title>

```ts
const useMounted = () => boolean
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Text, useMouse } from 'core'

export const meta = {
  title: 'useMouse',
  description: 'Track the position of the mouse, in the page or relative to an element.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 41
}

## useMouse

Track the position of the mouse, in the page or relative to an element.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="The position is relative to the box when the ref is used."
  scope={{ Text, useMouse }}
  code={`
() => {
  const { ref, x, y } = useMouse()
  return (
    <div ref={ref} style={{ padding: 24, border: '1px dashed currentColor' }}>
      <Text>{x}, {y}</Text>
    </div>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-mouse.mdx">
<Attributes.Title>useMouse</Attributes.Title>

```ts
const useMouse = <T extends HTMLElement = HTMLElement>() => {
  ref: RefObject<T | null>
  x: number
  y: number
}
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, useMove } from 'core'

export const meta = {
  title: 'useMove',
  description: 'Track the position of the pointer inside an element as a value between 0 and 1.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 75
}

## useMove

Track the position of the pointer inside an element as a value between 0 and 1.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="Press and drag inside the box to move the dot."
  scope={{ useMove }}
  code={`
() => {
  const [value, setValue] = React.useState({ x: 0.5, y: 0.5 })
  const { ref } = useMove(setValue)
  return (
    <div ref={ref} style={{ position: 'relative', width: 240, height: 120, border: '1px dashed currentColor', touchAction: 'none' }}>
      <div style={{ position: 'absolute', left: value.x * 100 + '%', top: value.y * 100 + '%', width: 12, height: 12, marginLeft: -6, marginTop: -6, borderRadius: '50%', background: 'currentColor' }} />
    </div>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-move.mdx">
<Attributes.Title>useMove</Attributes.Title>

```ts
const useMove = <T extends HTMLElement = HTMLElement>(
  onChange: (value: { x: number; y: number }) => void,
  onScrubEnd?: () => void,
) => { ref: RefObject<T | null>; active: boolean }
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Button, Text, useMutationObserver } from 'core'

export const meta = {
  title: 'useMutationObserver',
  description: 'Observe changes in the attributes, children or text of an element.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 76
}

## useMutationObserver

Observe changes in the attributes, children or text of an element.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="Count the children added to the list."
  scope={{ Button, Text, useMutationObserver }}
  code={`
() => {
  const [changes, setChanges] = React.useState(0)
  const [items, setItems] = React.useState(1)
  const ref = useMutationObserver(() => setChanges((c) => c + 1), { childList: true })
  return (
    <>
      <ul ref={ref}>{Array.from({ length: items }, (_, i) => <li key={i}>Item {i + 1}</li>)}</ul>
      <Button auto scale={0.6} onClick={() => setItems(items + 1)}>Add item</Button>
      <Text>Mutations: {changes}</Text>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-mutation-observer.mdx">
<Attributes.Title>useMutationObserver</Attributes.Title>

```ts
const useMutationObserver = <T extends HTMLElement = HTMLElement>(
  callback: MutationCallback,
  options: MutationObserverInit,
) => RefObject<T | null>
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Text, useNetwork } from 'core'

export const meta = {
  title: 'useNetwork',
  description: 'Read the state of the connection and know when it goes online or offline.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 42
}

## useNetwork

Read the state of the connection and know when it goes online or offline.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="Turn the network off in the browser to see the status change. Connection details are not available in every browser."
  scope={{ Text, useNetwork }}
  code={`
() => {
  const network = useNetwork()
  return <Text>{network.online ? 'Online' : 'Offline'}, {network.effectiveType || 'unknown connection'}</Text>
}
`}
/>

<Attributes edit="/content/docs/hooks/use-network.mdx">
<Attributes.Title>useNetwork</Attributes.Title>

```ts
const useNetwork = () => {
  online?: boolean
  downlink?: number
  downlinkMax?: number
  effectiveType?: string
  rtt?: number
  saveData?: boolean
  type?: string
}
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Text, useOrientation } from 'core'

export const meta = {
  title: 'useOrientation',
  description: 'Read the orientation of the screen, portrait or landscape, and its angle.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 77
}

## useOrientation

Read the orientation of the screen, portrait or landscape, and its angle.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="Rotate the device to see the values change."
  scope={{ Text, useOrientation }}
  code={`
() => {
  const { angle, type } = useOrientation()
  return <Text>{type}, {angle} degrees</Text>
}
`}
/>

<Attributes edit="/content/docs/hooks/use-orientation.mdx">
<Attributes.Title>useOrientation</Attributes.Title>

```ts
const useOrientation = (defaultValue?: {
  angle: number
  type: OrientationType
}) => { angle: number; type: OrientationType }
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Text, useOs } from 'core'

export const meta = {
  title: 'useOs',
  description: 'Detect the operating system of the user.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 43
}

## useOs

Detect the operating system of the user.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="It is undetermined on the server and on the first render."
  scope={{ Text, useOs }}
  code={`
() => {
  const os = useOs()
  return <Text>{os}</Text>
}
`}
/>

<Attributes edit="/content/docs/hooks/use-os.mdx">
<Attributes.Title>useOs</Attributes.Title>

```ts
const useOs = () =>
  | 'undetermined'
  | 'macos'
  | 'ios'
  | 'windows'
  | 'android'
  | 'linux'
  | 'chromeos'
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Text, usePageLeave } from 'core'

export const meta = {
  title: 'usePageLeave',
  description: 'Run a callback when the mouse leaves the page.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 44
}

## usePageLeave

Run a callback when the mouse leaves the page.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="Move the mouse out of the window."
  scope={{ Text, usePageLeave }}
  code={`
() => {
  const [count, setCount] = React.useState(0)
  usePageLeave(() => setCount((c) => c + 1))
  return <Text>The mouse left the page {count} times</Text>
}
`}
/>

<Attributes edit="/content/docs/hooks/use-page-leave.mdx">
<Attributes.Title>usePageLeave</Attributes.Title>

```ts
const usePageLeave = (onPageLeave: () => void) => void
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Button, Text, usePagination } from 'core'

export const meta = {
  title: 'usePagination',
  description: 'Compute the page numbers and the handlers of a pagination, with dots when there are many pages.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 78
}

## usePagination

Compute the page numbers and the handlers of a pagination, with dots when there are many pages.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="Twenty pages, with dots between the ranges."
  scope={{ Button, Text, usePagination }}
  code={`
() => {
  const { range, active, setPage, next, previous } = usePagination({ total: 20, initialPage: 5 })
  return (
    <>
      <Text>{range.map((item) => (item === 'dots' ? '...' : item === active ? '[' + item + ']' : item)).join(' ')}</Text>
      <Button auto scale={0.6} onClick={previous}>Previous</Button>
      <Button auto scale={0.6} onClick={next} style={{ marginLeft: 8 }}>Next</Button>
      <Button auto scale={0.6} onClick={() => setPage(1)} style={{ marginLeft: 8 }}>First</Button>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-pagination.mdx">
<Attributes.Title>usePagination</Attributes.Title>

```ts
const usePagination = (options: {
  total: number
  page?: number
  initialPage?: number
  siblings?: number
  boundaries?: number
  onChange?: (page: number) => void
}) => {
  range: (number | 'dots')[]
  active: number
  setPage: (page: number) => void
  next: () => void
  previous: () => void
  first: () => void
  last: () => void
}
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Button, Text, usePrevious } from 'core'

export const meta = {
  title: 'usePrevious',
  description: 'Get the value a variable had on the previous render.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 45
}

## usePrevious

Get the value a variable had on the previous render.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="It is null on the first render."
  scope={{ Button, Text, usePrevious }}
  code={`
() => {
  const [count, setCount] = React.useState(0)
  const previous = usePrevious(count)
  return (
    <>
      <Text>Now: {count}, before: {String(previous)}</Text>
      <Button auto scale={0.6} onClick={() => setCount(count + 1)}>Increment</Button>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-previous.mdx">
<Attributes.Title>usePrevious</Attributes.Title>

```ts
const usePrevious = <T>(value: T) => T | undefined | null
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Button, Text, useQueue } from 'core'

export const meta = {
  title: 'useQueue',
  description: 'Show a limited number of items at once and keep the rest waiting in a queue.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 46
}

## useQueue

Show a limited number of items at once and keep the rest waiting in a queue.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="Only two items are visible, the others wait in the queue."
  scope={{ Button, Text, useQueue }}
  code={`
() => {
  const { state, queue, add, update } = useQueue({ initialValues: [1, 2, 3], limit: 2 })
  return (
    <>
      <Text>Visible: {state.join(', ')}</Text>
      <Text>Queue: {queue.join(', ') || 'empty'}</Text>
      <Button auto scale={0.6} onClick={() => add(state.length + queue.length + 1)}>Add</Button>
      <Button auto scale={0.6} onClick={() => update((items) => items.slice(1))} style={{ marginLeft: 8 }}>Remove first</Button>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-queue.mdx">
<Attributes.Title>useQueue</Attributes.Title>

```ts
const useQueue = <T>(options?: {
  initialValues?: T[]
  limit?: number
}) => {
  state: T[]
  queue: T[]
  add: (...items: T[]) => void
  update: (fn: (items: T[]) => T[]) => void
  cleanQueue: () => void
}
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Text, useRadialMove } from 'core'

export const meta = {
  title: 'useRadialMove',
  description: 'Track the angle of the pointer around the center of an element, from 0 to 360 degrees.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 79
}

## useRadialMove

Track the angle of the pointer around the center of an element, from 0 to 360 degrees.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="Press and drag around the circle to turn the hand."
  scope={{ Text, useRadialMove }}
  code={`
() => {
  const [value, setValue] = React.useState(0)
  const { ref } = useRadialMove(setValue, { step: 5 })
  return (
    <>
      <div ref={ref} style={{ position: 'relative', width: 120, height: 120, border: '1px dashed currentColor', borderRadius: '50%', touchAction: 'none' }}>
        <div style={{ position: 'absolute', left: '50%', top: '50%', width: 2, height: 50, marginLeft: -1, marginTop: -50, background: 'currentColor', transformOrigin: 'bottom center', transform: 'rotate(' + value + 'deg)' }} />
      </div>
      <Text>{value} degrees</Text>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-radial-move.mdx">
<Attributes.Title>useRadialMove</Attributes.Title>

```ts
const useRadialMove = <T extends HTMLElement = HTMLElement>(
  onChange: (value: number) => void,
  options?: { step?: number; onChangeEnd?: (value: number) => void },
) => { ref: RefObject<T | null>; active: boolean }
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Text, useReducedMotion } from 'core'

export const meta = {
  title: 'useReducedMotion',
  description: 'Detect when the user asks the system to reduce motion.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 47
}

## useReducedMotion

Detect when the user asks the system to reduce motion.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="Turn on reduced motion in the system settings to see it change."
  scope={{ Text, useReducedMotion }}
  code={`
() => {
  const reduced = useReducedMotion()
  return <Text>{reduced ? 'Reduced motion' : 'Motion allowed'}</Text>
}
`}
/>

<Attributes edit="/content/docs/hooks/use-reduced-motion.mdx">
<Attributes.Title>useReducedMotion</Attributes.Title>

```ts
const useReducedMotion = () => boolean
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Text, useResizeObserver } from 'core'

export const meta = {
  title: 'useResizeObserver',
  description: 'Observe the size and position of an element with a ResizeObserver.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 48
}

## useResizeObserver

Observe the size and position of an element with a ResizeObserver.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="Resize the textarea to see its size change."
  scope={{ Text, useResizeObserver }}
  code={`
() => {
  const [ref, rect] = useResizeObserver()
  return (
    <>
      <Text>{Math.round(rect.width)} x {Math.round(rect.height)}</Text>
      <textarea ref={ref} style={{ resize: 'both', width: 240, height: 80 }} />
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-resize-observer.mdx">
<Attributes.Title>useResizeObserver</Attributes.Title>

```ts
const useResizeObserver = <T extends HTMLElement = HTMLElement>(
  options?: ResizeObserverOptions,
) => [RefObject<T | null>, UseResizeObserverRect]
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, useRovingIndex } from 'core'

export const meta = {
  title: 'useRovingIndex',
  description: 'Move the focus between the items of a list with the arrow keys, keeping one tab stop.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 80
}

## useRovingIndex

Move the focus between the items of a list with the arrow keys, keeping one tab stop.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="Tab into the group once, then use the arrow keys."
  scope={{ useRovingIndex }}
  code={`
() => {
  const { getItemProps } = useRovingIndex({ total: 3 })
  return (
    <div>
      {['One', 'Two', 'Three'].map((label, index) => (
        <button key={label} {...getItemProps(index)} style={{ marginRight: 8 }}>{label}</button>
      ))}
    </div>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-roving-index.mdx">
<Attributes.Title>useRovingIndex</Attributes.Title>

```ts
const useRovingIndex = (options: {
  total: number
  initialIndex?: number
  orientation?: 'horizontal' | 'vertical'
  loop?: boolean
  onChange?: (index: number) => void
}) => {
  selected: number
  setSelected: (index: number) => void
  getItemProps: (index: number) => {
    ref: (element: HTMLElement | null) => void
    tabIndex: number
    onFocus: () => void
    onKeyDown: (event: KeyboardEvent) => void
  }
}
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Button, useTheme } from 'core'

export const meta = {
  title: 'useScale',
  description:
    'Remember the elastic scaling feature mentioned in the subsection, which gave the Bolio UI components amazing imagination and extensibility.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 10
}

## useScale

Remember the elastic scaling feature mentioned in the [scale](/docs/hooks/use-scale#scale-the-width 'Scale') subsection,
which gave the Bolio UI components amazing imagination and extensibility,
and now you can add elastic scaling features to your own components with the help of the `useScale` hooks.

### Scale the width

As a first example, let's prepare a simple component with a fixed width:

```tsx
const MyComponent = ({ width: string = '20px' }) => {
  return <div style={{ width }}>Scale Component</div>
}
```

Although the component accepts a `string` parameter to define the `width`, we can't control the multiplier of the width,
say `1.35` times the width, unless it's manually calculated and then filled in, which seems fine,
but when our component can set more than 10 styles, the calculation of these values is very tedious.

Now we try to bind the component to the scale of Bolio UI:

```tsx
import { withScale, useScale } from '@bolio-ui/core'

const MyComponent = () => {
  const { SCALES } = useScale()
  return <div style={{ width: SCALES.width(1.25) }}>Scale Component</div>
}

export default withScale(MyComponent)
```

`withScale` can transform any component into a dynamically scaled component and automatically **add props and types** to the component.
You just need to set `useScale` within the component to get the `SCALES`, and then add the bindings for the `SCALES` for each style.

The default unit of Scale is `16px`, when we need to set the default width to `20px`, Obviously `20px` is 1.25 times more than `16px`,
so we get `SCALES.width(1.25)`.

The components of the above example should be used as follows:

```tsx
<MyComponent width={0.5} />
<MyComponent width="10px" />
<MyComponent width="auto" />
<MyComponent unit="10rem" />
```

### Unconventional defaults

In a few components where we want the default width to be `auto` (or others), and allow user-defined `width` to override this value,
then within the Scale component we want to follow the following rules:

- When the initial value is a special character (`initial` etc.), the component cannot be scaled by a factor of.
- The user can still override the initial value with the specified value.

For a simple component, the following example can be used to illustrate:

```tsx
const MyComponent = () => {
  const { SCALES } = useScale()
  return <div style={{ width: SCALES.width(1, 'auto') }}>Fixed Component</div>
}

export default withScale(MyComponent)
```

When we use this component, the width cannot be scaled by a multiple anymore:

```tsx
<MyComponent width={0.1} />

// -> The width is still "auto"
// -> "auto" cannot be calculated mathematically
```

When we enter specific values to override, it still works well:

```tsx
<MyComponent width="100px" />

// -> The width is "100px"
```

### Get native props

When a component is combined with `withScale`, multiple props and corresponding types are automatically added,
we can use the `useScale` function to get the corresponding value.
Note, however, that the value obtained from the `useScale` function is computed, not the native value.

```tsx
const MyComponent = () => {
  const { SCALES } = useScale()

  console.log(SCALES.width(1))

  return null
}

<MyComponent width={2} />  // output -> 'calc(2 * 16px)'
<MyComponent />            // output -> '16px'
```

The value obtained from `SCALES.width` is not exactly equal to the user input (`width=`),
because we want to make sure that the component works even if the user does nothing.
So, if you need to get the **native value** of the user input, use a separate function to get:

```ts
const MyComponent = () => {
  const { getScaleProps } = useScale()

  console.log(getScaleProps('width'))

  return null
}

<MyComponent width={2} />     // output -> 2
<MyComponent width="20px" />  // output -> '20px'
<MyComponent />               // output -> undefined
```

<Attributes edit="/content/docs/hooks/use-scale.mdx">
<Attributes.Title>withScale</Attributes.Title>

```ts
type withScale = (Render: React.ComponentType) => React.ComponentType
```

<Attributes.Title>useScale</Attributes.Title>

```ts
type useScale = () => ScaleConfig

type ScaleConfig = {
  SCALES: DynamicScales
  // Get the native value of scale prop
  getScaleProps: GetScalePropsFunction
  // Base value of the current component
  unit: string
}
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Text, useScrollDirection } from 'core'

export const meta = {
  title: 'useScrollDirection',
  description: 'Know whether the page is being scrolled up or down.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 81
}

## useScrollDirection

Know whether the page is being scrolled up or down.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="Scroll the page to see the value change."
  scope={{ Text, useScrollDirection }}
  code={`
() => {
  const direction = useScrollDirection()
  return <Text>Scrolling {direction}</Text>
}
`}
/>

<Attributes edit="/content/docs/hooks/use-scroll-direction.mdx">
<Attributes.Title>useScrollDirection</Attributes.Title>

```ts
const useScrollDirection = () => 'up' | 'down'
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Button, useScrollIntoView } from 'core'

export const meta = {
  title: 'useScrollIntoView',
  description: 'Scroll smoothly to an element, in the page or inside a container.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 83
}

## useScrollIntoView

Scroll smoothly to an element, in the page or inside a container.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="Scroll the box down to the last item."
  scope={{ Button, useScrollIntoView }}
  code={`
() => {
  const { targetRef, scrollableRef, scrollIntoView } = useScrollIntoView({ duration: 500 })
  return (
    <>
      <Button auto scale={0.6} onClick={scrollIntoView}>Scroll to the last item</Button>
      <div ref={scrollableRef} style={{ marginTop: 8, height: 100, overflow: 'auto', border: '1px dashed currentColor' }}>
        <div style={{ height: 300 }}>Scroll content</div>
        <div ref={targetRef}>Last item</div>
      </div>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-scroll-into-view.mdx">
<Attributes.Title>useScrollIntoView</Attributes.Title>

```ts
const useScrollIntoView = <
  T extends HTMLElement = HTMLElement,
  C extends HTMLElement = HTMLElement,
>(options?: { duration?: number; offset?: number }) => {
  targetRef: RefObject<T | null>
  scrollableRef: RefObject<C | null>
  scrollIntoView: () => void
  cancel: () => void
}
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Text, useScrollSpy } from 'core'

export const meta = {
  title: 'useScrollSpy',
  description: 'Highlight the heading that is visible while the page is scrolled, for a table of contents.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 84
}

## useScrollSpy

Highlight the heading that is visible while the page is scrolled, for a table of contents.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="Lists the h2 headings of the page and marks the one being read."
  scope={{ Text, useScrollSpy }}
  code={`
() => {
  const { active, data } = useScrollSpy({ selector: 'h2', offset: 80 })
  return (
    <>
      {data.slice(0, 6).map((heading, index) => (
        <Text key={heading.id + index} small b={index === active}>{heading.label}</Text>
      ))}
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-scroll-spy.mdx">
<Attributes.Title>useScrollSpy</Attributes.Title>

```ts
const useScrollSpy = (options?: {
  selector?: string
  offset?: number
}) => {
  active: number
  data: {
    id: string
    label: string
    depth: number
    element: HTMLElement
  }[]
  reinitialize: () => void
}
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Button, useScroller } from 'core'

export const meta = {
  title: 'useScroller',
  description: 'Know whether a scrollable row can scroll further and scroll it by a step, for carousels and tab lists.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 82
}

## useScroller

Know whether a scrollable row can scroll further and scroll it by a step, for carousels and tab lists.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="The buttons are disabled when the row cannot scroll further."
  scope={{ Button, useScroller }}
  code={`
() => {
  const { ref, canScrollStart, canScrollEnd, scrollBy } = useScroller(120)
  return (
    <>
      <Button auto scale={0.6} disabled={!canScrollStart} onClick={() => scrollBy('start')}>Previous</Button>
      <Button auto scale={0.6} disabled={!canScrollEnd} onClick={() => scrollBy('end')} style={{ marginLeft: 8 }}>Next</Button>
      <div ref={ref} style={{ marginTop: 8, display: 'flex', gap: 8, overflow: 'auto', width: 240 }}>
        {Array.from({ length: 10 }, (_, i) => <div key={i} style={{ flex: '0 0 80px', padding: 16, border: '1px solid currentColor' }}>{i + 1}</div>)}
      </div>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-scroller.mdx">
<Attributes.Title>useScroller</Attributes.Title>

```ts
const useScroller = <T extends HTMLElement = HTMLElement>(
  step?: number,
) => {
  ref: RefObject<T | null>
  canScrollStart: boolean
  canScrollEnd: boolean
  scrollBy: (direction: 'start' | 'end') => void
}
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Button, Text, Spacer, useSelection } from 'core'

export const meta = {
  title: 'useSelection',
  description: 'Select items of a list, one by one or all at once, and know which are selected.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 85
}

## useSelection

Select items of a list, one by one or all at once, and know which are selected.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="Toggle items or select them all."
  scope={{ Button, Text, Spacer, useSelection }}
  code={`
() => {
  const data = ['Apple', 'Banana', 'Cherry']
  const [selected, handlers] = useSelection({ data })
  return (
    <>
      {data.map((item) => (
        <Button key={item} auto scale={0.6} type={handlers.isSelected(item) ? 'success' : 'default'} onClick={() => handlers.toggle(item)} style={{ marginRight: 8 }}>{item}</Button>
      ))}
      <Spacer h={0.5} />
      <Button auto scale={0.6} onClick={handlers.selectAll}>Select all</Button>
      <Button auto scale={0.6} onClick={handlers.deselectAll} style={{ marginLeft: 8 }}>Clear</Button>
      <Text>Selected: {selected.join(', ') || 'none'}</Text>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-selection.mdx">
<Attributes.Title>useSelection</Attributes.Title>

```ts
const useSelection = <T>(options: {
  data: T[]
  initialSelection?: T[]
}) => [
  T[],
  {
    select: (item: T) => void
    deselect: (item: T) => void
    toggle: (item: T) => void
    selectAll: () => void
    deselectAll: () => void
    setSelection: (items: T[]) => void
    isSelected: (item: T) => boolean
  },
]
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Button, Text, useSetState } from 'core'

export const meta = {
  title: 'useSetState',
  description: 'Keep an object in state and update it with partial changes, like the setState of a class component.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 49
}

## useSetState

Keep an object in state and update it with partial changes, like the setState of a class component.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="Changing one field keeps the others."
  scope={{ Button, Text, useSetState }}
  code={`
() => {
  const [state, setState] = useSetState({ name: 'Ada', age: 36 })
  return (
    <>
      <Text>{state.name}, {state.age}</Text>
      <Button auto scale={0.6} onClick={() => setState({ name: 'Grace' })}>Change name</Button>
      <Button auto scale={0.6} onClick={() => setState((current) => ({ age: current.age + 1 }))} style={{ marginLeft: 8 }}>Add a year</Button>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-set-state.mdx">
<Attributes.Title>useSetState</Attributes.Title>

```ts
const useSetState = <T extends Record<string, unknown>>(
  initialState: T,
) => [
  T,
  (partial: Partial<T> | ((current: T) => Partial<T>)) => void,
]
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Button, Text, useSet } from 'core'

export const meta = {
  title: 'useSet',
  description: 'Keep a Set in state that renders again when it changes.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 86
}

## useSet

Keep a Set in state that renders again when it changes.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="add, delete and clear render the component again."
  scope={{ Button, Text, useSet }}
  code={`
() => {
  const set = useSet(['a', 'b'])
  return (
    <>
      <Text>{[...set].join(', ') || 'empty'}</Text>
      <Button auto scale={0.6} onClick={() => set.add('item ' + (set.size + 1))}>Add</Button>
      <Button auto scale={0.6} onClick={() => set.clear()} style={{ marginLeft: 8 }}>Clear</Button>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-set.mdx">
<Attributes.Title>useSet</Attributes.Title>

```ts
const useSet = <T>(values?: readonly T[]) => Set<T>
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Button, Text, useShallowEffect } from 'core'

export const meta = {
  title: 'useShallowEffect',
  description: 'Run an effect when the dependencies change, comparing objects and arrays by their contents.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 50
}

## useShallowEffect

Run an effect when the dependencies change, comparing objects and arrays by their contents.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="The effect runs once, even though the object is new on every render."
  scope={{ Button, Text, useShallowEffect }}
  code={`
() => {
  const [, setCount] = React.useState(0)
  const [runs, setRuns] = React.useState(0)
  useShallowEffect(() => setRuns((r) => r + 1), [{ id: 1 }])
  return (
    <>
      <Text>Effect ran {runs} times</Text>
      <Button auto scale={0.6} onClick={() => setCount((c) => c + 1)}>Render again</Button>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-shallow-effect.mdx">
<Attributes.Title>useShallowEffect</Attributes.Title>

```ts
const useShallowEffect = (
  cb: EffectCallback,
  dependencies?: DependencyList,
) => void
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, useSplitter } from 'core'

export const meta = {
  title: 'useSplitter',
  description: 'Resize two panes by dragging the handle between them, in percent of the container.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 87
}

## useSplitter

Resize two panes by dragging the handle between them, in percent of the container.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="Drag the bar to resize the panes."
  scope={{ useSplitter }}
  code={`
() => {
  const { containerRef, handleRef, size } = useSplitter({ initialSize: 40 })
  return (
    <div ref={containerRef} style={{ display: 'flex', height: 100, border: '1px dashed currentColor' }}>
      <div style={{ width: size + '%', padding: 8 }}>{Math.round(size)}%</div>
      <div ref={handleRef} style={{ width: 8, cursor: 'col-resize', touchAction: 'none', background: 'currentColor', opacity: 0.3 }} />
      <div style={{ flex: 1, padding: 8 }}>Second pane</div>
    </div>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-splitter.mdx">
<Attributes.Title>useSplitter</Attributes.Title>

```ts
const useSplitter = <
  C extends HTMLElement = HTMLElement,
  H extends HTMLElement = HTMLElement,
>(options?: {
  initialSize?: number
  min?: number
  max?: number
  direction?: 'horizontal' | 'vertical'
}) => {
  containerRef: RefObject<C | null>
  handleRef: RefObject<H | null>
  size: number
  dragging: boolean
}
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Button, Text, useStateHistory } from 'core'

export const meta = {
  title: 'useStateHistory',
  description: 'Keep a value with its history and move back and forward through it.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 51
}

## useStateHistory

Keep a value with its history and move back and forward through it.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="Undo and redo the changes of a value."
  scope={{ Button, Text, useStateHistory }}
  code={`
() => {
  const [value, handlers, state] = useStateHistory(1)
  return (
    <>
      <Text h3>{value}</Text>
      <Button auto scale={0.6} onClick={() => handlers.set(value + 1)}>Increment</Button>
      <Button auto scale={0.6} onClick={() => handlers.back()} style={{ marginLeft: 8 }}>Undo</Button>
      <Button auto scale={0.6} onClick={() => handlers.forward()} style={{ marginLeft: 8 }}>Redo</Button>
      <Text small>History: {state.history.join(', ')}</Text>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-state-history.mdx">
<Attributes.Title>useStateHistory</Attributes.Title>

```ts
const useStateHistory = <T>(initialValue: T) => [
  T,
  {
    set: (value: T) => void
    back: (steps?: number) => void
    forward: (steps?: number) => void
    reset: () => void
  },
  { history: T[]; current: number },
]
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { useTabs, Tabs, Button, Spacer } from 'core'

export const meta = {
  title: 'useTabs',
  description:
    'Provides automatic binding for component, which can reduce the amount of repetitive code and improve the development experience.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 11
}

## useTabs

`useTabs` provides automatic binding for component [Tabs](/docs/components/tabs), which can reduce the amount of repetitive code and improve the development experience.
Using this hooks behaves the same as if you had added `React.useState` manually.

<Playground
  desc="Control components with Hooks."
  scope={{ Tabs, Button, Spacer, useTabs }}
  code={`
() => {
  const { setState, bindings } = useTabs('1')
  return (
    <>
      <Button scale={1/3} font="12px" onClick={() => setState('2')}>
        To Extensible
      </Button>
      <Spacer h={.5} />
      <Tabs {...bindings}>
        <Tabs.Item label="stateless" value="1">HTTP is stateless, but not sessionless.</Tabs.Item>
        <Tabs.Item label="extensible" value="2">Introduced in HTTP/1.0, HTTP headers make this protocol easy to extend and experiment with.</Tabs.Item>
      </Tabs>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-tabs.mdx" >
<Attributes.Title>useTabs</Attributes.Title>

```ts
type useTabs = (initialValue: string) => {
  state: string
  setState: Dispatch<SetStateAction<string>>
  currentRef: MutableRefObject<string>
  bindings: {
    value: string
    onChange: (val: string) => void
  }
}
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Text, useTextSelection } from 'core'

export const meta = {
  title: 'useTextSelection',
  description: 'Read the text the user has selected on the page.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 52
}

## useTextSelection

Read the text the user has selected on the page.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="Select some text of this page."
  scope={{ Text, useTextSelection }}
  code={`
() => {
  const selection = useTextSelection()
  return <Text>Selected: {selection ? selection.toString() : ''}</Text>
}
`}
/>

<Attributes edit="/content/docs/hooks/use-text-selection.mdx">
<Attributes.Title>useTextSelection</Attributes.Title>

```ts
const useTextSelection = () => Selection | null
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Button, useTheme } from 'core'

export const meta = {
  title: 'useTheme',
  description:
    'This hooks can get the theme states of Bolio UI within any component, and can track changes in states.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 12
}

## useTheme

This hooks can get the theme states of Bolio UI within any component, and can track changes in states.
In the default scenario (you haven't changed the `themeType`), hooks gets the same value as `Themes.getPresets`.

Usually the components from Bolio are already added with theme states, you don't need to change it,
this hooks just helps you to build your own components using Bolio UI's themes.

Notice in the example below that after we define the component using Theme,
the properties of the custom component will change according to the current Bolio UI's theme,
switching themes in the upper right corner of the website, the color of the components we create will also change with the theme.

<Playground
  scope={{ useTheme, Button }}
  desc=""
  code={`
() => {
  const theme = useTheme()
  return (
    <div style={{
        width: '200px',
        height: '50px',
        borderRadius: theme.layout.radius,
        background: theme.palette.accents_2
      }}
    >
      <span style={{
          color: theme.palette.accents_7,
          paddingLeft: theme.layout.gapQuarter
        }}
      >My first component.</span>
    </div>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-theme.mdx">
<Attributes.Title>useTheme</Attributes.Title>

```ts
const theme: BolioUIThemes = useTheme()

export type BolioUIThemes = {
  type: string
  font: BolioUIThemesFont
  layout: BolioUIThemesLayout
  palette: BolioUIThemesPalette
  breakpoints: BolioUIThemesBreakpoints
  expressiveness: BolioUIThemesExpressiveness
}
```

<Attributes.Title>Get preset types</Attributes.Title>

```ts
import {
  BolioUIThemes,
  BolioUIThemesFont,
  BolioUIThemesPalette,
  BolioUIThemesExpressiveness,
  BolioUIThemesLayout
} from '@bolio-ui/core'

const myFontTheme: BolioUIThemesFont = {}
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Text, useThrottledCallback } from 'core'

export const meta = {
  title: 'useThrottledCallback',
  description: 'Create a function that runs at most once per interval, with a trailing call.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 53
}

## useThrottledCallback

Create a function that runs at most once per interval, with a trailing call.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="Move the mouse over the box, the position updates at most every 200ms."
  scope={{ Text, useThrottledCallback }}
  code={`
() => {
  const [position, setPosition] = React.useState('0, 0')
  const update = useThrottledCallback((e) => setPosition(e.clientX + ', ' + e.clientY), 200)
  return (
    <div onMouseMove={update} style={{ padding: 24, border: '1px dashed currentColor' }}>
      <Text>{position}</Text>
    </div>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-throttled-callback.mdx">
<Attributes.Title>useThrottledCallback</Attributes.Title>

```ts
const useThrottledCallback = <A extends unknown[]>(
  callback: (...args: A) => void,
  wait: number,
) => ((...args: A) => void) & { cancel: () => void }
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Button, Text, useThrottledState } from 'core'

export const meta = {
  title: 'useThrottledState',
  description: 'Keep a state that updates at most once per interval.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 88
}

## useThrottledState

Keep a state that updates at most once per interval.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="The click count shows at most one update per second."
  scope={{ Button, Text, useThrottledState }}
  code={`
() => {
  const [count, setCount] = useThrottledState(0, 1000)
  const clicks = React.useRef(0)
  return (
    <>
      <Button auto scale={0.6} onClick={() => setCount(++clicks.current)}>Click fast</Button>
      <Text>Shown: {count}</Text>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-throttled-state.mdx">
<Attributes.Title>useThrottledState</Attributes.Title>

```ts
const useThrottledState = <T>(
  initialValue: T,
  wait: number,
) => [T, (value: T) => void]
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Text, Input, Spacer, useThrottledValue } from 'core'

export const meta = {
  title: 'useThrottledValue',
  description: 'Limit how often a value updates, no more than once per interval.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 89
}

## useThrottledValue

Limit how often a value updates, no more than once per interval.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="The throttled value updates at most once per second."
  scope={{ Text, Input, Spacer, useThrottledValue }}
  code={`
() => {
  const [value, setValue] = React.useState('')
  const throttled = useThrottledValue(value, 1000)
  return (
    <>
      <Input placeholder="Type fast" value={value} onChange={(e) => setValue(e.target.value)} />
      <Spacer h={0.5} />
      <Text>Throttled: {throttled}</Text>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-throttled-value.mdx">
<Attributes.Title>useThrottledValue</Attributes.Title>

```ts
const useThrottledValue = <T>(value: T, wait: number) => T
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Button, Text, useTimeout } from 'core'

export const meta = {
  title: 'useTimeout',
  description: 'Run a function after a delay that you can start again or clear.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 54
}

## useTimeout

Run a function after a delay that you can start again or clear.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="The message appears two seconds after the click."
  scope={{ Button, Text, useTimeout }}
  code={`
() => {
  const [visible, setVisible] = React.useState(false)
  const { start } = useTimeout(() => setVisible(true), 2000)
  return (
    <>
      <Button auto scale={0.6} onClick={() => { setVisible(false); start() }}>Start</Button>
      <Text>{visible ? 'Done' : 'Waiting'}</Text>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-timeout.mdx">
<Attributes.Title>useTimeout</Attributes.Title>

```ts
const useTimeout = (
  callback: () => void,
  delay: number,
  options?: { autoInvoke?: boolean },
) => { start: () => void; clear: () => void }
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { useToasts, Button, Spacer, Link, SegmentedControl } from 'core'

export const meta = {
  title: 'useToast',
  description: 'Display an important message globally.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 13
}

## useToast

Display an important message globally. A toast is not a component you render: call `setToast` from `useToasts` anywhere under `BolioUIProvider`, and the provider shows it. It disappears after `delay`, and stays while the pointer is over it.

<Playground
  desc="Basic usage. The toast closes after 2 seconds, or after `delay` milliseconds."
  scope={{ Button, useToasts }}
  code={`
() => {
  const { setToast } = useToasts()
  const click = () => setToast({ text: 'Draft saved.', delay: 3000 })
  return <Button scale={2/3} auto onClick={click}>Save draft</Button>
}
`}
/>

<Playground
  title="Type"
  desc="Use `type` to tell a result from a problem. An `error` toast is announced right away by a screen reader, the others wait for a pause."
  scope={{ Button, useToasts, Spacer }}
  code={`
() => {
  const { setToast } = useToasts()
  const messages = {
    success: 'Invoice 2041 is paid.',
    info: 'A new version is ready to load.',
    warning: 'You used 92% of your storage.',
    error: 'Your card was declined. Update it to try again.'
  }
  const click = (type) => setToast({ text: messages[type], type })
  return (
    <>
      {Object.keys(messages).map((type) => (
        <React.Fragment key={type}>
          <Button scale={2/3} auto onClick={() => click(type)} type={type} style={{ textTransform: 'capitalize' }}>{type}</Button>
          <Spacer inline w={.5} />
        </React.Fragment>
      ))}
    </>
  )
}
`}
/>

<Playground
  title="Multiline"
  desc="Display multiline or overlong text."
  scope={{ Button, useToasts }}
  code={`
() => {
  const { setToast } = useToasts()
  const click = () => setToast({ text: 'HTTP is a protocol which allows the fetching of resources, such as HTML documents. It is the foundation of any data exchange on the Web and it is a client-server protocol, which means requests are initiated by the recipient, usually the Web browser. A complete document is reconstructed from the different sub-documents fetched, for instance text, layout description, images, videos, scripts, and more.' })
  return <Button scale={2/3} auto onClick={click}>Show Toast</Button>
}
`}
/>

<Playground
  title="Action"
  desc="Add a button with `actions`. Its `handler` receives the click and a `cancel` function that closes the toast. Actions show only when `text` is a string."
  scope={{ Button, useToasts }}
  code={`
() => {
  const { setToast } = useToasts()
  const archive = () => {
    setToast({
      text: 'Conversation archived.',
      delay: 6000,
      actions: [{
        name: 'Undo',
        handler: (event, cancel) => {
          cancel()
          setToast({ text: 'Conversation restored.' })
        }
      }]
    })
  }
  return <Button scale={2/3} auto onClick={archive}>Archive conversation</Button>
}
`}
/>

<Playground
  title="Cancel"
  desc="Use `passive` to change the style of the button, for an action that only dismisses."
  scope={{ Button, useToasts }}
  code={`
() => {
  const { setToast } = useToasts()
  const click = () => setToast({
    text: 'You are offline. Changes sync when you reconnect.',
    delay: 8000,
    actions: [{ name: 'Dismiss', passive: true, handler: (event, cancel) => cancel() }]
  })
  return <Button scale={2/3} auto onClick={click}>Go offline</Button>
}
`}
/>

<Playground
  title="ReactNode"
  desc="Show more information by replacing the string with a `ReactNode`. The content replaces the whole toast, so put any button or link inside it."
  scope={{ Button, useToasts, Link }}
  code={`
() => {
  const { setToast } = useToasts()
  const click = () => setToast({
    text: <p>Click the <Link target="_blank" color block href="https://github.com/bolio-ui/bolio-ui">URL</Link> to learn more</p>,
    delay: 4000,
  })
  return <Button scale={2/3} auto onClick={click}>Show Toast</Button>
}
`}
/>

<Playground
  title="Placement"
  desc="Pass a layout to `useToasts` to choose where toasts appear. The layout applies when the component mounts, so it is set once, not on each toast."
  scope={{ Button, useToasts, SegmentedControl, Spacer }}
  code={`
() => {
  const Demo = ({ placement }) => {
    const { setToast } = useToasts({ placement })
    return (
      <Button scale={2/3} auto onClick={() => setToast({ text: 'Showing at ' + placement + '.' })}>
        Show Toast
      </Button>
    )
  }
  const [placement, setPlacement] = React.useState('bottomRight')
  return (
    <>
      <SegmentedControl value={placement} onChange={setPlacement} aria-label="Placement">
        <SegmentedControl.Item value="topLeft">Top left</SegmentedControl.Item>
        <SegmentedControl.Item value="topRight">Top right</SegmentedControl.Item>
        <SegmentedControl.Item value="bottomLeft">Bottom left</SegmentedControl.Item>
        <SegmentedControl.Item value="bottomRight">Bottom right</SegmentedControl.Item>
      </SegmentedControl>
      <Spacer h={1} />
      <Demo key={placement} placement={placement} />
    </>
  )
}
`}
/>

<Playground
  title="Unique id"
  desc="Give a toast an `id` to close it later with `removeToastOneByID`, or use `removeAll` to close every toast. Setting a toast with an `id` that is still shown throws an error, so check with `findToastOneByID` first."
  scope={{ Button, useToasts, Spacer }}
  code={`
() => {
  const { setToast, findToastOneByID, removeToastOneByID, removeAll } = useToasts()
  const start = () => {
    if (findToastOneByID('upload')) return
    setToast({ id: 'upload', text: 'Uploading 3 files.', delay: 20000 })
  }
  return (
    <>
      <Button scale={2/3} auto onClick={start}>Start upload</Button>
      <Spacer inline w={.5} />
      <Button scale={2/3} auto onClick={() => removeToastOneByID('upload')}>Cancel upload</Button>
      <Spacer inline w={.5} />
      <Button scale={2/3} auto onClick={removeAll}>Clear all</Button>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-toast.mdx">
<Attributes.Title>useToasts</Attributes.Title>

```ts
const {
  // All Toasts currently in DOM
  toasts: Array<Toast>

  // Set a displayable Toast
  setToast: (toast: ToastInput) => void

  // Hide all Toast immediately
  removeAll: () => void

  // Query by id to get an instance of Toast
  findToastOneByID: (ident: string) => Toast | undefined

  // Remove the specified Toast by id
  removeToastOneByID: (ident: string) => void
} = useToasts(layout: ToastLayout)
```

<Attributes.Title>ToastLayout</Attributes.Title>

| Option        | Description                  | Type                              | Default       |
| ------------- | ---------------------------- | --------------------------------- | ------------- |
| **padding**   | space inside each toast      | `string`                          | `12px 16px`   |
| **margin**    | space around each toast      | `string`                          | `8px 0`       |
| **width**     | width of each toast          | `string`                          | `420px`       |
| **maxWidth**  | largest width of a toast     | `string`                          | `90vw`        |
| **maxHeight** | largest height of a toast    | `string`                          | `75px`        |
| **placement** | the pop-up position of toast | [ToastPlacement](#toastplacement) | `bottomRight` |

<Attributes.Title>ToastInput</Attributes.Title>

| Option      | Description                                  | Type                        | Default   |
| ----------- | -------------------------------------------- | --------------------------- | --------- |
| **id**      | name to find or close the toast. It must not match a toast that is still shown | `string`                    | generated |
| **text**    | content displayed in toast                   | `string`, `ReactNode`       | -         |
| **type**    | the type of toast                            | [ToastTypes](#toasttypes)   | `default` |
| **delay**   | milliseconds before it closes. `0` uses the default | `number`             | `2000`    |
| **actions** | buttons shown after the text. Only with a string `text` | [ToastAction](#toastaction)[] | -  |

<Attributes.Title>ToastPlacement</Attributes.Title>

```ts
type ToastPlacement = 'topLeft' | 'topRight' | 'bottomLeft' | 'bottomRight'
```

<Attributes.Title>ToastAction</Attributes.Title>

```ts
interface ToastAction {
  name: string
  handler: (
    event: React.MouseEvent<HTMLButtonElement>,
    cancel: () => void
  ) => void
  passive?: boolean
}
```

<Attributes.Title>ToastTypes</Attributes.Title>

```ts
type ToastTypes =
  | 'default'
  | 'primary'
  | 'secondary'
  | 'success'
  | 'warning'
  | 'error'
  | 'info'
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Button, Spacer, useToggle } from 'core'

export const meta = {
  title: 'useToggle',
  description: 'Switch between two or more values, a boolean by default.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 55
}

## useToggle

Switch between two or more values, a boolean by default.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="Without arguments it flips a boolean, with a list it cycles through the values."
  scope={{ Button, Spacer, useToggle }}
  code={`
() => {
  const [value, toggle] = useToggle()
  const [theme, toggleTheme] = useToggle(['light', 'dark', 'system'])
  return (
    <>
      <Button auto scale={0.6} onClick={() => toggle()}>{String(value)}</Button>
      <Spacer h={0.5} />
      <Button auto scale={0.6} onClick={() => toggleTheme()}>{theme}</Button>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-toggle.mdx">
<Attributes.Title>useToggle</Attributes.Title>

```ts
const useToggle = <T = boolean>(
  options?: readonly T[]
) => readonly [T, (value?: T) => void]
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Input, Spacer, useUncontrolled } from 'core'

export const meta = {
  title: 'useUncontrolled',
  description: 'Build a component that works controlled and uncontrolled with the same code.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 56
}

## useUncontrolled

Build a component that works controlled and uncontrolled with the same code.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="The same component keeps its own state or follows the value prop."
  scope={{ Input, Spacer, useUncontrolled }}
  code={`
() => {
  const Field = ({ value, defaultValue, onChange }) => {
    const [current, setCurrent, controlled] = useUncontrolled({ value, defaultValue, finalValue: '', onChange })
    return <Input value={current} onChange={(e) => setCurrent(e.target.value)} placeholder={controlled ? 'Controlled' : 'Uncontrolled'} />
  }
  const [value, setValue] = React.useState('')
  return (
    <>
      <Field defaultValue="Starts here" />
      <Spacer h={0.5} />
      <Field value={value} onChange={setValue} />
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-uncontrolled.mdx">
<Attributes.Title>useUncontrolled</Attributes.Title>

```ts
const useUncontrolled = <T>(options: {
  value?: T
  defaultValue?: T
  finalValue?: T
  onChange?: (value: T) => void
}) => [T, (value: T) => void, boolean]
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Text, Input, Spacer, useValidatedState } from 'core'

export const meta = {
  title: 'useValidatedState',
  description: 'Keep a value together with its validity and the last value that was valid.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 57
}

## useValidatedState

Keep a value together with its validity and the last value that was valid.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="The email is valid when it matches a simple pattern."
  scope={{ Text, Input, Spacer, useValidatedState }}
  code={`
() => {
  const [{ value, lastValidValue, valid }, setEmail] = useValidatedState('', (v) => /^\S+@\S+\.\S+$/.test(v))
  return (
    <>
      <Input placeholder="Email" value={value} onChange={(e) => setEmail(e.target.value)} />
      <Spacer h={0.5} />
      <Text>Valid: {String(valid)}, last valid: {lastValidValue || 'none'}</Text>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-validated-state.mdx">
<Attributes.Title>useValidatedState</Attributes.Title>

```ts
const useValidatedState = <T>(
  initialValue: T,
  validate: (value: T) => boolean,
) => [
  { value: T; lastValidValue: T | undefined; valid: boolean },
  (value: T) => void,
]
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Text, useViewportSize } from 'core'

export const meta = {
  title: 'useViewportSize',
  description: 'Get the width and height of the window and keep them updated.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 58
}

## useViewportSize

Get the width and height of the window and keep them updated.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="Resize the window to see the values change."
  scope={{ Text, useViewportSize }}
  code={`
() => {
  const { width, height } = useViewportSize()
  return <Text>{width} x {height}</Text>
}
`}
/>

<Attributes edit="/content/docs/hooks/use-viewport-size.mdx">
<Attributes.Title>useViewportSize</Attributes.Title>

```ts
const useViewportSize = () => { width: number; height: number }
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Text, useWindowEvent } from 'core'

export const meta = {
  title: 'useWindowEvent',
  description: 'Attach an event listener to the window and remove it when the component unmounts.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 59
}

## useWindowEvent

Attach an event listener to the window and remove it when the component unmounts.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="Show the last key pressed anywhere on the page."
  scope={{ Text, useWindowEvent }}
  code={`
() => {
  const [key, setKey] = React.useState('')
  useWindowEvent('keydown', (event) => setKey(event.key))
  return <Text>Last key: {key || 'none yet'}</Text>
}
`}
/>

<Attributes edit="/content/docs/hooks/use-window-event.mdx">
<Attributes.Title>useWindowEvent</Attributes.Title>

```ts
const useWindowEvent = <K extends keyof WindowEventMap>(
  type: K,
  listener: (event: WindowEventMap[K]) => void,
  options?: boolean | AddEventListenerOptions,
) => void
```

</Attributes>

export default Docs.withMeta(meta)


---

import Docs from 'src/templates/Docs'
import { Playground, Attributes } from 'src/components'
import { Link, Button, Text, useWindowScroll } from 'core'

export const meta = {
  title: 'useWindowScroll',
  description: 'Read the scroll position of the window and scroll it.',
  sidebar: 'hooks',
  group: 'Hooks',
  index: 60
}

## useWindowScroll

Read the scroll position of the window and scroll it.

This is custom React hooks, you need to follow the <Link target="_blank" color href="https://reactjs.org/docs/hooks-rules.html">Basic Rules</Link> when you use it.

<Playground
  desc="Read the scroll position and go back to the top."
  scope={{ Button, Text, useWindowScroll }}
  code={`
() => {
  const [scroll, scrollTo] = useWindowScroll()
  return (
    <>
      <Text>Scroll: {scroll.x}, {scroll.y}</Text>
      <Button auto scale={0.6} onClick={() => scrollTo({ y: 0 })}>Scroll to top</Button>
    </>
  )
}
`}
/>

<Attributes edit="/content/docs/hooks/use-window-scroll.mdx">
<Attributes.Title>useWindowScroll</Attributes.Title>

```ts
const useWindowScroll = () => [
  { x: number; y: number },
  (position: { x?: number; y?: number }) => void,
]
```

</Attributes>

export default Docs.withMeta(meta)