New to Telerik Document Processing? Start a free 30-day trial

Cell Value Types

Updated on Jun 12, 2026

Use this article to understand how the Value property works in the RadSpreadProcessing document model and which value types a cell can store. It explains the ICellValue abstraction, the supported concrete value types, and the most common ways to set, read, and format cell values.

Working with the Value Property of Cells

Cells are the atomic data units of a worksheet, so the Value property is one of the most frequently used cell members. The property is of type ICellValue, which is implemented by these five concrete types:

EmptyCellValue
BooleanCellValue
NumberCellValue
FormulaCellValue
TextCellValue

In most scenarios, you start by creating a CellSelection that points to a single cell or a cell range. The Value property then exposes three common operations:

SetValue()
GetValue()
ClearValue()

SetValue() provides multiple overloads, so you can pass a double, string, bool, DateTime, or an ICellValue instance directly.

Key ICellValue Members

The ICellValue interface exposes several members that are useful when you need to inspect or format a cell value:

RawValue: Stores the entered string value rather than the displayed result. For example, if you enter =1+2, the cell value becomes FormulaCellValue, the displayed result is 3, and RawValue remains =1+2.
ValueType and ResultValueType: Return CellValueType values that describe the stored value and the calculated result. For example, a formula with RawValue equal to =1+2 has ValueType equal to Formula and ResultValueType equal to Number.
GetValueAsString() and GetResultValueAsString(): Return formatted string representations of the cell value or its result and require a CellValueFormat argument.

Quick Reference for Supported Value Types

Value type	Stores	Typical input methods
`EmptyCellValue`	No value	`ClearValue()`
`BooleanCellValue`	`true` or `false`	`SetValue(bool)`, `CellValueFactory.Create(bool)`
`NumberCellValue`	Numeric values, including dates	`SetValue(double)`, `SetValue(DateTime)`, `SetValue(string)` when parsing succeeds
`FormulaCellValue`	Spreadsheet formulas	`SetValue(string)` with `=`, `CellValueFactory.Create(...)`, `SetValueAsFormula(string)`
`TextCellValue`	Text strings	`SetValue(string)`, text cell format, `SetValueAsText(string)`

How to Get a Formatted Cell Value

Excel number formats differ from .NET formats. To get the correctly formatted cell value, first read the number format by using CellSelection.GetFormat().Value, and then pass the retrieved CellValueFormat to ICellValue.GetResultValueAsString().

The proper way to get a formatted cell value is to read the number format first through CellSelection.GetFormat().Value and then pass that CellValueFormat to ICellValue.GetResultValueAsString(). This approach also calculates formulas contained in the cell. For more information, see Number Formatting.

Example: Get a Formatted Cell Value

CellSelection cell = worksheet.Cells[rowIndex, columnIndex];
ICellValue cellValue = cell.GetValue().Value;
CellValueFormat cellFormat = cell.GetFormat().Value;
string formattedValue = cellValue.GetResultValueAsString(cellFormat);

Set and Read Cell Values

Example 1 sets the value of cell A1 to Total.

Example 1: Set a String Value

Workbook workbook = new Workbook();
Worksheet worksheet = workbook.Worksheets.Add();

worksheet.Cells[0, 0].SetValue("Total");

Another option is to use the Create() method of CellValueFactory to produce an ICellValue instance and then pass that instance to SetValue(ICellValue). Like SetValue(), Create() provides overloads for common value types such as string, double, and bool.

Example 2 creates NumberCellValue with value 3.14 and assigns it to cell A1.

Example 2: Create NumberCellValue

Workbook workbook = new Workbook();
Worksheet worksheet = workbook.Worksheets.Add();

ICellValue value = CellValueFactory.Create(3.14);
worksheet.Cells[0, 0].SetValue(value);

If you retrieve the value of cell A1, GetValue() returns NumberCellValue with RawValue equal to 3.14 and both ValueType and ResultValueType equal to Number.

Example 3 retrieves the value created in Example 2.

Example 3: Retrieve a Cell Value

RangePropertyValue<ICellValue> rangeValue = worksheet.Cells[0, 0].GetValue();
ICellValue value = rangeValue.Value;

How RangePropertyValue Works

GetValue() does not return ICellValue directly. Instead, it returns RangePropertyValue<ICellValue>, which is used to determine whether the selected cell range contains a single consistent value.

If you retrieve the value of a range such as A1:B2 and the cells do not all share the same value, RangePropertyValue<ICellValue> reports that the range is not homogeneous.

The class exposes these two key properties:

IsIndeterminate: Indicates whether the Value property is consistent across the selected cells. If all cells have the same value, IsIndeterminate is false. If values differ, it is true.
Value: Holds the common ICellValue for the range when IsIndeterminate is false. If the range contains different values, Value falls back to the default EmptyCellValue.

