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.

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.

Field at a glance

Input and output

Input type

Numbers (integers, decimals, and floats)

API output

number

API response example

"temperature": -15.5

Field configuration options

Use help text and default values to guide your content teams.

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.

{
  "quantity": 100,
  "rating": 5,
  "order_number": 12345
}

{
  "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.

{
  "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:

// 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

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.

// 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

// 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

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