Skip to main content

Data Grid

Overview

The DataGrid is meant for displaying tabular data. You can easily customize its look with style properties such as header background color, odd row color, etc., or go deeper into customization using templates for cells and headers.

To display data the DataGrid needs at least:

  • a list of column definitions set in the ColumnDefinitions property; they indicate how the data source will be organized in columns (check DataGridColumn type below)
  • an enumerable set in the ItemsSource property that is the actual data to display in the rows

There are 2 ways to define how the data source is mapped into a column:

  • the BindingPath property of the column; the DataGrid creates a Label on each cell with its Text bound through this path
  • the CellTemplate property of the column; by using a DataTemplate you can define a free visual hierarchy to use in each cell

The DataGrid supports sorting and selection.

DataGrid Properties

NameTypeDescription
ColumnDefinitionsIList
Collection of column definitions
ColumnSeparatorColorColorColumn separators color
ColumnSeparatorWidthdoubleColumn separators width
EvenRowsBackgroundColorColorEven rows background color
GridSeparatorVisibilityDataGridSeparatorVisibilitySeparators visibility: DataGridSeparatorVisibility.None, DataGridSeparatorVisibility.Horizontal, DataGridSeparatorVisibility.Vertical, DataGridSeparatorVisibility.All
HeaderColumnSeparatorColorColorHeader column separators color
HeaderColumnSeparatorWidthdoubleHeader column separators width
HeaderRowBackgroundColorColorHeader background color
HeaderRowHeightdoubleHeader height
HeaderRowSeparatorColorColorHeader row separator color
HeaderRowSeparatorHeightdoubleHeader row separator height
HeaderSeparatorVisibilityDataGridSeparatorVisibilityHeader separators visibility: DataGridSeparatorVisibility.None, DataGridSeparatorVisibility.Horizontal, DataGridSeparatorVisibility.Vertical, DataGridSeparatorVisibility.All
HorizontalScrollBarVisibilityScrollBarVisibilityHorizontal scrollbar visibility: ScrollBarVisibility.Default, ScrollBarVisibility.Always, ScrollBarVisibility.Never
ItemsSourceIEnumerableEnumerable data source to display as rows.
OddRowsBackgroundColorColorOdd rows background color
RowHeightdoubleRows height
RowSeparatorColorColorRow separators color
RowSeparatorHeightdoubleRow separators height
SelectedBackgroundColorColorBackground color for selected item
SelectedItemobjectSelected row item
SelectionModeDataGridSelectionModeSelection mode (DataGridSelectionMode.None, DataGridSelectionMode.Row)
tip

If you enable selection, the BindingContext of the rows should be different for each row (either different objects or different value types) as their identity is used to uniquely identify the selected row.

DataGrid Events and Commands

NameTypeDescription
ItemSelectedEventFired when a row is selected. Args: DataGridSelectedItemChangedEventArgs { SelectedItem: object }
ItemSelectedCommandICommandExecuted when a row is selected. Receives the selected row object as parameter.

DataGridColumn Properties

