Number Formatting

Updated on Jun 16, 2026

Applying different formats to a number changes the appearance of the number. A format does not change the value it is applied to. It only changes the way the value appears in the cell. The following sections explain how to use the predefined number formats.

For more information on how to create your own number format or modify one of the predefined types, see the Format Codes article.

Available Number Formats

The document model exposes the following categories of predefined formats:

• General format: The default number format applied to a number. Typically, numbers formatted with this format are displayed exactly as they are typed. If the number has 12 or more digits, the General number format applies scientific notation.

• Number format: Used for the general display of numbers. The format specifies the number of decimal places and indicates whether a thousands separator is used. Additionally, the Number format specifies how negative numbers are displayed.

• Currency format: Used for general monetary values. Numbers in this format are displayed with the default currency symbol. The format specifies the number of decimal places and indicates whether a thousands separator is used. Additionally, the Currency format specifies how negative numbers are displayed.

• Accounting format: Used for monetary values. Unlike the Currency format, it aligns the currency symbols and the values in a column. The format specifies the number of decimal places used.

• Date format: Treats a number as date and time serial number and displays it as a date value.

• Time format: Treats a number as date and time serial number and displays it as a time value.

• Percentage format: Displays the cell value multiplied by 100 and followed by a percent (%) symbol. The format specifies the number of decimal places used.

• Fraction format: Displays a cell value as a fraction.

• Scientific format: Displays a number in scientific notation. The number is transformed into a real number followed by E+n, where E (which stands for Exponent) multiplies the real number by 10 to the nth power. For example, a 2-decimal scientific format displays 12345678901 as 1.23E+10, which is 1.23 times 10 to the 10th power. The format specifies the number of decimal places used.

• Text format: Treats the content of a cell as text and displays the content exactly as it is typed.

• Special format: Designed to display numbers as postal codes (ZIP Code), phone numbers, or Social Security numbers.

• Custom format: Allows modifying any of the predefined formats. The format also allows creating a new custom number format that is added to the list of number format codes. For more information, see the Format Codes article.

The Date, Time, and Currency formats are influenced by your OS regional settings. For more information, see Localization.

Applying a Number Format

The number format is represented by the CellValueFormat class. You can set it to a given CellSelection object through its SetFormat() method.

When working with CellValueFormat, keep in mind that its constructor accepts a culture-dependent format and converts it to culture-independent format using the current thread format settings (for example, in Bulgarian culture a format passed as 0,00 is converted to 0.00).

The following examples demonstrate how to apply a predefined format to a CellSelection:

Example 1: Apply General Format

C#

CellValueFormat generalFormat = new CellValueFormat("General");

CellSelection cellSelectionA1 = worksheet.Cells[new CellIndex(0, 0)];
cellSelectionA1.SetValue(1234.56789);
cellSelectionA1.SetFormat(generalFormat);

Example 1 produces the following result:

Example 2: Apply Number Format

C#

CellValueFormat numberFormat = new CellValueFormat("0.00");

CellSelection cellSelectionA1 = worksheet.Cells[new CellIndex(0, 0)];
cellSelectionA1.SetValue(1234.56789);
cellSelectionA1.SetFormat(numberFormat);

Example 2 produces the following result:

Example 3: Apply Currency Format

C#

CellValueFormat currencyFormat = new CellValueFormat("$#,##0.00");

CellSelection cellSelectionA1 = worksheet.Cells[new CellIndex(0, 0)];
cellSelectionA1.SetValue(1234.56789);
cellSelectionA1.SetFormat(currencyFormat);

Example 3 produces the following result:

Example 4: Apply Accounting Format

C#

CellValueFormat accountingFormat = new CellValueFormat("_($* #,##0.00_);_($* (#,##0.00);_($* \" - \"??_);_(@_)");

CellSelection cellSelectionA1 = worksheet.Cells[new CellIndex(0, 0)];
cellSelectionA1.SetValue(1234.56789);
cellSelectionA1.SetFormat(accountingFormat);

Example 4 produces the following result:

Example 5: Apply Date Format

C#

CellValueFormat dateFormat = new CellValueFormat("m/d/yyyy");

CellSelection cellSelectionA1 = worksheet.Cells[new CellIndex(0, 0)];
cellSelectionA1.SetValue(1234.56789); // OR cellSelectionA1.SetValue(new DateTime(1903, 5, 18, 13, 37, 46));
cellSelectionA1.SetFormat(dateFormat);

Example 5 produces the following result:

To show milliseconds in Date Format, modify the predefined format as follows: "m/d/yyyy HH:mm:ss.SSS". For more information on how to create your own number format or modify one of the predefined types, see the Format Codes article.

