C# Nullable Value Type: Syntax and Usage
Learn how to declare and use C# nullable value types with Nullable<T>, including HasValue, Value, GetValueOrDefault, and pattern matching.

A nullable value type is a C# feature that lets a value type such as int, bool, or DateTime represent a missing or unknown value. A nullable value type is an instance of System.Nullable<T> and is declared by appending ? to the underlying type, for example int? or DateTime?. The variable can hold either a valid value of T or null.
Declaring Nullable Value Types
The ? modifier is syntactic sugar for Nullable<T>. The following declarations are equivalent:
int? maybeNumber = null;
Nullable<int> alsoMaybeNumber = null;Both create a value type that wraps an int and a Boolean flag indicating whether a value is present. Because Nullable<T> is itself a struct, a nullable value type is still a value type. It does not introduce heap allocation when stored in a local variable or field, although boxing can occur in certain situations.
You can assign a normal value directly:
int? count = 42;You can also assign a nullable variable from another nullable variable, and the null state is preserved.
Checking for a Value with HasValue and Value
The Nullable<T> structure exposes two important members: HasValue and Value. HasValue returns true when the variable contains a real value; otherwise it returns false. Accessing Value when HasValue is false throws an InvalidOperationException.
int? maybe = GetNullableInt();
if (maybe.HasValue)
{
Console.WriteLine($"Value is {maybe.Value}");
}
else
{
Console.WriteLine("No value present");
}Always check HasValue before reading Value, or use one of the safer access patterns described below.
Using GetValueOrDefault and Null-Coalescing
GetValueOrDefault() returns the underlying value if present, or the default value of T otherwise. You can also supply a custom default:
int? maybe = null;
int result = maybe.GetValueOrDefault(-1); // returns -1The null-coalescing operator ?? provides a more concise alternative:
int result = maybe ?? -1;Both approaches avoid the exception risk and are common in real-world code. The ?? operator also works with nullable value types in expressions and assignments.
Pattern Matching with Nullable Value Types
C# pattern matching lets you test the underlying value of a nullable without explicitly checking HasValue. You can use is to check for a value and extract it:
if (maybe is int value)
{
Console.WriteLine(value);
}This is equivalent to checking HasValue and then reading Value, but the syntax is more readable. You can also combine it with other patterns:
string description = maybe switch
{
int v when v > 100 => "Large",
int v => "Small",
null => "None"
};The null pattern matches the case where HasValue is false. Pattern matching treats the nullable value type as having either its underlying value or null, so no explicit HasValue check is needed here.
Boxing and Performance Considerations
When a nullable value type is converted to object or an interface, the CLR boxes it. If HasValue is false, the boxed result is a null reference. If a value is present, the boxed object contains the underlying value, not the Nullable<T> wrapper. This behavior matters when you pass a nullable value type to a method that expects object, or when you store it in a non-generic collection such as ArrayList.
Boxing has a runtime cost. In hot paths, avoid unnecessary conversions. For example, prefer generic collections like List<int?> over non-generic collections, and use ?. and ?? to avoid repeated HasValue checks when possible. Calling GetValueOrDefault() on a nullable variable does not box it; boxing occurs when you convert the nullable to object or an interface.
Nullable Value Types vs Nullable Reference Types
C# 8 introduced nullable reference types, which are a compile-time annotation feature. They do not change the runtime behavior of reference types; they only enable static analysis warnings. Nullable value types, on the other hand, are a runtime feature that actually changes the type of the variable. The two features solve different problems:
| Feature | Nullable Value Types | Nullable Reference Types |
|---|---|---|
| Runtime representation | Nullable<T> struct | Same as reference type |
| Null handling | Runtime check via HasValue | Compile-time warnings |
| Introduced in | C# 2 | C# 8 |
| Applies to | Value types only | Reference types only |
Use nullable value types when a value type must represent an absent value, such as a database column that allows NULL. Use nullable reference types to document null intent and get compile-time warnings when a reference that should not be null is assigned null.
Common Pitfalls and Edge Cases
One common mistake is comparing a nullable value type directly to null without understanding the underlying behavior. The == operator works, but it is implemented by Nullable<T> and returns true when HasValue is false. This is fine, but be aware that null is not the same as the default value of T. For example, int? with no value is not the same as 0.
Another edge case is lifting operators. When you use arithmetic operators on nullable value types, the result is null if either operand is null. For example:
int? a = 5;
int? b = null;
int? sum = a + b; // sum is nullThis behavior is called lifted operators and applies to most built-in operators. It can be surprising if you expect null to be treated as zero.
Finally, the is pattern example requires C# 7 or later, and the switch expression requires C# 8 or later. If you are using an older compiler, use HasValue and Value instead.
Try matching browser tools
All toolsSmall utilities that fit C# work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related C# guides
All C# guidesC# Dispose vs Destructor: Key Differences Explained
c# dispose vs destructor: Understand the difference between Dispose and destructors in C#, when each runs, and how to manage unmanaged resources correctly.
C# Variable Declaration: Syntax and Practical Usage
Learn how to declare variables in C# with explicit types, var, and nullable annotations, and understand how defaults, scope, and readability affect your choices.
C# Primary Constructors for Classes: Syntax and Usage
Learn how to use C# primary constructors for classes: syntax, initialization, dependency injection, and limitations with practical examples.
C# IComparer: Custom Sorting with IComparer<T>
Learn how to implement IComparer<T> in C# to define custom sort order for arrays and lists, handle nulls, and avoid common performance pitfalls.
More in C#
All C# guidesThe guides filed next to this one in C#, in library order.