Example 4: Use IsIndeterminate and Value

Workbook workbook = new Workbook();
Worksheet worksheet = workbook.Worksheets.Add();

worksheet.Cells[0, 0].SetStyleName("Good");
worksheet.Cells[0, 1].SetStyleName("Bad");

RangePropertyValue<string> cell00Value = worksheet.Cells[0, 0].GetStyleName();
//cell at [0, 0] cell00Value.IsIndeterminate is False, cell00Value.Value is Good

RangePropertyValue<string> cell01Value = worksheet.Cells[0, 1].GetStyleName();
//cell at [0, 0] cell01Value.IsIndeterminate is False, cell01Value.Value is Bad

RangePropertyValue<string> twoCellsValue = worksheet.Cells[0, 0, 0, 1].GetStyleName();
//cells at [0, 0, 0, 1] twoCellsValue.IsIndeterminate is True, twoCellsValue.Value is Normal

Empty Cell Value

EmptyCellValue is the default cell value type. When you add an empty worksheet to a workbook, all cells initially contain EmptyCellValue. Its RawValue is an empty string and its ValueType is Empty.

If a cell already contains another value, clear it by using ClearValue().

Example 5: Clear a Value

Workbook workbook = new Workbook();
Worksheet worksheet = workbook.Worksheets.Add();
worksheet.Cells[0, 0].ClearValue();

Boolean Cell Value

BooleanCellValue stores a value of type bool. Its RawValue is either TRUE or FALSE, and its ValueType is Boolean. You can assign it directly by using SetValue(bool).

Example 6 sets cells A1 and B1 to true and false.

Example 6: Set a Boolean Value

Workbook workbook = new Workbook();
Worksheet worksheet = workbook.Worksheets.Add();
worksheet.Cells[0, 0].SetValue(true);
worksheet.Cells[0, 1].SetValue(false);

You can also create BooleanCellValue explicitly by using CellValueFactory.Create() and then passing the result to SetValue().

Example 7: Create BooleanCellValue by Using CellValueFactory

Workbook workbook = new Workbook();
Worksheet worksheet = workbook.Worksheets.Add();
ICellValue booleanCellValueTrue = CellValueFactory.Create(true);
ICellValue booleanCellValueFalse = CellValueFactory.Create(false);
worksheet.Cells[0, 0].SetValue(booleanCellValueTrue);
worksheet.Cells[0, 1].SetValue(booleanCellValueFalse);

Number Cell Value

NumberCellValue stores a value of type double. Its ValueType is Number, and RawValue is the string representation of the internal numeric value.

The displayed cell content can differ from RawValue because of the applied number format. For example, 50.00% and 5.00E-01 can both represent the same internal number 0.5. Dates also use numeric cell values with a date format applied. For example, 16 September 2020 is stored internally as 44090.

Use these SetValue() overloads to create NumberCellValue:

SetValue(double)
SetValue(DateTime)
SetValue(string) when the string can be parsed as a numeric value

If SetValue(string) cannot parse the input as another supported type, it falls back to TextCellValue.

Example 8: Set a Number Cell Value

Workbook workbook = new Workbook();
Worksheet worksheet = workbook.Worksheets.Add();
worksheet.Cells[0, 0].SetValue("1.23");

Date Values

You can use SetValue(string) to assign dates.

Example 9 sets the value of cell A1 to 6 October 1987 in the en-US culture. After assignment, the cell contains NumberCellValue with RawValue equal to 32056. Because the document model detects a date string, it applies a date format automatically.

Example 9: Set a Date as NumberCellValue

Workbook workbook = new Workbook();
Worksheet worksheet = workbook.Worksheets.Add();
worksheet.Cells[0, 0].SetValue("10/06/1987");

Contained double value: 32056 Applied format: m/d/yyyy

If you later access the value from Example 9, you receive its numeric representation, 32056. To convert that value back to a date, use FormatHelper.ConvertDoubleToDateTime() or call GetValueAsString() to get the formatted string.

Example 10: Get a Date Value

ICellValue cellValue = worksheet.Cells[0, 0].GetValue().Value;
CellValueFormat format = worksheet.Cells[0, 0].GetFormat().Value;

string resultAsString = cellValue.GetValueAsString(format);

double rawValueAsNumber = Convert.ToDouble(cellValue.RawValue);
DateTime? resultAsDateTime = FormatHelper.ConvertDoubleToDateTime(rawValueAsNumber).Value.Date;

Formula Cell Value

FormulaCellValue stores a value of type RadExpression, which represents an arithmetic expression built from constants, operators, cell references, and functions. Its CellValueType is Formula, and its RawValue must start with =.

You can create FormulaCellValue in two common ways:

Pass a string that starts with = to SetValue().
Create an ICellValue through CellValueFactory.Create() and pass it to SetValue().

