---
title: Format
description: "`Format` is used to format dates, numbers, and bytes according to a specific locale."
links:
  - source: https://github.com/yamada-ui/yamada-ui/tree/main/packages/react/src/components/format
  - storybook: https://yamada-ui.github.io/yamada-ui?path=/story/components-format
---

```tsx
<VStack gap="0">
  <Format.Byte value={1234567} />
  <Format.Number value={1234567.89} />
</VStack>
```

## Usage

```tsx
import { Format } from "@yamada-ui/react"
```

```tsx
import { Format } from "@/components/ui"
```

```tsx
import { Format } from "@workspaces/ui"
```

```tsx
<Format.Byte />
<Format.Number />
```

### Dates

:::note
`Format.DateTime` internally uses [Intl.DateTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat).
:::

#### Changing the Locale

To change the locale, set a value for [locale](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#locales).

```tsx
<Grid templateColumns="auto 1fr" gap="sm">
  <Text fontWeight="semibold">en-US</Text>
  <Format.DateTime value={new Date()} locale="en-US" />

  <Text fontWeight="semibold">ja-JP</Text>
  <Format.DateTime value={new Date()} locale="ja-JP" />

  <Text fontWeight="semibold">de-DE</Text>
  <Format.DateTime value={new Date()} locale="de-DE" />

  <Text fontWeight="semibold">fr-FR</Text>
  <Format.DateTime value={new Date()} locale="fr-FR" />

  <Text fontWeight="semibold">zh-CN</Text>
  <Format.DateTime value={new Date()} locale="zh-CN" />
</Grid>
```

#### Converting to Year

To convert to year, set a value for [year](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#year).

```tsx
<Format.DateTime value={new Date()} year="numeric" />
```

#### Converting to Month

To convert to month, set a value for [month](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#month).

```tsx
<Format.DateTime value={new Date()} month="long" />
```

#### Converting to Day

To convert to day, set a value for [day](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#day).

```tsx
<Format.DateTime value={new Date()} day="2-digit" />
```

#### Converting to Weekday

To convert to weekday, set a value for [weekday](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#weekday).

```tsx
<Format.DateTime value={new Date()} weekday="long" />
```

### Numbers

:::note
`Format.Number` internally uses [Intl.NumberFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat).
:::

#### Changing the Locale

To change the locale, set a value for [locale](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#locales).

```tsx
<Grid templateColumns="auto 1fr" gap="sm">
  <Text fontWeight="semibold">en-US</Text>
  <Format.Number value={1234567.89} locale="en-US" />

  <Text fontWeight="semibold">ja-JP</Text>
  <Format.Number value={1234567.89} locale="ja-JP" />

  <Text fontWeight="semibold">de-DE</Text>
  <Format.Number value={1234567.89} locale="de-DE" />

  <Text fontWeight="semibold">fr-FR</Text>
  <Format.Number value={1234567.89} locale="fr-FR" />

  <Text fontWeight="semibold">zh-CN</Text>
  <Format.Number value={1234567.89} locale="zh-CN" />
</Grid>
```

#### Converting to Currency

To convert to currency, set `"currency"` for [style](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#style).

```tsx
<Grid templateColumns="auto 1fr" gap="sm">
  <Text fontWeight="semibold">USD</Text>
  <Format.Number
    value={1234567.89}
    style="currency"
    currency="USD"
    locale="en-US"
  />

  <Text fontWeight="semibold">EUR</Text>
  <Format.Number
    value={1234567.89}
    style="currency"
    currency="EUR"
    locale="de-DE"
  />

  <Text fontWeight="semibold">JPY</Text>
  <Format.Number
    value={1234567.89}
    style="currency"
    currency="JPY"
    locale="ja-JP"
  />
</Grid>
```

#### Converting to Units

To convert to units, set `"unit"` for [style](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#style).

```tsx
<VStack gap="sm">
  <Format.Number value={100} style="unit" unit="kilogram" />
  <Format.Number value={100} style="unit" unit="celsius" unitDisplay="long" />
  <Format.Number
    value={100}
    style="unit"
    unit="kilometer-per-hour"
    unitDisplay="narrow"
  />
</VStack>
```

#### Converting to Percent

To convert to percent, set `"percent"` for [style](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#style).

```tsx
<VStack gap="sm">
  <Format.Number value={0.45} style="percent" />
  <Format.Number value={0.45} style="percent" minimumFractionDigits={2} />
</VStack>
```

#### Converting Notation

To convert notation, set a value for [notation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#notation).

```tsx
<VStack gap="sm">
  <Format.Number value={1234567.89} notation="standard" />
  <Format.Number value={1234567.89} notation="scientific" />
  <Format.Number value={1234567.89} notation="engineering" />
  <Format.Number value={1234567.89} notation="compact" />
</VStack>
```

#### Controlling Decimal Places

To control the number of decimal places, use [minimumFractionDigits](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#minimumfractiondigits) and [maximumFractionDigits](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#maximumfractiondigits).

```tsx
<VStack gap="sm">
  <Format.Number
    minimumFractionDigits={2}
    maximumFractionDigits={2}
    value={1234.5}
  />
  <Format.Number
    minimumFractionDigits={0}
    maximumFractionDigits={3}
    value={1234.567}
  />
  <Format.Number
    minimumFractionDigits={4}
    maximumFractionDigits={4}
    value={1234}
  />
</VStack>
```

#### Disabling Grouping

To disable grouping, set `false` for [useGrouping](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#usegrouping).

```tsx
<Format.Number value={1234567.89} useGrouping={false} />
```

#### Changing the Sign Display

To change the sign display, set a value for [signDisplay](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#signdisplay).

```tsx
<VStack gap="sm">
  <Format.Number value={1234.5} signDisplay="always" />
  <Format.Number value={-1234.5} signDisplay="exceptZero" />
</VStack>
```

### Bytes

:::note
`Format.Byte` internally uses [Intl.NumberFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat).
:::

#### Automatic Unit Selection

`Format.Byte` automatically selects the most appropriate unit (`byte`, `kB`, `MB`, `GB`, `TB`) based on the byte value size.

```tsx
<VStack gap="sm">
  <Format.Byte value={512} />
  <Format.Byte value={1024} />
  <Format.Byte value={1024 * 1024} />
  <Format.Byte value={1024 * 1024 * 1024} />
  <Format.Byte value={1024 * 1024 * 1024 * 1024} />
</VStack>
```

#### Changing the Locale

To change the locale, set a value for [locale](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#locales).

```tsx
<Grid templateColumns="auto 1fr" gap="sm">
  <Text fontWeight="semibold">en-US</Text>
  <Format.Byte value={1024} locale="en-US" unitDisplay="long" />

  <Text fontWeight="semibold">ja-JP</Text>
  <Format.Byte value={1024} locale="ja-JP" unitDisplay="long" />

  <Text fontWeight="semibold">de-DE</Text>
  <Format.Byte value={1024} locale="de-DE" unitDisplay="long" />

  <Text fontWeight="semibold">fr-FR</Text>
  <Format.Byte value={1024} locale="fr-FR" unitDisplay="long" />

  <Text fontWeight="semibold">zh-CN</Text>
  <Format.Byte value={1024} locale="zh-CN" unitDisplay="long" />
</Grid>
```

#### Unit Format

To convert units, set `unit` to either `"byte"` or `"bit"`. The default is `"byte"`.

```tsx
<Grid templateColumns="auto 1fr" gap="sm">
  <Text fontWeight="semibold">Bytes</Text>
  <Format.Byte value={1024} unit="byte" />

  <Text fontWeight="semibold">Bits</Text>
  <Format.Byte value={1024} unit="bit" />
</Grid>
```

#### Changing the Unit Display

To change the unit display, set a value for [unitDisplay](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#unitdisplay).

```tsx
<Grid templateColumns="auto 1fr" gap="sm">
  <Text fontWeight="semibold">Short</Text>
  <Format.Byte value={1024} unitDisplay="short" />

  <Text fontWeight="semibold">Narrow</Text>
  <Format.Byte value={1024} unitDisplay="narrow" />

  <Text fontWeight="semibold">Long</Text>
  <Format.Byte value={1024} unitDisplay="long" />
</Grid>
```

### Set the Locale for the Entire Application

If you want to set the locale for the entire application, set the `locale` for the `UIProvider`.

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

const App = () => {
  return (
    <UIProvider locale="en-US">
      <Format.Byte value={1024} />
      <Format.Number value={1234567.89} />
    </UIProvider>
  )
}
```

## Props

### Format.Byte

| Prop          | Default   | Type                                                                                                                      | Description                                |
| ------------- | --------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `as`          | -         | `As`                                                                                                                      | The HTML element to render.                |
| `asChild`     | -         | `boolean`                                                                                                                 | Merges its props onto its immediate child. |
| `css`         | -         | `CSSObject \| CSSObject[]`                                                                                                | The CSS object.                            |
| `colorScheme` | -         | `"amber" \| "black" \| "blackAlpha" \| "blue" \| "cyan" \| "danger" \| "emerald" \| "error" \| "flashy" \| "fuchsia" ...` | Set color scheme variables.                |
| `value`       | -         | `number`                                                                                                                  | The byte size to format                    |
| `locale`      | `"en-US"` | `AnyString \| Locale`                                                                                                     | The locale string to use for formatting.   |
| `unit`        | -         | `"bit" \| "byte"`                                                                                                         | The unit granularity to display            |
| `unitDisplay` | -         | `"long" \| "narrow" \| "short"`                                                                                           | The unit display                           |

### Format.DateTime

| Prop          | Default   | Type                                                                                                                      | Description                                |
| ------------- | --------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `as`          | -         | `As`                                                                                                                      | The HTML element to render.                |
| `asChild`     | -         | `boolean`                                                                                                                 | Merges its props onto its immediate child. |
| `css`         | -         | `CSSObject \| CSSObject[]`                                                                                                | The CSS object.                            |
| `colorScheme` | -         | `"amber" \| "black" \| "blackAlpha" \| "blue" \| "cyan" \| "danger" \| "emerald" \| "error" \| "flashy" \| "fuchsia" ...` | Set color scheme variables.                |
| `value`       | -         | `Date`                                                                                                                    | The date time to format                    |
| `locale`      | `"en-US"` | `AnyString \| Locale`                                                                                                     | The locale string to use for formatting.   |

### Format.Number

| Prop          | Default   | Type                                                                                                                      | Description                                |
| ------------- | --------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `as`          | -         | `As`                                                                                                                      | The HTML element to render.                |
| `asChild`     | -         | `boolean`                                                                                                                 | Merges its props onto its immediate child. |
| `css`         | -         | `CSSObject \| CSSObject[]`                                                                                                | The CSS object.                            |
| `colorScheme` | -         | `"amber" \| "black" \| "blackAlpha" \| "blue" \| "cyan" \| "danger" \| "emerald" \| "error" \| "flashy" \| "fuchsia" ...` | Set color scheme variables.                |
| `value`       | -         | `number`                                                                                                                  | The numeric value to be formatted.         |
| `locale`      | `"en-US"` | `AnyString \| Locale`                                                                                                     | The locale string to use for formatting.   |