---
title: Number field
description: Display a number as a count, a decimal, a currency amount, a percentage, or a progress against a total.
---

This reference explains how to:

- Declare a finite number
- Say what the number is with a format
- Supply a fixed currency code or total, or read one from each record
- Set an editor step

## Overview

A number field declares a finite numeric value. Use a format to say what the
number is. The renderer decides how to present it, with the locale supplied by
the host. It uses the JavaScript runtime locale when the host does not supply
one.

## API

```ts
fields.number<Name extends string>(
  name: Name,
  options?: NumberFieldOptions
): NumberFieldBuilder<Name>
```

| Option           | Input                                              | Result                                       |
| ---------------- | -------------------------------------------------- | -------------------------------------------- |
| `label`          | `string`                                           | Sets the text shown for the field.           |
| `description`    | `string`                                           | Adds supporting text for the label.          |
| `format`         | `integer`, `percent`, `currency`, or `progress`    | Says what the number is.                     |
| `currency`       | An ISO 4217 code, with `format: 'currency'`        | Fixes the code for every record.             |
| `max`            | `number`, with `format: 'progress'`                | Fixes the total for every record.            |
| `displayVariant` | `compact`                                          | Draws the figure as 12.5K instead of 12,480. |
| `decimals`       | `number`, with no format, `percent`, or `currency` | Pins the fraction digits the display shows.  |
| `step`           | `number`                                           | Sets the increment used by an editor.        |

`configure(options)` returns a configured clone. `configure(callback)` reads
the format's options from each record. `clone()` returns an independent copy
with the same options.

If you do not set a format, the number is a plain decimal number.

## Basic number field

<BacklitExample path="fields/number/basic" view="detail" />

## Description

Use a description when the value needs a unit, rule, or other supporting
information that does not belong in the label.

<BacklitExample path="fields/number/description" view="detail" />

## Formats

Number supports four formats. A format says what the number is. A fixed format sends a number. Per-record currency or progress options
send an object with `value` and the resolved `currency` or `max`.

| Format     | Use                                                     | Options    |
| ---------- | ------------------------------------------------------- | ---------- |
| `integer`  | A whole count.                                          |            |
| `percent`  | A fraction, where `0.15` represents 15 percent.         |            |
| `currency` | An amount of money.                                     | `currency` |
| `progress` | A count against a total, drawn as a bar with the share. | `max`      |

An option is accepted only with its format. A format's option is fixed for
every record when you set it on the field, or read from each record through a
callback:

```ts title="app/resources/products.ts"
import { fields } from '@backlit/sdk'

const price = fields.number('price', {
  format: 'currency',
  currency: 'USD',
})

const convertedPrice = fields
  .number('convertedPrice', { format: 'currency' })
  .configure((row: { currencyCode: string }) => ({
    currency: row.currencyCode,
  }))

const shipped = fields
  .number('shipped', { format: 'progress' })
  .configure((row: { ordered: number }) => ({ max: row.ordered }))
```

A code must contain three uppercase letters, such as `USD`, `EUR`, or `BRL`. A
total must be a finite number of zero or more. Backlit reports a defect when a
record supplies an invalid value, or supplies an option for a format the field
does not declare. A progress with no total draws the count alone.

<BacklitExample path="fields/number/formats" view="detail" />

## Decimals

A currency strips its fraction when the amount is whole and keeps it otherwise:
1200 shows as $1,200, and 1200.5 as $1,200.50. An integer and a progress count
show no fraction. A percent shows at most one decimal.

Set `decimals` to pin the fraction of a plain number, a percent, or a currency.
An integer and a progress count have no fraction and do not take it.
`decimals: 2` shows two digits on every value. `decimals: 0` rounds to a whole
number: 412222.89 shows as $412,223.

```ts title="app/resources/orders.ts"
import { fields } from '@backlit/sdk'

const total = fields.number('total', {
  format: 'currency',
  currency: 'USD',
  decimals: 2,
})
```

## Compact figures

The `compact` display variant draws a figure in the locale's compact notation
with at most one decimal: 12,480 as 12.5K, 1,200,000 as 1.2M. It composes with
any format. A compact currency keeps its symbol, and a compact progress draws
both counts compact.

```ts title="app/resources/publication.ts"
import { fields } from '@backlit/sdk'

const subscribers = fields.number('subscribers', {
  format: 'integer',
  displayVariant: 'compact',
})
```

## Step

The step tells an editing control how much to add or subtract for one change.
When you do not set it, a field with `decimals` steps by that unit, one for
zero and a hundredth for two, and an `integer` field steps by one. The step
does not change the read-only value.

<BacklitExample path="fields/number/step" view="detail" />

## Clone

Use `configure` to reuse a number field with different options. It does not
change the source field.

<BacklitExample path="fields/number/clone" view="detail" />

## All options

You can use a label, description, format, and step on the same number field.

<BacklitExample path="fields/number/all_options" view="detail" />