NameTypeDescription
AscendingSortIconImageSourceImage displayed on header when the column is sorted and sort type is Ascending
AscendingSortIconTextstringIcon text displayed on header when the column is sorted and sort type is Ascending, see SortIconsFontFamily
BindingPathstringBinding path used to display data within an automatically created Label (ignored when using a CellTemplate)
CellBackgroundColorColorCells background color
CellFontAttributesFontAttributesCells text font attributes (FontAttributes.None, FontAttributes.Bold, FontAttributes.Italic)
CellFontFamilystringCells text font family
CellFontSizedoubleCells text font size
CellPaddingThicknessCells padding
CellTemplateDataTemplateData template for cells, when using this property BindingPath is ignored. When using a DataTemplateSelector the selector receives the entire row unless a CellTemplateBindingContextPath is defined.
CellTemplateBindingContextPathstringOptional binding path that constrains the data context of this column CellTemplate. Helps as a shortcut if there are multiple bindings in the template content with the same base path.
CellTextAlignmentTextAlignment`Cells text alignment (TextAlignment.Start, TextAlignment.Center, TextAlignment.End); if not defined, numeric values are right-aligned and non-numeric values left-aligned
CellTextColorColorCells text color
CellVerticalAlignmentDataGridVerticalAlignmentCells vertical alignment (DataGridVerticalAlignment.Start, DataGridVerticalAlignment.Center, DataGridVerticalAlignment.End)
ColumnWidthGridLengthColumn width
ConverterIValueConverterConverter applied to binding when using BindingPath
ConverterParameterobjectParameter passed to converter when using BindingPath
DescendingSortIconImageSourceImage displayed on header when the column is sorted and sort type is Descending
DescendingSortIconTextstringIcon text displayed on header when the column is sorted and sort type is Descending, see SortIconsFontFamily
HeaderBackgroundColorColorHeader background color
HeaderControlTemplateControlTemplateA ControlTemplate for a DataGridHeaderCell representing the content of the header cell.
HeaderFontAttributesFontAttributesHeader text font attributes (FontAttributes.None, FontAttributes.Bold, FontAttributes.Italic)
HeaderFontFamilystringHeader text font family
HeaderFontSizedoubleHeader text font size
HeaderPaddingThicknessHeader padding
HeaderTextstringText displayed on header
HeaderTextAlignmentTextAlignmentHeader text alignment (TextAlignment.Start, TextAlignment.Center, TextAlignment.End)
HeaderTextColorColorHeader text color
HeaderVerticalAlignmentDataGridVerticalAlignmentHeader vertical alignment (DataGridVerticalAlignment.Start, DataGridVerticalAlignment.Center, DataGridVerticalAlignment.End)
IsSortableboolIndicates if the column is sortable or not
SortDataGridSortType(readonly) Indicates the current sort direction (DataGridSortType.Unsorted, DataGridSortType.Ascending, DataGridSortType.Descending)
SortIconsFontFamilystringIcon font family to use for displaying both AscendingSortIconText and DescendingSortIconText
SortIconsFontSizedoubleSorting text font size
StringFormatstringString format applied to binding when using BindingPath
UnsortedIconImageSourceImage displayed on header when the column is sortable and sort type is Unsorted
UnsortedIconTextstringText displayed on header when the column is sortable and sort type is Unsorted

DataGridColumn Commands

NameTypeDescription
SortCommandICommandCustom sorting command invoked when the user taps the column header.

DataGridHeaderCell properties

DataGridHeaderCell is the backing class for the control template of headers (see HeaderControlTemplate above).

The only purpose of this class is to consume its properties through TemplateBindings inside your header template. Most of them come from the column definition itself.

NameTypeDescription
AscendingSortIconImageSourceImage to be used for Ascending sort
AscendingSortIconTextstringIcon text to be used for Ascending sort, see SortIconsFontFamily
CurrentSortIconImageSourceCalculated sort Image according to the current column sort, usually is enough to have 1 Image in the template with its source bound to this property, no need to care for Ascending and Descending images.
CurrentSortIconTextstringCalculated icon text according to the current column sort, usually is enough to have 1 Label in the template with its text bound to this property, no need to care for Ascending and Descending icons.
DescendingSortIconImageSourceImage to be used for Descending sort
DescendingSortIconTextstringIcon text to be used for Descending sort, see SortIconsFontFamily
HeaderBackgroundColorColorColor to be used for the background
HeaderFontAttributesFontAttributesText to be used as the column title
HeaderFontFamilystringFont family to be used for the column title text
HeaderFontSizedoubleFont size to be used on the column title text
HeaderPaddingThicknessPadding for the header
HeaderTextstringText displayed on header
HeaderTextAlignmentTextAlignmentText alignment to be used for the header text
HeaderTextColorColorColor to be used for the header text
HeaderVerticalAlignmentDataGridVerticalAlignmentHeader vertical alignment
IsSortableboolTrue when sortable and False when not
SortDataGridSortTypeIndicates the current sort direction
SortIconsFontFamilystringIcon font family to be used for displaying both AscendingSortIconText and DescendingSortIconText
SortIconsFontSizedoubleSorting text font size
UnsortedIconImageSourceImage to be used when Unsorted
UnsortedIconTextstringIcon text to be used when Unsorted sort, see SortIconsFontFamily

DataGridHeaderCell Commands

NameTypeDescription
SortCommandICommandCustom sorting command invoked when the user taps the column header.

Samples

Let's see how to show a grid like the following one:

ID NumberFull Name
#000Joe Doe

The above grid has a Header and a single row, and the data has the following format (JSON notation):

{
"MyTabularData": [
{
"Id" : "#000",
"Name" : "Joe Doe"
}
]
}
caution

Don't forget to include the namespace
xmlns:grial="clr-namespace:UXDivers.Grial;assembly=UXDivers.Grial"

The XAML code would like the following:

<grial:DataGrid 
ItemsSource="{ Binding MyTabularData }"
>
<grial:DataGrid.ColumnDefinitions>
<grial:DataGridColumn
BindingPath="Id"
HeaderText="Id Number"
/>
<grial:DataGridColumn
BindingPath="Name"
HeaderText="Full Name"
/>
</grial:DataGrid.ColumnDefinitions>
</grial:DataGrid>

The HeaderText property used in each column sets the text displayed for each column header.

The result will look like the following:

DataGridSample

Let's see how to make the headers look different by changing a few properties:

<grial:DataGrid 
ItemsSource="{ Binding MyTabularData }"
RowSeparatorColor="Purple"
ColumnSeparatorColor="Purple"
>
<grial:DataGrid.ColumnDefinitions>
<grial:DataGridColumn
BindingPath="Id"
HeaderText="ID Number"
HeaderBackgroundColor="Purple"
HeaderTextColor="White"
/>
<grial:DataGridColumn
BindingPath="Name"
HeaderText="Full Name"
HeaderBackgroundColor="Purple"
HeaderTextColor="White"
/>
</grial:DataGrid.ColumnDefinitions>
</grial:DataGrid>

The result will look like the following:

DataGridSample

Let's see how to change the look and feel to display just borders:

<grial:DataGrid 
ItemsSource="{ Binding MyTabularData }"
RowSeparatorColor="Purple"
ColumnSeparatorColor="Purple"
HeaderRowSeparatorColor="Purple"
HeaderColumnSeparatorColor="Purple"
>
<grial:DataGrid.ColumnDefinitions>
<grial:DataGridColumn
BindingPath="Id"
HeaderText="ID Number"
HeaderBackgroundColor="Transparent"
HeaderTextColor="Purple"
/>
<grial:DataGridColumn
BindingPath="Name"
HeaderText="Full Name"
HeaderBackgroundColor="Transparent"
HeaderTextColor="Purple"
/>
</grial:DataGrid.ColumnDefinitions>
</grial:DataGrid>

The result will look like the following:

DataGridSample

Now, let's change the default GridSeparatorVisibility value (DataGridSeparatorVisibility.All)) to just display "Horizontal" lines:

<grial:DataGrid 
ItemsSource="{ Binding MyTabularData }"
RowSeparatorColor="Purple"
ColumnSeparatorColor="Purple"

GridSeparatorVisibility="Horizontal"
HeaderSeparatorVisibility="Horizontal"
HeaderRowSeparatorColor="Purple"

>
<grial:DataGrid.ColumnDefinitions>
<grial:DataGridColumn
BindingPath="Id"
HeaderText="Id Number"
HeaderBackgroundColor="Transparent"
HeaderTextColor="Purple"

/>
<grial:DataGridColumn
BindingPath="Name"
HeaderText="Full Name"
HeaderBackgroundColor="Transparent"
HeaderTextColor="Purple"
/>
</grial:DataGrid.ColumnDefinitions>
</grial:DataGrid>

The result will look like the following:

DataGridSample

Let's see how out DataGrid looks like when we set the GridSeparatorVisibility and HeaderSeparatorVisibility to "Vertical":

<grial:DataGrid 
ItemsSource="{ Binding MyTabularData }"
RowSeparatorColor="Purple"
ColumnSeparatorColor="Purple"

GridSeparatorVisibility="Vertical"
HeaderSeparatorVisibility="Vertical"

HeaderRowSeparatorColor="Purple"
HeaderColumnSeparatorColor="Purple"

>
<grial:DataGrid.ColumnDefinitions>
<grial:DataGridColumn
BindingPath="Id"
HeaderText="Id Number"
HeaderBackgroundColor="White"
HeaderTextColor="Purple"

/>
<grial:DataGridColumn
BindingPath="Name"
HeaderText="Full Name"
HeaderBackgroundColor="White"
HeaderTextColor="Purple"
/>
</grial:DataGrid.ColumnDefinitions>
</grial:DataGrid>

The result will look like the following:

DataGridSample

Things to keep in mind while working with the DataGrid

By default, when a DataGrid is rendered it will fill the available vertical space.

DataGridSample

If a second DataGrid needs to be added immediately below the first one, you will need to set the RowHeight property -of the first DataGrid- to an specific value.

DataGridSample
<StackLayout Margin="40">

<grial:DataGrid
ItemsSource="{ Binding MyTabularData }"
BackgroundColor="#33ffa700"
GridSeparatorVisibility="Horizontal"
HeaderSeparatorVisibility="Horizontal"

RowHeight="32"
>
<grial:DataGrid.ColumnDefinitions>
<grial:DataGridColumn
BindingPath="Id"
HeaderText="Id Number"
/>
<grial:DataGridColumn
BindingPath="Name"
HeaderText="Full Name"
/>
</grial:DataGrid.ColumnDefinitions>
</grial:DataGrid>

<grial:DataGrid
ItemsSource="{ Binding MyTabularData }"
BackgroundColor="LightGray"

GridSeparatorVisibility="Horizontal"
HeaderSeparatorVisibility="Horizontal"
>
<grial:DataGrid.ColumnDefinitions>
<grial:DataGridColumn
BindingPath="Id"
HeaderText="Id Number"
/>
<grial:DataGridColumn
BindingPath="Name"
HeaderText="Full Name"
/>
</grial:DataGrid.ColumnDefinitions>
</grial:DataGrid>
</StackLayout>

An advanced example using custom data templates for cells can be found in Grial's ShippingDetailPage.xaml.

DataGridSample