Example 6: Apply Time Format

C#

CellValueFormat timeFormat = new CellValueFormat("h:mm:ss AM/PM");

CellSelection cellSelectionA1 = worksheet.Cells[new CellIndex(0, 0)];
cellSelectionA1.SetValue(1234.56789); // OR cellSelectionA1.SetValue(new DateTime(1903, 5, 18, 13, 37, 46));
cellSelectionA1.SetFormat(timeFormat);

Example 6 produces the following result:

To show milliseconds in Time Format, modify the predefined format as follows: "HH:mm:ss.SSS". For more information on how to create your own number format or modify one of the predefined types, see the Format Codes article.

Example 7: Apply Percentage Format

C#

CellValueFormat percentageFormat = new CellValueFormat("0.00%");

CellSelection cellSelectionA1 = worksheet.Cells[new CellIndex(0, 0)];
cellSelectionA1.SetValue(1234.56789);
cellSelectionA1.SetFormat(percentageFormat);

Example 7 produces the following result:

Example 8: Apply Fraction Format

C#

CellValueFormat fractionFormat = new CellValueFormat("# ?/?");

CellSelection cellSelectionA1 = worksheet.Cells[new CellIndex(0, 0)];
cellSelectionA1.SetValue(1234.56789);
cellSelectionA1.SetFormat(fractionFormat);

Example 8 produces the following result:

Example 9: Apply Scientific Format

C#

CellValueFormat scientificFormat = new CellValueFormat("0.00E+00");

CellSelection cellSelectionA1 = worksheet.Cells[new CellIndex(0, 0)];
cellSelectionA1.SetValue(1234.56789);
cellSelectionA1.SetFormat(scientificFormat);

Example 9 produces the following result:

Example 10: Apply Text Format

C#

CellValueFormat textFormat = new CellValueFormat("@");

CellSelection cellSelectionA1 = worksheet.Cells[new CellIndex(0, 0)];
cellSelectionA1.SetValue(1234.56789);
cellSelectionA1.SetFormat(textFormat);

Example 10 produces the following result:

Example 11: Apply Special Format

C#

CellValueFormat specialFormat = new CellValueFormat("00000-0000");

CellSelection cellSelectionA1 = worksheet.Cells[new CellIndex(0, 0)];
cellSelectionA1.SetValue(1234.56789);
cellSelectionA1.SetFormat(specialFormat);

Example 11 produces the following result:

Example 12: Apply Custom Format

C#

CellValueFormat specialFormat = new CellValueFormat("[Green]$#,##0_);[Red]$(#,##0);\"zero\";[Blue]\"Text: \" @");

CellSelection cellSelectionA1 = worksheet.Cells[new CellIndex(0, 0)];
cellSelectionA1.SetValue(123456789);
cellSelectionA1.SetFormat(specialFormat);

CellSelection cellSelectionB1 = worksheet.Cells[new CellIndex(0, 1)];
cellSelectionB1.SetValueAsText("Progress");
cellSelectionB1.SetFormat(specialFormat);

CellSelection cellSelectionA2 = worksheet.Cells[new CellIndex(1, 0)];
cellSelectionA2.SetValue(0);
cellSelectionA2.SetFormat(specialFormat);

CellSelection cellSelectionB2 = worksheet.Cells[new CellIndex(1, 1)];
cellSelectionB2.SetValue(-1234.56789);
cellSelectionB2.SetFormat(specialFormat);

Example 12 produces the following result:

For more information on how to create your own number format or modify one of the predefined types, see the Format Codes article.

Retrieving a Number Format

You can retrieve the number format of any cell selection through the GetFormat() method of the CellSelection class. The method returns an object of type RangePropertyValue<CellValueFormat>, which exposes two properties:

• IsIndeterminate: Determines if the CellValueFormat is consistent among all cells in the specified CellSelection. If the CellValueFormat is one and the same for all cells, IsIndeterminate is set to false. If the CellValueFormat varies throughout the cells in the CellSelection, the IsIndeterminate property is set to true and the Value property of the RangePropertyValue<T> object is set to its default value.

• Value: Holds the CellValueFormat for the cells. If the IsIndeterminate property is set to false, Value contains the CellValueFormat of the whole CellSelection region. If the IsIndeterminate property is set to true, the CellValueFormat is not the same for all cells in the CellSelection and the Value property is set to the default CellValueFormat.

Example 13 demonstrates how to get the number format of cell A1:

Example 13: Get Number Format

C#

CellSelection cellSelectionA1 = worksheet.Cells[new CellIndex(0, 0)];

CellValueFormat cellSelectioA1Format = cellSelectionA1.GetFormat().Value;