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

# Number Field

> Numeric values with formatting for amounts, quantities, and calculations

The Number field captures numeric values — integers or decimals — with optional formatting and validation. Number fields enable calculations, comparisons, and numeric operations within automations and data processing.

Use Number fields whenever you need to perform mathematical operations, apply min/max validation, or format values with prefix/suffix. Number fields are essential for quantities, ages, scores, and any data that requires numeric processing.

## When to Use

**Use Number fields for:**

* Quantities (items, count, volume)
* Ages and years
* Scores and ratings
* Percentages and ratios
* Measurements (weight, height, distance)
* Identifiers that are purely numeric (account numbers, IDs)
* Calculated values

**Consider alternatives:**

* Use **Currency** for monetary amounts (prices, costs, revenues, claims)
* Use **Text** for alphanumeric IDs (contain letters)
* Use **Choices** for predefined numeric ranges (age groups, price tiers)
* Use **Date** for years that represent dates

## Configuration Options

| Option        | Description                     | Type   | Default          | Example                     |
| ------------- | ------------------------------- | ------ | ---------------- | --------------------------- |
| `key`         | Unique identifier               | String | Required         | `number_of_employees`       |
| `name`        | Display label                   | String | Required         | "Number of Employees"       |
| `description` | Help text for users             | String | Optional         | "Total full-time employees" |
| `min`         | Minimum allowed value           | Number | None             | `0`                         |
| `max`         | Maximum allowed value           | Number | None             | `1000000`                   |
| `decimals`    | Number of decimal places        | Number | None             | `2`                         |
| `prefix`      | Text displayed before the value | String | None             | `$`                         |
| `suffix`      | Text displayed after the value  | String | None             | `kg`                        |
| `placeholder` | Hint text shown in empty field  | String | None             | "Enter a number"            |
| `visibility`  | Display setting                 | String | `always-visible` | `hide-when-empty`           |
| `section`     | Section this field belongs to   | String | None             | Section UUID                |

## Examples

### Basic Integer

Collect a simple count:

```json theme={null}
{
  "key": "number_of_employees",
  "type": "number",
  "name": "Number of Employees",
  "description": "Total full-time employees",
  "min": 1
}
```

### Decimal Value

Collect precise measurements:

```json theme={null}
{
  "key": "weight_kg",
  "type": "number",
  "name": "Weight (kg)",
  "description": "Weight in kilograms",
  "decimals": 2,
  "suffix": "kg",
  "min": 0
}
```

### Percentage with Prefix/Suffix

Collect a percentage value:

```json theme={null}
{
  "key": "completion_percentage",
  "type": "number",
  "name": "Completion Percentage",
  "description": "Project completion percentage",
  "suffix": "%",
  "min": 0,
  "max": 100,
  "decimals": 1
}
```

## Validation

Number fields enforce numeric validation automatically:

### Type Validation

* Only numeric values accepted
* Decimals allowed based on `decimals` configuration
* Non-numeric input rejected

### Range Validation

* `min` - Minimum allowed value (inclusive)
* `max` - Maximum allowed value (inclusive)
* User cannot enter values outside range

### Decimal Validation

* `decimals` defines maximum decimal places allowed
* For integers: omit `decimals` or set to `0`
* For precise values: set `decimals` to the required precision (e.g., `2`)

<Info>
  Validation happens when users fill the field. Existing data or API imports are
  not automatically validated.
</Info>

## Best Practices

**Always use Number for numeric data:**

* Don't store numbers as text (prevents calculations)
* Use Number even if you don't need calculations now (future-proofs)
* Enables numeric comparisons in automations

**Set appropriate min/max:**

* Prevents invalid or unrealistic values
* Catches data entry errors
* Useful for regulated fields with limits

**Configure decimals based on needs:**

* Omit `decimals` for counts and quantities
* Use `2` for precise measurements
* Use appropriate precision for your domain

**Use prefix/suffix for display context:**

* Add `suffix: "kg"` for weight fields
* Add `suffix: "%"` for percentage fields
* Helps users understand expected format

**Use Currency for monetary values:**

* Don't use Number with a currency prefix for financial amounts
* The **Currency** field type is purpose-built for monetary values

**Validate reasonably:**

* Don't set overly restrictive min/max
* Consider edge cases (zero values, large amounts)
* Test with realistic data ranges

***

## Related Field Types

<CardGroup cols={2}>
  <Card title="Currency" icon="coins" href="/cases/data_schema/currency">
    Use for monetary amounts with currency formatting
  </Card>

  <Card title="Text" icon="text" href="/cases/data_schema/text">
    Use for alphanumeric IDs and formatted numbers
  </Card>

  <Card title="Choices" icon="circle-dot" href="/cases/data_schema/choices">
    Use for predefined numeric ranges or tiers
  </Card>

  <Card title="Data Schema Overview" icon="sitemap" href="/cases/data_schema">
    Back to Data Schema overview
  </Card>
</CardGroup>