Both methods create FormulaCellValue only when the current CellValueFormat is not Text. If the cell format is Text, the value becomes TextCellValue instead.

Example 11: Create a Formula That Refers to Another Cell

Workbook workbook = new Workbook();
Worksheet worksheet = workbook.Worksheets.Add();
worksheet.Cells[0, 0].SetValue("=A2");

After this code runs, the value of cell A1 matches the value of cell A2. When A2 changes, A1 updates automatically.

An expression can also contain a built-in function. For the full list of available functions, see Functions. If the current CellValueFormat is Text (@), the method produces TextCellValue instead of FormulaCellValue.

Example 12: Use a Built-In Function

Workbook workbook = new Workbook();
Worksheet worksheet = workbook.Worksheets.Add();
worksheet.Cells[0, 0].SetValue("=SUM(A2, 3)");

You can also pass ICellValue to SetValue() after creating it with CellValueFactory.Create(). Unlike the Boolean and Number overloads, formula creation also requires Worksheet and CellIndex parameters because the expression can reference other cells and worksheets. This overload also takes the current cell format and can return an updated format to apply.

Example 13: Create FormulaCellValue

Workbook workbook = new Workbook();
Worksheet worksheet = workbook.Worksheets.Add();
CellIndex cellIndex = new CellIndex(0, 0);

ICellValue cellValue;
CellValueFormat newFormatValue;
CellValueFactory.Create("=A2 + B2", worksheet, cellIndex, CellValueFormat.GeneralFormat, out cellValue, out newFormatValue);
worksheet.Cells[cellIndex].SetValue(cellValue);

SetValue() performs internal checks that consider the current cell format and other conditions. If you already know that the incoming text is a formula, use SetValueAsFormula(string text) directly to improve performance.

Example 14: Create FormulaCellValue by Using SetValueAsFormula()

Workbook workbook = new Workbook();
Worksheet worksheet = workbook.Worksheets.Add();
CellIndex cellIndex = new CellIndex(0, 0);

worksheet.Cells[cellIndex].SetValueAsFormula("=B1+B2");

Depending on your requirements, you can read either the formula definition or the evaluated result value.

Example 15: Get the Value of a Cell That Contains a Formula

Workbook workbook = new Workbook();
Worksheet worksheet = workbook.Worksheets.Add();
worksheet.Cells[0, 0].SetValue("=SUM(A2, 3)");
worksheet.Cells[1, 0].SetValue(10);
ICellValue cellValue = worksheet.Cells[0, 0].GetValue().Value;
CellValueFormat format = worksheet.Cells[0, 0].GetFormat().Value;

string valueAsString = cellValue.GetValueAsString(format); // =SUM(A2, 3)
string resultValue = cellValue.GetResultValueAsString(format); // 13

Text Cell Value

TextCellValue stores a string, and its ValueType is Text.

You can set TextCellValue by using SetValue(string). Before the method creates TextCellValue, it first tries to parse the incoming string as other supported value types. For example, if you pass true, the cell becomes BooleanCellValue.

Example 16: Set TextCellValue

Workbook workbook = new Workbook();
Worksheet worksheet = workbook.Worksheets.Add();
worksheet.Cells[0, 0].SetValue("some text");

If you want to skip the default parsing and always create TextCellValue, set the cell value format to Text (@) before you assign the value.

Example 17: Explicitly Apply the Text Value Type

Workbook workbook = new Workbook();
Worksheet worksheet = workbook.Worksheets.Add();
worksheet.Cells[0, 0].SetFormat(new CellValueFormat("@"));
worksheet.Cells[0, 0].SetValue("=1+2");

You can achieve the same result by using CellValueFactory.Create().

Example 18: Create TextCellValue

Workbook workbook = new Workbook();
Worksheet worksheet = workbook.Worksheets.Add();
CellIndex cellIndex = new CellIndex(0, 0);

ICellValue cellValue;
CellValueFormat newFormatValue;
CellValueFactory.Create("=1 + 2", worksheet, cellIndex, new CellValueFormat("@"), out cellValue, out newFormatValue);
worksheet.Cells[cellIndex].SetValue(cellValue);

If you already know that the value must be text, use SetValueAsText(string text) directly to avoid the internal parsing checks and improve performance.

Example 19: Create TextCellValue by Using SetValueAsText()

Workbook workbook = new Workbook();
Worksheet worksheet = workbook.Worksheets.Add();
CellIndex cellIndex = new CellIndex(0, 0);

worksheet.Cells[cellIndex].SetValueAsText("This is most certainly a text.");

Next Steps

Continue with the article that matches your next task:

Read Accessing Cells of a Worksheet to work with CellSelection objects.
Read Number Formatting to control how numeric and date values are displayed.
Read Functions to build more advanced formulas.