Number Field - Payload

The Number Field stores and validates numeric entry and supports additional numerical validation and formatting features.

To add a Number Field, set the type to number in your Field Config:

import type { Field } from 'payload'

export const MyNumberField: Field = {
  // ...
  type: 'number', // highlight-line
}

Config Options

Option	Description
`name` *	To be used as the property name when stored and retrieved from the database. More details.
`label`	Text used as a field label in the Admin Panel or an object with keys for each language.
`min`	Minimum value accepted. Used in the default `validation` function.
`max`	Maximum value accepted. Used in the default `validation` function.
`hasMany`	Makes this field an ordered array of numbers instead of just a single number.
`minRows`	Minimum number of numbers in the numbers array, if `hasMany` is set to true.
`maxRows`	Maximum number of numbers in the numbers array, if `hasMany` is set to true.
`unique`	Enforce that each entry in the Collection has a unique value for this field. This creates a database-level unique index on the field's path. More details.
`index`	Build an index for this field to produce faster queries. Set this field to `true` if your users will perform queries on this field's data often.
`validate`	Provide a custom validation function that will be executed on both the Admin Panel and the backend. More details.
`saveToJWT`	If this field is top-level and nested in a config supporting Authentication, include its data in the user JWT.
`hooks`	Provide Field Hooks to control logic for this field. More details.
`access`	Provide Field Access Control to denote what users can see and do with this field's data. More details.
`hidden`	Restrict this field's visibility from all APIs entirely. Will still be saved to the database, but will not appear in any API or the Admin Panel.
`defaultValue`	Provide data to be used for this field's default value. More details.
`localized`	Enable localization for this field. Requires localization to be enabled in the Base config.
`required`	Require this field to have a value.
`admin`	Admin-specific configuration. More details.
`custom`	Extension point for adding custom data (e.g. for plugins)
`typescriptSchema`	Override field type generation with providing a JSON schema
`virtual`	Provide `true` to disable field in the database, or provide a string path to link the field with a relationship. See Virtual Fields

* An asterisk denotes that a property is required.

Admin Options

To customize the appearance and behavior of the Number Field in the Admin Panel, you can use the admin option:

import type { Field } from 'payload'

export const MyNumberField: Field = {
  // ...
  admin: {
    // highlight-line
    // ...
  },
}

The Number Field inherits all of the default admin options from the base Field Admin Config, plus the following additional options:

Property	Description
`step`	Set a value for the number field to increment / decrement using browser controls.
`placeholder`	Set this property to define a placeholder string for the field.
`autoComplete`	Set this property to a string that will be used for browser autocomplete.

Example

import type { CollectionConfig } from 'payload'

export const ExampleCollection: CollectionConfig = {
  slug: 'example-collection',
  fields: [
    {
      name: 'age', // required
      type: 'number', // required
      required: true,
      admin: {
        step: 1,
      },
    },
  ],
}

Custom Components

Field

Server Component

tsx

import type React from 'react'
import { NumberField } from '@payloadcms/ui'
import type { NumberFieldServerComponent } from 'payload'

export const CustomNumberFieldServer: NumberFieldServerComponent = ({
  clientField,
  path,
  schemaPath,
  permissions,
}) => {
  return (
    <NumberField
      field={clientField}
      path={path}
      schemaPath={schemaPath}
      permissions={permissions}
    />
  )
}

Client Component

tsx

'use client'
import React from 'react'
import { NumberField } from '@payloadcms/ui'
import type { NumberFieldClientComponent } from 'payload'

export const CustomNumberFieldClient: NumberFieldClientComponent = (props) => {
  return <NumberField {...props} />
}

Label

Server Component

tsx

import React from 'react'
import { FieldLabel } from '@payloadcms/ui'
import type { NumberFieldLabelServerComponent } from 'payload'

export const CustomNumberFieldLabelServer: NumberFieldLabelServerComponent = ({
  clientField,
  path,
}) => {
  return (
    <FieldLabel
      label={clientField?.label || clientField?.name}
      path={path}
      required={clientField?.required}
    />
  )
}

Client Component

tsx

'use client'
import React from 'react'
import { FieldLabel } from '@payloadcms/ui'
import type { NumberFieldLabelClientComponent } from 'payload'

export const CustomNumberFieldLabelClient: NumberFieldLabelClientComponent = ({
  field,
  path,
}) => {
  return (
    <FieldLabel
      label={field?.label || field?.name}
      path={path}
      required={field?.required}
    />
  )
}