> ## Documentation Index
> Fetch the complete documentation index at: https://buttercms.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Number field

> Detailed explanation of the Number field in ButterCMS, including input, output, configuration options, and use cases

The **Number** field only accepts number entries (integers and decimals) and returns a JSON number in the API, which makes it perfect for prices, quantities, and dimensions.

{/* IMAGE_SOURCE: file_path="knowledge-base/content-modeling-basics/content-fields.md" */}

![Number field configuration in ButterCMS](https://cdn.buttercms.com/hEhTiMInTnzYdNGNbO0w)

<Warning>
  Always use the Number field for numeric data instead of Short Text. This ensures proper type validation and returns the correct data type in your API response.
</Warning>

## Field at a glance

### Input and output

<CardGroup cols={2}>
  <Card title="Input type" icon="arrow-right-to-bracket">
    Numbers (integers, decimals, and floats)
  </Card>

  <Card title="API output" icon="arrow-right-from-bracket">
    `number`
  </Card>
</CardGroup>

### API response example

```json theme={null}
"temperature": -15.5
```

### Field configuration options

<Tip>
  Use help text and default values to guide your content teams.
</Tip>

| `Option Name` | `Type`  | `Function`                        |
| ------------- | ------- | --------------------------------- |
| Required?     | boolean | Make field required to save page  |
| Default value | string  | Set a default value for the field |

## Common use cases

E-commerce

* Product prices
* Stock quantities
* Shipping weights
* Discount percentages
* Order totals

Events and scheduling

* Event capacity
* Number of attendees
* Duration in minutes/hours
* Room numbers

Content metrics

* Read time estimates
* View counts
* Rating scores
* Sort order/priority

Configuration values

* Display order
* Maximum items to show
* Pagination limits

## Handling different number types

### Integers

Number fields support integers (numbers without a decimal), including both zero and negative integers.

```json theme={null}
{
  "quantity": 100,
  "rating": 5,
  "order_number": 12345
}
```

```json theme={null}
{
  "wind_speed": 0,
  "temperature": -5,
}
```

### Decimals (floats)

Number fields support decimal/float values with no restriction on the number of places after the decimal. This includes both 0.00 and negative numbers.

```json theme={null}
{
  "price": 29.99,
  "discount_percentage": 0.5,
  "weight_kg": 2.75,
  "temperature": -15.5
}
```

### Large numbers

Be aware of JavaScript's number precision limits for very large numbers:

```javascript theme={null}
// Safe integer range in JavaScript
console.log(Number.MAX_SAFE_INTEGER); // 9007199254740991

// For larger numbers, consider storing as strings
// and using BigInt in your application
```

## Number field vs. Short Text for numbers

<Tip>
  Always use the Number field for numeric data instead of Short Text. This ensures proper type validation and returns the correct data type in your API response.
</Tip>

```json theme={null}
// Number field
{ "price": 29.99 }

// Short Text (incorrect approach)
{ "price": "29.99" }
```

| Aspect              | Number Field                | Short Text          |
| ------------------- | --------------------------- | ------------------- |
| **API output**      | `number`                    | `"string"`          |
| **Validation**      | Built-in numeric validation | Manual regex needed |
| **Math operations** | Works directly              | Requires parsing    |
| **Sorting**         | Correct numeric sort        | Alphabetical sort   |

## Best practices

### Prices

* Consider your currency's decimal precision
* Use help text to specify the expected currency

### Quantities

* Use integers only (no decimals)
* Use help text to clarify expected values

### Percentages

* Clarify in help text whether to enter as `15` or `0.15` for 15%

### Ratings

* Consider using a dropdown for consistent values

## Working with numbers in your application

### JavaScript example

```javascript theme={null}
// Fetching and using number fields
const butter = require('buttercms')('your-api-key');

const response = await butter.page.retrieve('*', 'product-page');
const product = response.data.data.fields;

// Numbers are returned as actual numbers, not strings
const price = product.price; // 29.99 (number)
const quantity = product.stock_quantity; // 100 (number)

// Format for display
const formattedPrice = new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD'
}).format(price); // "$29.99"

// Math operations work directly
const total = price * quantity; // 2999
```

### Python example

```python theme={null}
from butter_cms import ButterCMS

client = ButterCMS('your-api-key')

response = client.pages.get('*', 'product-page')
product = response['data']['fields']

# Numbers are Python floats/ints
price = product['price']  # 29.99
quantity = product['stock_quantity']  # 100

# Format for display
formatted_price = f"${price:,.2f}"  # "$29.99"

# Math operations
total = price * quantity  # 2999.0
```