React Data Grid Numeric cell type

React Data GridNumeric cell type

Display, format, sort, and filter numbers correctly by using the numeric cell type.

On this page

Overview

The default cell type in Handsontable is text. The data of a text cell is processed as a string type that corresponds to the value of the text editor's internal <textarea> element. However, there are many cases where you need cell values to be treated as a number type. The numeric cell type allows you to format displayed numbers nicely and sort them correctly.

Numeric cell type demo

In the following demo, multiple columns use the numeric cell type with different formatting styles:

  • Year: Basic numeric formatting
  • Price (USD) and Price (EUR): Currency formatting
  • Distance: Unit formatting (kilometers) with grouping
  • Fuel: Unit formatting (liters) with decimal precision
  • Discount: Percentage formatting
  • Quantity: Decimal formatting with thousands separators

Use the locale selector above the table to see how different locales affect number formatting.

    Use the numeric cell type

    To use the numeric cell type, set the type option to 'numeric':

    // set the numeric cell type for each cell of the entire grid
type={'numeric'},

// set the numeric cell type for each cell of a single column
columns={[{
  type: 'numeric',
}]}

// set the numeric cell type for a single cell
cell={[{
  row: 0,
  col: 0,
  type: 'numeric',
}]}

    Mind that Handsontable doesn't parse strings to numbers. In your data source, make sure to store numeric cell values as numbers, not as strings.

    All positive and negative integers whose magnitude is no greater than 253 (+/- 9007199254740991) are representable in the Number type, i.e., as a safe integer. Any calculations that are performed on bigger numbers won't be calculated precisely, due to JavaScript's limitations.

    Format numbers

    To format the look of numeric values in cell renderers, use the numericFormat option.

    Since Handsontable 17.0, the numericFormat option supports the native Intl.NumberFormat (opens new window) API, which provides better performance and broader browser support without external dependencies.

    The numericFormat option accepts all properties of Intl.NumberFormatOptions (opens new window). The locale is controlled separately via the locale option.

    <HotTable
  columns={[{
    type: 'numeric',
    locale: 'en-US',
    numericFormat: {
      style: 'currency',
      currency: 'USD',
      minimumFractionDigits: 2
    }
  }, {
    type: 'numeric',
    locale: 'de-DE',
    numericFormat: {
      style: 'currency',
      currency: 'EUR',
      minimumFractionDigits: 2
    }
  }]}
/>

    Common formatting styles:

    • Currency: Use style: 'currency' with a currency property (e.g., 'USD', 'EUR', 'PLN')
    • Decimal: Use style: 'decimal' with useGrouping: true for thousands separators
    • Percent: Use style: 'percent' for percentage formatting
    • Unit: Use style: 'unit' with a unit property (e.g., 'kilometer', 'liter')

    Available options:

    Style options:

    Property Possible values Description
    style 'decimal' (default), 'currency', 'percent', 'unit' The formatting style to use
    currency ISO 4217 currency codes (e.g., 'USD', 'EUR', 'PLN') Required when style is 'currency'
    currencyDisplay 'symbol' (default), 'narrowSymbol', 'code', 'name' How to display the currency
    currencySign 'standard' (default), 'accounting' Use parentheses for negative values in accounting format
    unit Unit identifiers (e.g., 'kilometer', 'liter') Required when style is 'unit'
    unitDisplay 'short' (default), 'narrow', 'long' How to display the unit

    Notation options:

    Property Possible values Description
    notation 'standard' (default), 'scientific', 'engineering', 'compact' The formatting notation
    compactDisplay 'short' (default), 'long' Display style for compact notation (e.g., 1.5M vs 1.5 million)

    Sign and grouping options:

    Property Possible values Description
    signDisplay 'auto' (default), 'never', 'always', 'exceptZero', 'negative' When to display the sign
    useGrouping true, false (default), 'always', 'auto', 'min2' Whether to use grouping separators (e.g., 1,000)

    Digit options:

    Property Possible values Description
    minimumIntegerDigits 1 to 21 Minimum number of integer digits (pads with zeros)
    minimumFractionDigits 0 to 100 Minimum number of fraction digits
    maximumFractionDigits 0 to 100 Maximum number of fraction digits
    minimumSignificantDigits 1 to 21 Minimum number of significant digits
    maximumSignificantDigits 1 to 21 Maximum number of significant digits

    Rounding options:

    Property Possible values Description
    roundingMode 'halfExpand' (default), 'ceil', 'floor', 'expand', 'trunc', 'halfCeil', 'halfFloor', 'halfTrunc', 'halfEven' Rounding algorithm
    roundingPriority 'auto' (default), 'morePrecision', 'lessPrecision' Priority between fraction and significant digits
    roundingIncrement 1, 2, 5, 10, 20, 25, 50, 100, 200, 250, 500, 1000, 2000, 2500, 5000 Increment for rounding (e.g., nickel rounding)
    trailingZeroDisplay 'auto' (default), 'stripIfInteger' Whether to strip trailing zeros for integers

    Locale options:

    Property Possible values Description
    localeMatcher 'best fit' (default), 'lookup' Locale matching algorithm
    numberingSystem 'latn', 'arab', 'hans', 'deva', 'thai', etc. Numbering system to use

    For a complete reference, see the numericFormat API documentation or MDN: Intl.NumberFormat (opens new window).

    Using Numbro.js format options (deprecated)

    Deprecated

    The numericFormat.pattern and numericFormat.culture options (numbro.js-based formatting) are deprecated and will be removed in the next major release. Migrate to the Intl.NumberFormat API shown above.

    The following demo uses the deprecated numbro.js format options. These options are still supported but will be removed in version 18.0.

    In the following demo, columns Price in Japan and Price in Turkey use two different numericFormat configurations.

      Deprecated options:

      Option Description Replacement
      pattern Numbro.js format pattern (e.g., '0,0.00 $') Use Intl.NumberFormat options (see above)
      culture Numbro.js locale identifier (e.g., 'en-US') Use the locale option

      Migration example:

      // Before (deprecated)
numericFormat: {
  pattern: '0,0.00 $',
  culture: 'en-US'
}

// After (recommended)
locale: 'en-US',
numericFormat: {
  style: 'currency',
  currency: 'USD',
  minimumFractionDigits: 2
}

      For detailed migration instructions and more examples, see the migration guide.

      Editor behavior

      Mind that the numericFormat option doesn't change the way numbers are presented or parsed by the cell editor. When you edit a numeric cell:

      • Regardless of the numericFormat configuration, the number that's being edited displays its decimal separator as a period (.), and has no thousands separator or currency symbol.
        For example, during editing $7,000.02, the number displays as 7000.02.
      • You can enter a decimal separator either with a period (.), or with a comma (,).
      • You can't enter a thousands separator. After you finish editing the cell, the thousands separator is added automatically, based on your numericFormat configuration.