A canvas-drawn DataGrid for .NET MAUI and the Uno Platform: one SkiaSharp engine, the same grid on every head.
Getting Started · Columns · Sorting & Filtering · Grouping · Editing · Theming · Keyboard · FAQ
Each grid is one SkiaSharp canvas. Cells, headers, editors, the filter popup, pickers and the grouping panel are drawn by KumikoUI.Core, so a grid looks the same on every platform. The host controls add what a canvas can't do: a connection to the platform's text input (keyboard, soft keyboard and input methods), the platform's pointer and gesture events, and the mouse cursor. The grid draws no scrollbars; it scrolls by touch, mouse wheel, trackpad and keyboard.
- Features
- Packages
- Supported platforms
- Getting Started
- Columns
- Action Button Columns
- Sorting and Filtering
- Grouping
- Summaries
- Editing
- Validation
- Localization
- Selection
- Keyboard
- Row Drag and Drop
- Theming and Styling
- Host Properties, Commands & Events
- Custom Fonts
- Icons
- Scrolling
- Performance
- Live Data
- Native AOT and Trimming
- Accessibility
- FAQ
- Architecture
- Sample Applications
- Contributing
- License
| Area | What you get |
|---|---|
| Hosts | KumikoDataGrid for .NET MAUI and for the Uno Platform, with the same properties, commands and events |
| Rendering | Only visible rows and columns are drawn; steady-state frames allocate nothing in the managed render loop; sorting, filtering and grouping of 10,000 rows or more run on a background thread (Performance) |
| Column types | Text, Numeric, Boolean (optionally three-state), Date, ComboBox, Picker, Image, ProgressBar, Template (custom renderers such as the built-in action buttons) |
| Column layout | Fixed, Star and Auto (fitted to content) sizing; headers fit unless you set a width; resize by dragging or double-click auto-fit; wrapping text cells; drag a header to reorder; freeze columns left or right and rows at the top; save and restore the layout as JSON |
| Sorting | Header tap cycles through a type-aware first direction, the opposite direction and none; Shift or Ctrl adds columns to a multi-column sort |
| Filtering | Filter popup per column with search, a value checklist, sort rows and OK / Cancel / Clear; programmatic predicate and column filters |
| Grouping | Nested groups, expand and collapse, sticky group headers, a grouping panel with chips |
| Summaries | Table (top or bottom, bottom pinned as a footer by default), group and caption summaries: Sum, Average, Count, Min, Max, Custom |
| Editing | Text, numeric, date, combo box, picker and custom editors; edit triggers per grid and per column; typed conversion and validation with messages |
| Selection | None, Single, Multiple, Extended; item-based, so it survives sort, filter and regrouping; MVVM-bindable |
| Rows | Drag and drop reorder by handle or by row |
| Interaction | Hover and pressed feedback, short transitions (group expand and collapse, column drag), momentum presets for iOS, Android and desktop, optional haptics, and a context-menu event; every timing is listed in docs/INTERACTION.md |
| Scrolling | Touch, wheel, trackpad and keyboard; ScrollToRow, ScrollToItem and ScrollToColumn; bindable VerticalOffset and HorizontalOffset; a Scrolled event |
| Clipboard | Ctrl/Cmd+C copies the selected rows as tab-separated text; copy, cut and paste work in editors |
| Theming | Light, Dark and HighContrast presets, bindable, following the system light/dark setting by default; every color, font and size on KumikoStyle; per-cell and per-row style resolvers |
| Icons | Every built-in glyph (sort arrows, filter buttons, chevrons, check marks, editor buttons) drawn by a replaceable icon provider: the built-in vector set, an icon font such as Material Icons, or your own drawing (Icons) |
| Localization | KumikoStrings for every built-in text, Culture for formatting, parsing and ordering |
| Data | ObservableCollection and INotifyPropertyChanged, nested property paths, heterogeneous item types |
| AOT | Packages are IsAotCompatible; source-generated accessors ([KumikoGridItem]) or per-column delegates |
| Package | Contains | Install it when |
|---|---|---|
KumikoUI.Maui |
KumikoDataGrid for .NET MAUI, UseKumikoUI(), MauiActionButtonDefinition |
you build a .NET MAUI app |
KumikoUI.Uno |
KumikoDataGrid for the Uno Platform (WinUI API), UnoActionButtonDefinition, KumikoFonts |
you build an Uno Platform app (the least verified host, see Supported platforms) |
KumikoUI.SkiaSharp |
SkiaDrawingContext, SkiaResourceCache, SkiaFontRegistrar |
you host the engine on your own SkiaSharp surface (the host packages reference it) |
KumikoUI.Core |
Data, layout, rendering, input and editing engine; models and themes; the [KumikoGridItem] source generator |
always (the other packages reference it); it has no UI framework or SkiaSharp dependency |
All four packages share one version, and each depends on the exact version of the others. The current version is 1.0.0-preview.1, the first 1.0 prerelease: the API may still change before 1.0.0. NuGet hides prerelease versions unless you ask for them; see Getting Started. Release notes are in the CHANGELOG and docs/release/1.0.0-preview.1-release-notes.md.
All packages target .NET 10 and SkiaSharp 4.153.1.
| Package | Platform (target framework) | Minimum OS | App build host | Verification |
|---|---|---|---|---|
| KumikoUI.Core, KumikoUI.SkiaSharp | any .NET 10 runtime (net10.0) |
— | any OS | Unit tests in CI |
| KumikoUI.Maui | iOS (net10.0-ios) |
17.0 | macOS (Xcode) | CI build; the device suite passes on iPhone (106 of 106) and iPad (104 of 105, 1 skipped) simulators |
| KumikoUI.Maui | Mac Catalyst (net10.0-maccatalyst) |
17.0 (macOS 14+) | macOS (Xcode) | CI build; the device suite passes (106 of 106) on macOS 27 |
| KumikoUI.Maui | Android (net10.0-android) |
API 24 (Android 7.0) | any OS | CI build; the device suite passes (106 of 106) on an Android 15 emulator, including the hardware (GPU) surface and Gboard composition; not yet run on a physical phone |
| KumikoUI.Maui | Windows (net10.0-windows10.0.19041.0) |
10.0.19041 | Windows | CI build only; not yet run on a device |
| KumikoUI.Uno | Desktop: Windows, macOS, Linux (net10.0-desktop) |
as .NET 10 | any OS | CI build; the sample renders and follows the system theme on macOS, but pointer and keyboard use of the desktop head has not been checked (#274), the grid is missing from the macOS accessibility tree (#277), and Windows and Linux have not been run |
| KumikoUI.Uno | WebAssembly (net10.0-browserwasm) |
current evergreen browsers | any OS (wasm-tools workload) |
CI build (trimmed publish); checked interactively in Chromium, including 100,000 rows |
| KumikoUI.Uno | iOS (net10.0-ios) |
17.0 | macOS (Xcode) | CI build; checked on an iPhone simulator; known issue: the sample shell sits under the system bars (#280) |
| KumikoUI.Uno | Android (net10.0-android) |
API 24 (Android 7.0) | any OS | CI build; checked on an Android 15 emulator; known issues: the filter popup's search box gets no soft keyboard (#275), a touch column reorder does not work (#276), a Release build starts slowly (#278), and the sample shell sits under the system bars (#280) |
| KumikoUI.Uno | Windows App SDK (net10.0-windows10.0.26100) |
10.0.19041 | Windows | CI build only; not yet run on a device |
"App build host" is where an app for that head can be built; the libraries themselves are compiled and packed for every head on Windows in CI. "CI build" means compiled and packed in CI. The device results come from the verification passes of 2026-11-13 and are written up, with their known issues, in docs/maui-verification.md and docs/uno/verification.md. KumikoUI.Uno has no Mac Catalyst head: Uno serves macOS through the desktop head.
1.0.0-preview.1 is a prerelease of all four packages. The API may still change before 1.0.0, and the compatibility promise of docs/VERSIONING.md starts with 1.0.0. KumikoUI.Uno is the least verified host. It shares its engine, its API and most of its input code with the MAUI host, and the sample app runs on its WebAssembly, iOS and Android heads, but its heads have not all been walked end to end: the desktop head has had no interactive pass (#274), Windows and Linux have not been run, and several input and accessibility problems on the desktop and mobile heads are open (#275 to #278, #280). See docs/uno/verification.md. KumikoUI.Core, KumikoUI.SkiaSharp and KumikoUI.Maui have had the device passes listed above.
Minimum OS versions are defined once in Directory.Build.props (KumikoMin*Version) and apply to every library, sample and head. They are re-baselined at each .NET major release, and every change is called out as breaking in the CHANGELOG.
The grid, its columns and its options are the same on both hosts. What differs is the package, the startup code and the XAML namespace:
| .NET MAUI | Uno Platform | |
|---|---|---|
| Package | KumikoUI.Maui |
KumikoUI.Uno |
| Startup | builder.UseKumikoUI() in MauiProgram (required: it registers SkiaSharp's MAUI handlers and passes ConfigureFonts aliases to the grid) |
no startup call |
| App project | — | <SkiaSharpVersion>4.153.1</SkiaSharpVersion> and the SkiaRenderer Uno feature |
| Control namespace | clr-namespace:KumikoUI.Maui;assembly=KumikoUI.Maui |
using:KumikoUI.Uno |
| Models namespace | clr-namespace:KumikoUI.Core.Models;assembly=KumikoUI.Core |
using:KumikoUI.Core.Models |
| Two-way bindings | default for the selection properties | set Mode=TwoWay explicitly (WinUI bindings default to one-way) |
| Custom fonts | ConfigureFonts aliases, or SkiaFontRegistrar |
KumikoFonts (wraps SkiaFontRegistrar) |
-
Add the package (it brings in
KumikoUI.CoreandKumikoUI.SkiaSharp):dotnet add package KumikoUI.Maui --prerelease
While only prereleases exist,
--prerelease(or--version 1.0.0-preview.1, orVersion="1.0.0-preview.1"in aPackageReference) is required; without it NuGet finds no stable version. The packages depend on each other at their exact version, so a mismatched set does not restore. -
Register KumikoUI in
MauiProgram.cs:using KumikoUI.Maui; public static class MauiProgram { public static MauiApp CreateMauiApp() { var builder = MauiApp.CreateBuilder(); builder .UseMauiApp<App>() .UseKumikoUI(); // registers the SkiaSharp handlers the grid's canvas needs return builder.Build(); } }
A
KumikoDataGridattached to a handler without this call throws an exception that says so.UseSkiaKumikoUI()from earlier versions was removed in 1.0; callUseKumikoUI(). -
Declare the grid. The XAML is the same as on Uno once the
kumikoandcoreprefixes are declared:<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui" xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml" xmlns:kumiko="clr-namespace:KumikoUI.Maui;assembly=KumikoUI.Maui" xmlns:core="clr-namespace:KumikoUI.Core.Models;assembly=KumikoUI.Core"> <kumiko:KumikoDataGrid x:Name="kumiko" ItemsSource="{Binding Employees}" RowHeight="36" HeaderHeight="40"> <core:KumikoColumn Header="Name" PropertyName="Name" Width="180" /> <core:KumikoColumn Header="Age" PropertyName="Age" Width="80" ColumnType="Numeric" TextAlignment="Right" /> <core:KumikoColumn Header="Active" PropertyName="IsActive" Width="80" ColumnType="Boolean" /> </kumiko:KumikoDataGrid> </ContentPage>
iOS and Mac Catalyst: current Apple OS versions (macOS 27 and iOS 27 with the Xcode 27 toolchain) terminate an app at launch if it has not adopted the UIScene lifecycle. New .NET MAUI templates already include it: a
UIApplicationSceneManifestinPlatforms/iOS/Info.plistandPlatforms/MacCatalyst/Info.plist, and aSceneDelegateclass deriving fromMauiUISceneDelegate. If your app was created from an older template, copy these from a freshdotnet new maui. Seesamples/SampleApp.Maui/Platformsfor a working setup.
-
Add the package:
dotnet add package KumikoUI.Uno --prerelease
While only prereleases exist,
--prerelease(or--version 1.0.0-preview.1, orVersion="1.0.0-preview.1"in aPackageReference) is required. -
In the app project, make Uno use the SkiaSharp major KumikoUI is built with, and turn on the SkiaSharp canvas (Uno.Sdk defaults to SkiaSharp 3.x, and the app must resolve one SkiaSharp major):
<PropertyGroup> <SkiaSharpVersion>4.153.1</SkiaSharpVersion> <UnoFeatures> SkiaRenderer; </UnoFeatures> </PropertyGroup> <!-- Windows App SDK head only: the SkiaRenderer feature does not add the WinUI SkiaSharp views --> <ItemGroup Condition="$(TargetFramework.Contains('-windows'))"> <PackageReference Include="SkiaSharp.Views.WinUI" Version="4.153.1" /> </ItemGroup>
samples/SampleApp.Uno/SampleApp.Uno.csprojis a complete, working project file. -
Declare the grid. Uno needs no startup call:
<Page xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" xmlns:kumiko="using:KumikoUI.Uno" xmlns:core="using:KumikoUI.Core.Models"> <kumiko:KumikoDataGrid x:Name="kumiko" ItemsSource="{Binding Employees}" RowHeight="36" HeaderHeight="40"> <core:KumikoColumn Header="Name" PropertyName="Name" Width="180" /> <core:KumikoColumn Header="Age" PropertyName="Age" Width="80" ColumnType="Numeric" TextAlignment="Right" /> <core:KumikoColumn Header="Active" PropertyName="IsActive" Width="80" ColumnType="Boolean" /> </kumiko:KumikoDataGrid> </Page>
From here on, XAML uses the kumiko prefix for the host's namespace (as above) plus core for KumikoUI.Core.Models and render for KumikoUI.Core.Rendering, so a snippet works on both hosts unless it says otherwise. C# snippets assume these using directives and a grid named kumiko:
using System.Collections.ObjectModel;
using System.Globalization;
using KumikoUI.Core.Components;
using KumikoUI.Core.Editing;
using KumikoUI.Core.Input;
using KumikoUI.Core.Models;
using KumikoUI.Core.Rendering;
using KumikoUI.Maui; // or KumikoUI.UnoThe grid can also be built in code:
kumiko.Columns.Add(new KumikoColumn { Header = "Name", PropertyName = "Name", Width = 180 });
kumiko.Columns.Add(new KumikoColumn
{
Header = "Salary",
PropertyName = "Salary",
ColumnType = KumikoColumnType.Numeric,
Format = "C0",
TextAlignment = KumikoTextAlignment.Right,
});
kumiko.ItemsSource = employees;Each column is a KumikoColumn. Its ColumnType picks the cell renderer and the editor.
ColumnType |
Cell | Editor | Notes |
|---|---|---|---|
Text (default) |
Text | DrawnTextBox |
|
Numeric |
Formatted number | DrawnTextBox that accepts numbers only |
Set Format (for example "C0", "N2") and usually TextAlignment="Right" |
Boolean |
Check box | none: toggled in place | Checked or unchecked; with IsThreeState="True" a tap, Space or Enter cycles unchecked, checked and indeterminate (null, drawn as a dash), and the property must be a bool? |
Date |
Formatted date | DrawnDatePicker (opens its calendar) |
DateTime, DateTimeOffset and DateOnly values |
ComboBox |
Text | DrawnComboBox (opens its list) |
Items from EditorItems or EditorItemsString; EditorDisplayMemberPath / EditorValueMemberPath or the selector delegates for objects; EditorIsFilterable makes the list searchable |
Picker |
Text | DrawnScrollPicker (scroll wheel) |
Items from EditorItems or EditorItemsString |
Image |
Image, centered in a square | none | A URL, file or asset name, bytes, a stream or a host image source, loaded off the UI thread; see Images |
ProgressBar |
Progress bar | none (read-only) | A number between ProgressMinimum (default 0) and ProgressMaximum (default 100); see Progress bars |
Template |
CustomCellRenderer (text if none) |
EditorFactory, CustomEditorFactory, EditorDescriptor, an ICellEditorProvider renderer, or a text box |
For action buttons and your own renderers |
<core:KumikoColumn Header="Department" PropertyName="Department" Width="140"
ColumnType="ComboBox"
EditorItemsString="Engineering,Marketing,Sales,HR,Finance" />
<core:KumikoColumn Header="Salary" PropertyName="Salary" Width="120"
ColumnType="Numeric" Format="C0" TextAlignment="Right" />
<core:KumikoColumn Header="Id" PropertyName="Id"
IsReadOnly="True" AllowTabStop="False" />Column settings can be changed from code at any time: KumikoColumn raises PropertyChanged and the grid repaints and lays out again without Refresh(). Sort and filter state (SortDirection, SortOrder, ActiveFilter) belongs to the data source and is read-only on the column. Other per-column switches: IsVisible, AllowSorting, AllowFiltering, AllowResize, AllowReorder, CustomComparer, CellStyle and HeaderCellStyle (a KumikoCellStyle).
A Text, Numeric or Date cell shows one line and cuts it with an ellipsis; a line break in the value draws as a space. Set TextWrap on the column to Word or Character to wrap the text onto as many lines as fit the row height, with an ellipsis at the end of the last line when there is more. Rows keep the grid's RowHeight, so raise it to show more lines (variable row height is tracked in #102). The ellipsis never splits an emoji or a letter with combining marks.
<core:KumikoColumn Header="Notes" PropertyName="Notes" Width="220" TextWrap="Word" />A ProgressBar column draws a number as a read-only bar. ProgressMinimum (0) and ProgressMaximum (100) are the values at the empty and full ends, ProgressShowText (true) draws the value over the bar formatted with Format (N0 when unset), and ProgressFillColor sets the fill (default: the style's AccentColor). The column sorts and filters as numbers.
<core:KumikoColumn Header="Performance" PropertyName="Performance" Width="140"
ColumnType="ProgressBar" ProgressMaximum="100" Format="N0" />For a per-value fill color or a different track, use a Template column with a ProgressBarCellRenderer:
<core:KumikoColumn Header="Performance" PropertyName="Performance" Width="140"
ColumnType="Template" IsReadOnly="True">
<core:KumikoColumn.CustomCellRenderer>
<render:ProgressBarCellRenderer Minimum="0" Maximum="100"
TrackHeight="12" CornerRadius="6"
ShowText="True" TextFormat="N0" />
</core:KumikoColumn.CustomCellRenderer>
</core:KumikoColumn>FillColor sets one fill color and ColorSelector picks it per value.
An Image column draws its value as a picture, fitted into a square centered in the cell. The grid loads and decodes the image off the UI thread, draws nothing while it loads, and redraws when it is ready. A value can be:
| Value | Loaded from |
|---|---|
A URL (string or Uri) with http, https, file or data |
The web (through one shared HttpClient), the file system, or the data URI itself |
| A file name or path | An absolute path; otherwise an app package file: on .NET MAUI a MauiAsset (for example under Resources/Raw) or a MauiImage; on Uno an ms-appx:/// path (Assets/Photos/a.png) |
ImageSource (.NET MAUI) |
FileImageSource, UriImageSource and StreamImageSource |
Uri with ms-appx or ms-appdata, or a BitmapImage with a UriSource (Uno) |
The app package or app data, or the bitmap's URI |
byte[], Stream, Func<Stream> or Func<CancellationToken, Task<Stream>> |
The encoded bytes (PNG, JPEG, WebP, GIF, BMP, ICO) |
SKImage or SKBitmap |
Drawn as it is; you own and dispose it |
<core:KumikoColumn Header="Photo" PropertyName="PhotoUrl" Width="60" ColumnType="Image" />Each grid keeps the decoded images in its ImageCache (a KumikoImageCache from KumikoUI.SkiaSharp), keyed by the URL, file name or object, so rows showing the same picture share one image and scrolling back draws it without loading it again. The cache is bounded: it keeps at most MaxCount images (default 256) and MaxBytes of decoded pixels (default 64 MiB), disposes the least recently drawn image when it needs room, cancels the download of an image evicted before it arrives, and disposes everything when the grid is unloaded or disconnected from its handler. Images are decoded at most MaxDecodedSize pixels (default 256) on their longer side. Keep MaxCount above the number of image cells on screen:
kumiko.ImageCache.MaxCount = 500;
kumiko.ImageCache.MaxBytes = 128L * 1024 * 1024;
kumiko.ImageCache.MaxDecodedSize = 128;A value nothing can load, such as a FontImageSource, draws nothing and is reported once per type through System.Diagnostics.Trace, as is the first failed load of each kind. To load another kind of value, implement IKumikoImageLoader: TryGetCacheKey runs for every visible image cell on every frame, so it returns an object the value already holds without allocating, and OpenAsync runs on a worker thread:
public sealed record Photo(int Id);
public sealed class PhotoLoader : KumikoUI.SkiaSharp.IKumikoImageLoader
{
public bool TryGetCacheKey(object source,
[System.Diagnostics.CodeAnalysis.NotNullWhen(true)] out object? key)
{
key = source as Photo; // a record: equal ids share one cached image
return key is not null;
}
public Task<Stream?> OpenAsync(object key, CancellationToken cancellationToken) =>
Task.FromResult<Stream?>(File.OpenRead(
Path.Combine(AppContext.BaseDirectory, "photos", $"{((Photo)key).Id}.jpg")));
}kumiko.ImageCache.Loaders.Insert(0, new PhotoLoader());ImageCellRenderer.ImageResolver maps a cell value to the value to load (for example an id to a URL). A custom cell renderer draws images the same way through cell.ImageResolver.
Implement ICellRenderer and set it as the column's CustomCellRenderer. The grid calls Render for every visible cell of the column on every frame, passing a CellRenderContext by reference:
| Member | Meaning |
|---|---|
Bounds |
The rectangle to draw in (the cell minus its horizontal padding) |
Row |
The visible row index |
Value, DisplayText |
The raw value, and its text formatted with the column's Format in the source's culture |
Column, Style |
The column and the grid style |
CellStyle |
The cell's effective style overrides (column style merged with the resolvers'), or null |
IsSelected |
Whether the row is selected |
Paints |
The grid's shared PaintCache (cell text, checkbox, grid line, selection paints and more) |
TextPaint, TextAlignment |
The paint and alignment for the cell's text, with the cell style's overrides applied |
ImageResolver |
The grid's image cache: Resolve(value, out image) returns Ready with an image for ctx.DrawImage, or Pending while it loads (see Images) |
public sealed class StatusDotRenderer : ICellRenderer
{
// Created once and reused: only the color changes per cell
private readonly KumikoPaint _dot = new() { IsAntiAlias = true };
public void Render(IDrawingContext ctx, in CellRenderContext cell)
{
_dot.Color = cell.Value is true ? new KumikoColor(40, 167, 70) : new KumikoColor(220, 53, 69);
var b = cell.Bounds;
ctx.FillRoundRect(new KumikoRect(b.X, b.Y + b.Height / 2 - 5, 10, 10), 5, _dot);
ctx.DrawTextInRect(cell.DisplayText, new KumikoRect(b.X + 16, b.Y, b.Width - 16, b.Height),
cell.TextPaint, cell.TextAlignment, KumikoVerticalAlignment.Center);
}
}Keep Render free of allocations, as the built-in renderers are: draw with cell.Paints and cell.TextPaint, or with paints and fonts the renderer creates once, and don't create a KumikoPaint, KumikoFont or string per call. The context's CellStyle, TextPaint and Paints may be reused for the next cell, so read them during the call and don't keep or modify them.
A renderer that also implements ICellEditorProvider supplies the editor of its Template column; one that implements IInteractiveCellRenderer handles taps itself, as the action buttons do.
SizeMode |
Behavior |
|---|---|
Fixed (default) |
The width set with Width |
Auto |
Fitted to its header and its widest cell (ContentFitWidth), within MinWidth and MaxWidth. Cells are sampled (the rows on screen plus the first and last 100 rows) on the first frame and again after the data or the view changes; scrolling alone never changes the width |
Star |
A weighted share (StarWeight, default 1) of the width that Fixed and Auto columns leave, within MinWidth and MaxWidth |
<core:KumikoColumn Header="Notes" PropertyName="Notes" SizeMode="Star" StarWeight="2" />Headers fit unless you set a width. A column whose Width was never set is at least wide enough to show its whole header (KumikoColumn.HeaderFitWidth): the header text in the header font, the header padding on both sides, room for the sort arrow when the column can be sorted and for the filter icon when it can be filtered, and a small margin. Fixed and Auto columns without a Width are KumikoColumn.DefaultWidth (120) or their header-fit width when that is wider; Star columns never shrink below it.
<!-- No Width: at least wide enough for "Customer Account Number" -->
<core:KumikoColumn Header="Customer Account Number" PropertyName="Account" />
<!-- Explicit Width: kept as set; the header is truncated with an ellipsis if it doesn't fit -->
<core:KumikoColumn Header="Customer Account Number" PropertyName="Account" Width="100" />
<!-- A smaller MaxWidth also wins over the header fit -->
<core:KumikoColumn Header="Customer Account Number" PropertyName="Account" MaxWidth="100" />- Setting
Widthin code or XAML, dragging the column's resize grip, or auto-fitting it makes the width explicit (HasExplicitWidth); from then on a Fixed column keeps its width, even below the header-fit width. - For Star and Auto columns
Widthis an output of layout. Dragging the resize grip of a Star or Auto column, or auto-fitting it, switches it toFixedat the chosen width so the width persists; setSizeModeback toStarorAutoto share or measure it again. - A Star column whose share is below its minimum (its
MinWidthand header-fit width) or above itsMaxWidthis held there, and the other Star columns share what is left. When the viewport is too narrow for every column's minimum, the grid scrolls horizontally instead of truncating headers. - Header widths are measured once per header text and font and cached; changing a column's
Header, itsHeaderCellStyle.Fontor the grid'sHeaderFontmeasures it again.
Drag the right edge of a column header to resize the column, or double-click it to auto-fit the column to its header and its widest sampled cell (AutoFitColumnRequested, answered by KumikoRenderer.AutoFitColumn). The edge is a resize grip only when the column has AllowResize set (the default) and room to change (MaxWidth above MinWidth). ColumnResized reports a resize.
With a mouse, the cursor shows what a click does:
| Over | Cursor |
|---|---|
| A column resize grip, and for the whole of a resize drag | Left-right resize |
| A filter icon, a group chevron, a grouping chip or its remove button, the row drag handle, an editable check box, an enabled action button | Hand |
| Anything else | Arrow |
InputController.Cursor holds the current cursor (KumikoCursor) and InputController.CursorChanged (an EventHandler<KumikoCursor>) reports changes. The Uno control applies it on the Windows, desktop and WebAssembly heads, and the MAUI control on Windows and Mac Catalyst; touch platforms ignore it. Moving the mouse with no button pressed never scrolls or selects.
Drag a column header sideways to move the column. A drag that starts on a header and moves more horizontally than vertically reorders instead of scrolling; set AllowReorder="False" on a column to keep it in place. The dragged header follows the pointer, and on release the column lands between the two columns on either side of the pointer: before the first column whose middle is right of it, or after the last one.
A column moves only within its own pane: left-frozen columns among the left-frozen ones, scrolling columns among the scrolling ones and right-frozen columns among the right-frozen ones. A drop over another pane or over the row drag handle lands at the near end of the column's own pane, and a scrolling column hidden under a frozen pane is never the target. To move a column to another pane, change its FreezeMode.
The grid moves the column in both DataSource.Columns and its own Columns collection, then raises ColumnReordered. OldIndex and NewIndex are positions in Columns (the definition order, hidden columns included): the column is removed at OldIndex and inserted at NewIndex, so NewIndex is its index after the move. The on-screen position is its display index: left-frozen columns first, then scrolling, then right-frozen columns, each in Columns order, without hidden ones (DataSource.DisplayColumns).
kumiko.ColumnReordered += (_, e) =>
{
// e.Column moved from Columns[e.OldIndex] to Columns[e.NewIndex]
int onScreen = kumiko.DataSource.GetDisplayIndex(e.Column);
Console.WriteLine($"{e.Column.Header} is now column {onScreen + 1} on screen");
};Move a column in code by display index; the index is kept within the column's pane and Columns follows:
var total = kumiko.Columns.First(c => c.PropertyName == "Total");
kumiko.DataSource.SetDisplayIndex(total, 0); // first in its paneGetLayoutState() takes what the user can change: column order, width, visibility and freeze mode, the sort, the column filters and the grouping. KumikoLayoutState.ToJson() turns it into a string to keep in a file or in preferences (MAUI's Preferences, Uno's ApplicationData.Current.LocalSettings), and ApplyLayoutState puts it back:
string layoutPath = Path.Combine(
Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData), "orders-grid-layout.json");
// Save, for example when the page closes
File.WriteAllText(layoutPath, kumiko.GetLayoutState().ToJson());
// Restore, after the columns are set up
if (File.Exists(layoutPath))
kumiko.ApplyLayoutState(KumikoLayoutState.FromJson(File.ReadAllText(layoutPath)));The JSON comes from a System.Text.Json source generator, so it works with Native AOT and full trimming. FromJson ignores properties it does not know and throws a JsonException for text that is not a layout.
Columns are matched by name: KumikoColumn.Key when you set it, otherwise PropertyName. Give a column a Key when it has no property name (a template or action column) or when two columns show the same property; a column with neither is not saved. Saved layouts survive changes to the columns: a saved column the grid no longer has is ignored, and a column the layout does not mention keeps its place and settings. The sort and the grouping are replaced as a whole. Restoring is one change (one rebuild); it raises the sort and filter events. A predicate set with DataSource.SetFilter, delegates such as GroupDescription.KeySelector and which groups are expanded are not saved; a saved group whose property is already grouped by keeps your GroupDescription with its selectors. Without a host control, KumikoLayoutState.Capture(source) and state.ApplyTo(source) do the same on a KumikoSource.
<!-- Pinned to the left -->
<core:KumikoColumn Header="Id" PropertyName="Id" IsFrozen="True" />
<!-- Pinned to the right -->
<core:KumikoColumn Header="Total" PropertyName="Total" FreezeMode="Right" />On a narrow screen the frozen columns can take too much of the width. When the columns do not all fit and the frozen ones together are wider than KumikoStyle.MaxFrozenColumnsWidthRatio of the grid (two thirds by default, less the row drag handle), the grid unpins columns until they fit: right-frozen columns first, starting with the one next to the scrolling columns, then left-frozen columns from the rightmost. An unpinned column scrolls with the others in the same on-screen order and is pinned again when the grid is wide enough; its FreezeMode does not change. So the two panes never overlap and every column can be scrolled to, tapped and reached with the keyboard.
Pin the first rows so they stay visible while the rest scroll:
<kumiko:KumikoDataGrid FrozenRowCount="2" />Action button columns draw a row of pill buttons in every cell; the buttons share the cell's width equally. A button runs an ICommand, an Action callback, or both. This answers the most common question about the grid: how to put a button bound to a view model command in each row (#2).
An action column is a Template column whose CustomCellRenderer is an ActionButtonsCellRenderer. Set PropertyName="" so the whole row item is the cell value. The renderer is an interactive cell (IInteractiveCellRenderer): a tap runs the button under the finger directly, without opening an editor. A tap raises no CellBeginEdit, CellEndEdit or CellValueChanged, and no view change, and it works in a read-only column. EditTriggers does not apply to it.
CanExecute. A button whoseCommand.CanExecute(parameter)is false is drawn disabled (the style'sActionButtonDisabledBackgroundColorandActionButtonDisabledTextColor) and does nothing when tapped. The parameter isCommandParameter, or the row item when that is not set. The renderer listens toCanExecuteChangedand the grid redraws; the listener holds the renderer weakly, andActionButtonsCellRenderer.Dispose()removes it. A button with only anActionis always enabled.- Keyboard. Enter on the current action cell runs its first button when that button is enabled. Tab stops at the column like any other editable column; give it
AllowTabStop="False"to skip it. - Safe commands. A command may remove the row it was run for, even the last one.
- A column with its own
EditorFactory,CustomEditorFactoryorEditorDescriptoris not interactive: the editor wins.
MauiActionButtonDefinition is a BindableObject, so every property, including Command, can be bound. It is not in the visual tree, so the grid hands it its own BindingContext (the page's view model, unless the grid sets another) and a plain {Binding Path} resolves against it; the grid redraws when a property of a definition changes. Its colors are MAUI Color values, like the grid's other color properties:
<kumiko:KumikoDataGrid x:Name="actionsGrid" ItemsSource="{Binding Employees}">
<core:KumikoColumn Header="Actions" PropertyName="" ColumnType="Template" Width="200"
AllowSorting="False" AllowFiltering="False">
<core:KumikoColumn.CustomCellRenderer>
<render:ActionButtonsCellRenderer>
<render:ActionButtonsCellRenderer.Buttons>
<kumiko:MauiActionButtonDefinition
Label="Details"
BackgroundColor="#0D6EFD"
Command="{Binding ViewDetailsCommand}" />
<kumiko:MauiActionButtonDefinition
Label="Delete"
BackgroundColor="#DC3545"
Command="{Binding DeleteCommand}" />
</render:ActionButtonsCellRenderer.Buttons>
</render:ActionButtonsCellRenderer>
</core:KumikoColumn.CustomCellRenderer>
</core:KumikoColumn>
</kumiko:KumikoDataGrid>UnoActionButtonDefinition is a DependencyObject, so every property, including Command, can be bound. It is not in the visual tree, so it cannot inherit DataContext; the grid gives it its own DataContext (the page's view model unless the grid sets one), so a plain {Binding} works. Its colors are Color values, like the grid's other color properties:
<kumiko:KumikoDataGrid x:Name="actionsGrid" ItemsSource="{Binding Employees}">
<core:KumikoColumn Header="Actions" PropertyName="" ColumnType="Template" Width="200"
AllowSorting="False" AllowFiltering="False">
<core:KumikoColumn.CustomCellRenderer>
<render:ActionButtonsCellRenderer>
<render:ActionButtonsCellRenderer.Buttons>
<kumiko:UnoActionButtonDefinition
Label="Details"
BackgroundColor="#FF0D6EFD"
Command="{Binding ViewDetailsCommand}" />
<kumiko:UnoActionButtonDefinition
Label="Delete"
BackgroundColor="#FFDC3545"
Command="{Binding DeleteCommand}" />
</render:ActionButtonsCellRenderer.Buttons>
</render:ActionButtonsCellRenderer>
</core:KumikoColumn.CustomCellRenderer>
</core:KumikoColumn>
</kumiko:KumikoDataGrid>To build the buttons in code, use ActionButtonDefinition from KumikoUI.Core (it works on both hosts):
var actionsColumn = new KumikoColumn
{
Header = "Actions",
PropertyName = "", // the row item is the cell value
ColumnType = KumikoColumnType.Template,
Width = 200,
AllowSorting = false,
AllowFiltering = false,
CustomCellRenderer = new ActionButtonsCellRenderer
{
Buttons =
{
new ActionButtonDefinition
{
Label = "Edit",
BackgroundColor = new KumikoColor(13, 110, 253),
Command = vm.EditCommand, // the row item is the CommandParameter by default
},
new ActionButtonDefinition
{
Label = "Delete",
BackgroundColor = new KumikoColor(220, 53, 69),
Command = vm.DeleteCommand, // CanExecute false draws it disabled
},
},
},
};
kumiko.Columns.Add(actionsColumn);| Button property | Type | Meaning |
|---|---|---|
Label |
string |
Text on the button |
BackgroundColor |
KumikoColor |
Pill color (R,G,B, R,G,B,A, #RGB, #RRGGBB, #AARRGGBB or a color name in XAML) |
TextColor |
KumikoColor |
Label color (default: white) |
Command |
ICommand? |
Executed on tap; the row item is the default parameter |
CommandParameter |
object? |
Overrides the row item as the parameter |
Action |
Action? |
Code-behind callback; runs in addition to Command when both are set |
ActionButtonsCellRenderer also has CornerRadius (default 5), ButtonSpacing (6) and CellPadding (4). To open the buttons as an editor instead, set CustomEditorFactory to create a DrawnActionButtons with the same Buttons; that editor raises the edit events.
Tap a column header to sort. The first tap depends on the column type: Boolean columns sort checked rows first and Date columns newest first (both Descending); text, numeric, ComboBox and Picker columns sort ascending. The next tap sorts the other way, and the third removes the sort. Set KumikoColumn.InitialSortDirection to choose a column's first direction; KumikoColumn.FirstSortDirection reports the one in effect.
Shift-tap or Ctrl-tap a header to add it to a multi-column sort (the header shows each column's place in the chain). Template and Image columns, and columns with neither a PropertyName nor a ValueAccessor, are not sortable unless you set AllowSorting.
Sort state belongs to the data source (a column's SortDirection and SortOrder are read-only):
// One column:
kumiko.DataSource.SetSort(lastNameColumn, KumikoSortDirection.Ascending);
// Several: the order is the column's place in the chain (1 = primary).
kumiko.DataSource.SetSort(departmentColumn, KumikoSortDirection.Ascending, 1);
kumiko.DataSource.SetSort(lastNameColumn, KumikoSortDirection.Descending, 2);
// Remove one column from the sort, or clear it:
kumiko.DataSource.SetSort(departmentColumn, KumikoSortDirection.None);
kumiko.DataSource.ClearSort();Batch changes so the view is rebuilt and repainted once. BeginUpdate() returns a scope that calls EndUpdate() when disposed; collection changes inside the batch are coalesced too:
using (kumiko.DataSource.BeginUpdate())
{
kumiko.DataSource.SetSort(lastNameColumn, KumikoSortDirection.Ascending);
kumiko.DataSource.SetFilter(item => ((Employee)item).IsActive);
kumiko.DataSource.AddGroupDescription(new GroupDescription("Department"));
}Sorting, grouping, filtering and Min/Max summaries share one comparer (KumikoSource.Comparer) that never throws: nulls come first, numbers compare by value across numeric types, dates and times chronologically, other values of one type through IComparable, and anything else by its text. Sorting is stable. Text compares in the source's culture, ignoring case by default:
kumiko.DataSource.Culture = CultureInfo.GetCultureInfo("de-DE"); // formatting, text order, parsing (default: current culture)
kumiko.DataSource.StringCompareOptions = CompareOptions.Ordinal; // case-sensitive (default: IgnoreCase)A column's CustomComparer replaces the comparer for that column's sort and grouping. SortChanging and SortChanged report sort changes, and SortChangedCommand runs on each one.
Each column header with AllowFiltering (the default) shows a filter icon. Tapping it opens the filter popup:
- two sort rows whose text follows the column type (A to Z, smallest to largest, newest to oldest, checked first), the first being the header's first-tap direction;
- a search box that narrows the value list;
- Select All and Deselect All, and a checklist of the column's distinct values;
- OK applies the checked values as the column's filter, Cancel (or a tap outside the popup) closes it without changes, and Clear removes the column's filter.
The value list scrolls by drag, mouse wheel, its scrollbar, and Up/Down, Page Up/Page Down, Space, Enter and Escape. Filters on several columns combine. The filter icon is drawn in FilterActiveIconColor while the column has a filter.
From code, filter by predicate or per column:
// Any rule over the item; combined with the column filters
kumiko.DataSource.SetFilter(item => ((Employee)item).Salary > 50_000m);
// A column filter: a set of display values and/or up to two conditions
var filter = new FilterDescription(departmentColumn)
{
SelectedValues = new HashSet<string> { "Engineering", "Sales" },
};
kumiko.DataSource.SetColumnFilter(departmentColumn, filter);
// Remove filters
kumiko.DataSource.SetFilter(null);
kumiko.DataSource.ClearAllFilters();FilterChanging and FilterChanged report filter changes.
Add GroupDescriptions to group rows, outermost first. Groups can be nested and expanded or collapsed. While grouping is active, a panel above the header shows one chip per level: tapping a chip flips that level's group order, and its remove button removes the level.
Declare grouping in XAML (both hosts); the collection is kept in sync with the data source and can change at runtime:
<kumiko:KumikoDataGrid ItemsSource="{Binding Employees}">
<kumiko:KumikoDataGrid.GroupDescriptions>
<core:GroupDescription PropertyName="Department" />
<core:GroupDescription PropertyName="Level" />
</kumiko:KumikoDataGrid.GroupDescriptions>
</kumiko:KumikoDataGrid>or in code, through the collection or the data source:
kumiko.GroupDescriptions.Add(new GroupDescription("Department"));kumiko.DataSource.AddGroupDescription(new GroupDescription("Level"));
kumiko.DataSource.ExpandAllGroups();
kumiko.DataSource.CollapseAllGroups();
kumiko.DataSource.ClearGroupDescriptions();The grid's GroupDescriptions and GroupSummaryRows replace whatever grouping was set on DataSource directly, so use one or the other. GroupDescription also has Header, KeySelector (group by a computed key), DisplayTextSelector and GroupSortDirection. Groups are ordered by their key (1, 2, 10; dates chronologically) and expanded by default. GroupExpanding and GroupExpandedChanged report expand and collapse. Dragging a row doesn't reorder it while grouping is active.
While a grouped grid scrolls, the header of the group the top rows belong to stays pinned at the top of the data area, so you always see which group you are in. With nested grouping, each level's header stacks below the one outside it. As the next group's header scrolls up, it pushes the pinned header out of the way.
A pinned header works like the real one: tapping it (or its chevron) expands or collapses that group, and collapsing it keeps the header where it was pinned. Keyboard navigation keeps the current row below the pinned headers. Sticky headers are on by default; to let group headers scroll away with their rows:
var style = kumiko.GridStyle;
style.StickyGroupHeaders = false;
kumiko.GridStyle = style;| Kind | Where | How |
|---|---|---|
| Table summary | One or more rows at the top or bottom of the grid | TableSummaryRows on the grid, or DataSource.AddTableSummaryRow |
| Group summary | A row after each group | GroupSummaryRows on the grid, or DataSource.AddGroupSummaryRow |
| Caption summary | Inside each group header | DataSource.CaptionSummary |
Summary types: Sum, Average, Count, Min, Max, and Custom (with SummaryColumnDescription.CustomAggregate, which receives the values).
<kumiko:KumikoDataGrid.TableSummaryRows>
<core:TableSummaryRow Name="Totals" Position="Bottom" Title="Totals">
<core:TableSummaryRow.Columns>
<core:SummaryColumnDescription PropertyName="Salary" SummaryType="Sum" Format="C0" />
<core:SummaryColumnDescription PropertyName="Id" SummaryType="Count" Label="Rows: " />
<core:SummaryColumnDescription PropertyName="Salary" SummaryType="Average" Format="C0"
Label="Avg: " />
</core:TableSummaryRow.Columns>
</core:TableSummaryRow>
</kumiko:KumikoDataGrid.TableSummaryRows>Bottom rows are pinned. Position="Bottom" rows are drawn as a footer fixed to the bottom of the viewport while the data scrolls (KumikoStyle.PinBottomSummaryRows, default true). Taps on the footer don't reach the rows behind it, and keyboard navigation keeps the current row above it. To draw them after the last row instead, as a totals row that scrolls with the data:
var style = kumiko.GridStyle;
style.PinBottomSummaryRows = false;
kumiko.GridStyle = style;Several aggregates of one property share that property's cell, in declaration order (Sum: $1,300 | Avg: $163); the summary row stays one line high, so make the column wide enough. A property with no column, or a hidden one, can still be aggregated, and property names match case-insensitively.
kumiko.DataSource.AddGroupSummaryRow(new GroupSummaryRow("Totals")
{
Title = "Total",
Levels = GroupSummaryLevels.All, // after every group level; Innermost (the default) only after the innermost
Columns =
{
new SummaryColumnDescription { PropertyName = "Salary", SummaryType = SummaryType.Sum, Format = "C0" },
new SummaryColumnDescription { PropertyName = "Salary", SummaryType = SummaryType.Average, Format = "C0", Label = "Avg: " },
},
});With Levels = All each group, outer or inner, gets a summary of all the rows beneath it.
kumiko.DataSource.CaptionSummary = new CaptionSummaryDescription
{
Columns = { new SummaryColumnDescription("Salary", SummaryType.Sum, "C0") },
};Sum and Average of decimal values are exact (a decimal result); integers and floating-point numbers give a double. Values that are not numbers (text, dates, booleans, nulls) are skipped. Min and Max use the grid's comparer. Summary values are formatted in DataSource.Culture. Read computed values with DataSource.ComputedTopSummaries, ComputedBottomSummaries and GetGroupSummaries(groupPath): Values (text) and RawValues are keyed by property, and Aggregates / GetRawValue(property, type) give each aggregate when a property has several.
EditTriggers chooses which gestures and keys open the editor. The default is DoubleTap, F2Key and Typing.
<kumiko:KumikoDataGrid EditTriggers="DoubleTap,F2Key,Typing"
EditTextSelectionMode="SelectAll"
DismissKeyboardOnEnter="True" />EditTrigger |
Opens the editor on |
|---|---|
SingleTap |
A tap on the cell |
DoubleTap |
A double-tap |
LongPress |
A long press |
F2Key |
F2, or Enter outside an edit |
Typing |
A typed character, which replaces the cell's text |
None |
Nothing: the column can't be edited by gesture or key, but isn't read-only |
EditTextSelectionMode is SelectAll (default) or CursorAtEnd. DismissKeyboardOnEnter (default true) ends editing on Enter; when false, Enter commits and opens the editor of the cell below.
A column's EditTriggers overrides the grid's (#6); null, the default, inherits it:
<kumiko:KumikoDataGrid EditTriggers="DoubleTap,F2Key,Typing">
<!-- Single tap, F2 or typing -->
<core:KumikoColumn Header="Name" PropertyName="Name" EditTriggers="SingleTap,F2Key,Typing" />
<!-- Double-tap or F2 only: no accidental typing edits -->
<core:KumikoColumn Header="Department" PropertyName="Department" ColumnType="ComboBox"
EditorItemsString="Engineering,Marketing,Finance,HR"
EditTriggers="DoubleTap,F2Key" />
<!-- Keyboard only -->
<core:KumikoColumn Header="Salary" PropertyName="Salary" ColumnType="Numeric" Format="C0"
EditTriggers="F2Key" />
</kumiko:KumikoDataGrid>Read-only columns (IsReadOnly="True") never open an editor or toggle.
A Boolean cell toggles in place:
- a tap on the check box toggles it; a tap elsewhere in the cell only selects, unless the column has the
SingleTaptrigger; - a double-tap toggles once (the second tap toggles with the
DoubleTaptrigger only when the first didn't); - a long press toggles with the
LongPresstrigger, and Space, Enter or F2 toggle the current Boolean cell; - a read-only column, or one with
EditTriggers="None", never toggles.
A toggle goes through the same validation as an edit. With IsThreeState="True" a toggle cycles unchecked, checked and indeterminate (a null value, drawn as a dash) instead of flipping between two states.
While a cell is being edited, the open editor sees every key first. In an open ComboBox dropdown, Up/Down (and Page Up/Down, Home, End) move the selection, Enter picks the item and commits it, Escape closes the dropdown and restores the value it opened with, and a typed letter jumps to the next item starting with it, or narrows the list when the column sets EditorIsFilterable. The dropdown scrolls by drag, mouse wheel and scrollbar. A key the editor does not use goes to the grid's edit keys (Enter, Escape, Tab and the arrows commit or cancel as above) and otherwise stops there: typing never restarts the edit, and Space never toggles the row's selection inside an editor.
The Picker's scroll wheel coasts and snaps, and confirms an item on Enter, on a tap on the centered item, or when it settles on one.
The date picker and the numeric up/down are culture-aware and accept typed entry, validated through the edit session. The calendar follows the culture's first day of the week, month and day names and date order; the date shows in the culture's short date format. Held +/- buttons and the arrow keys repeat with acceleration, and minimum and maximum limits are enforced (disabled days draw dimmed).
Editors draw with the grid's cell font (or the column's CellStyle font). ComboBox dropdowns, calendars and the filter popup open above the cell when there is no room below, and slide into the viewport; a dropdown shrinks and scrolls in a short grid.
- Enter: commit and move down.
- Tab / Shift+Tab: commit and move to the next or previous tab stop; past the last (or before the first), commit and let focus leave the grid.
- Escape: cancel and restore the original value.
- Tapping another cell, sorting, filtering, toggling a group or starting a drag commits first; when the value is refused, the gesture is ignored and the editor stays open with its message.
An open edit belongs to its item and column, not a row number. If rows move underneath it (a collection change, a sort or a filter from code), the commit still writes to that item; if the item is filtered out, collapsed or removed, the edit is canceled. The editor follows its cell while the grid scrolls and hides while the cell is out of view.
CellBeginEdit, CellEndEdit and CellValueChanged report an edit; CellValueChanged is raised after CellEndEdit, and only for a value that was written.
For a Template column, an EditorDescriptor describes the editor:
var rating = new KumikoColumn
{
Header = "Rating",
PropertyName = "Rating",
ColumnType = KumikoColumnType.Template,
EditorDescriptor = new NumericUpDownEditorDescriptor { Minimum = 0, Maximum = 10, Step = 1 },
};To create the editor yourself, set EditorFactory. Its CellEditorContext carries the value, the cell bounds, the grid's culture and the character typed to open the edit (InitialCharacter, null for a double-tap or F2):
var notes = new KumikoColumn
{
Header = "Notes",
PropertyName = "Notes",
ColumnType = KumikoColumnType.Template,
EditorFactory = context => new DrawnTextBox
{
Bounds = context.Bounds,
Text = context.InitialCharacter?.ToString() ?? context.Value?.ToString() ?? "",
MaxLength = 200,
},
};A custom editor's value is committed when it implements IValueEditor (Value, HasValue, IsDirty); all built-in editors do.
An edit is written only when the user changed the value. Opening an editor and leaving it never touches the cell: a combo box or picker whose cell value isn't in its list opens with nothing selected, and a date picker opens empty on an empty cell and keeps the cell's time of day when a new date is picked.
When a changed value is committed (Enter, Tab, leaving the cell), it goes through four steps:
- Conversion to the property's type, in
DataSource.Culture: every numeric type (whole numbers only for integer types, and in range),decimalat full precision,bool,char,Guid, enums (by name, or by a defined number),DateTime,DateTimeOffset,DateOnly,TimeOnly,TimeSpan,string, and the nullable form of each. Blank text clears a nullable property and is an error for a non-nullable one. Text that doesn't convert is an error ("Enter a number.", "Enter a whole number.", "Enter a valid date.", ...). The conversion isKumikoValueConverter.TryConvert, which you can call yourself. - The grid's validator,
CellValidator(a host property, also onEditSession), with the converted value. - The write. A setter that throws is an error, and its exception message is shown.
- The item's own validation.
IDataErrorInfoandINotifyDataErrorInfoare checked with the new value in place; an error writes the original value back.
kumiko.CellValidator = (row, column, value) => value switch
{
int quantity when quantity > 100 => CellValidationResult.Error("At most 100."),
int quantity when quantity > 50 => CellValidationResult.Warning("That's a large order."),
_ => CellValidationResult.Valid,
};
kumiko.ValidationFailed += (_, e) =>
Console.WriteLine($"{e.Column.Header}: {e.Message} ({e.Severity}, committed: {e.Committed})");| Result | Editor | Item | ValidationFailed |
|---|---|---|---|
| Error | stays open, with a red outline, an icon and the message under the cell | unchanged | raised, Committed = false |
| Warning, first commit | stays open, with an orange outline and the message | unchanged | raised, Committed = false |
| Warning, same value committed again | closes | written | raised, Committed = true |
Info (Severity = ValidationSeverity.Info) |
closes | written | raised, Committed = true |
Changing the value in the editor clears the message. While a value is refused, the gestures that would end the edit (sorting, filtering, grouping, a tap or long press on another cell, Tab, Enter, the navigation keys) are ignored and the editor stays focused. The editor shows numbers and dates in the grid's culture (3,5 under de-DE), so the text parses back to the same value. DataSource.SetCellValue converts the same way and returns whether the value was written.
Two settings on the data source localize the grid:
var source = kumiko.DataSource;
// Numbers, dates, text order, and the date picker's month names, day names and AM/PM
source.Culture = CultureInfo.GetCultureInfo("de-DE");
// Every piece of text the grid draws or reports on its own
source.Strings = KumikoStrings.Default with
{
GroupPanelLabel = "Gruppiert nach:",
BlankGroupText = "(Leer)",
SummarySum = "Summe: ",
FilterSelectAll = "Alle auswählen",
FilterOk = "Übernehmen",
FilterCancel = "Abbrechen",
SortTextAscending = "A bis Z sortieren",
SortNumericAscending = "Aufsteigend sortieren",
EnterNumber = "Geben Sie eine Zahl ein.",
};KumikoStrings is a record: start from KumikoStrings.Default (English) and replace what you need. It covers the grouping panel label and the group for empty values, the default summary labels, the filter popup (including its type-aware sort rows) and the validation messages. A message with {0} is a format string; keep the placeholder. Setting Strings or Culture rebuilds the view, so group headers and summaries follow.
<kumiko:KumikoDataGrid GridSelectionMode="Multiple" />KumikoSelectionMode |
Behavior |
|---|---|
None |
Nothing is selected; the current cell still moves |
Single |
One item at a time |
Multiple |
Each tap toggles the item |
Extended (default) |
A tap selects one item, Shift extends a range, Ctrl toggles |
Selection is by row and tracks items, not row numbers: after a sort, filter, regroup or collection change the same items stay selected (items that are filtered out or removed leave the selection), and the current cell stays on its item and column. Group header and summary rows are never selected. Cell selection is planned for 1.x (#108).
A tap on the empty part of the rows area (below the last row or right of the last column) commits an open edit and clears the selection and the current cell. Set ClearSelectionOnEmptyAreaTap="False" to keep them.
var selection = kumiko.Selection;
IReadOnlySet<object> items = selection.SelectedItems; // the selected data items
IReadOnlySet<int> rows = selection.SelectedRows; // their visible rows right now
object? current = selection.CurrentItem; // the current cell's item
selection.Select(employee); // or Deselect(employee)
selection.SelectRange(0, 9); // visible rows 0 to 9 (data rows only)
selection.SelectAll();
selection.Clear();
selection.SelectionChanged += (_, e) =>
{
// e.AddedItems, e.RemovedItems, e.SelectedRows, e.CurrentCell
};Both hosts expose the selection as bindable properties:
<kumiko:KumikoDataGrid ItemsSource="{Binding Employees}"
SelectedItem="{Binding SelectedEmployee, Mode=TwoWay}"
SelectedItems="{Binding SelectedEmployees, Mode=OneWay}"
SelectedIndex="{Binding SelectedRow, Mode=TwoWay}"
SelectionChangedCommand="{Binding SelectionChangedCommand}" />| Property / event | Meaning |
|---|---|
SelectedItem (two-way) |
The primary selected item: the current cell's item while it is selected, otherwise the item selected last; null when nothing is selected. Setting it selects only that item and moves the current cell to it. |
SelectedItems (IList) |
The selected items. By default an ObservableCollection<object> the grid owns and keeps in sync. Bind your own list to have the grid select its items and keep it updated; if it implements INotifyCollectionChanged, adding or removing items selects and deselects in the grid. Set null to go back to the owned collection. |
SelectedIndex (two-way) |
The visible row of SelectedItem, or -1; it follows the item through sort and filter. Setting it selects the item at that row. |
CurrentCell (two-way) |
The keyboard-focus cell as a CellPosition (visible row and column). |
SelectionChanged |
KumikoSelectionChangedEventArgs with AddedItems and RemovedItems; the properties above are already up to date. |
SelectionChangedCommand |
Executed on every selection change with SelectionChangedCommandParameter, or the event arguments when that is null. |
Setting SelectedItem to an item that is not visible, or any value in None mode, leaves the selection empty. A change made on one side is applied to the other without echoing back, so two-way bindings do not loop.
The keys are handled in KumikoUI.Core, the same way on every host. Which keys reach the grid depends on the host and platform; see Keys per platform.
| Key | Outside an edit | While editing |
|---|---|---|
| Arrow keys | Move the current cell (Shift extends the row selection). On a group header, Right expands and Left collapses | Move the caret; a key the editor doesn't use commits and moves |
| Home / End | First / last cell in the row; with Ctrl, first / last cell in the grid | Caret to the start / end |
| Page Up / Page Down | Move one page of rows | Commit and move |
| Tab / Shift+Tab | Next / previous tab stop, opening its editor when the column's triggers allow; past the last (first) one, the key is left to the page so focus moves on | Commit and move to the next / previous tab stop |
| Enter | Run the first action button of an action cell, toggle a Boolean cell, toggle a group header, or open the editor (F2Key trigger); otherwise left to the page |
Commit and move down (and keep editing when DismissKeyboardOnEnter is false) |
| F2 | Toggle a Boolean cell or open the editor (F2Key trigger) |
|
| Escape | Clear the selection and the current cell; with nothing to clear, left to the page | Cancel the edit |
| Space | Toggle a Boolean cell, toggle a group header, or toggle the current row's selection | Types a space |
| Ctrl+A | Select all rows | Select all text |
| Ctrl/Cmd+C | Copy the selected rows (see Copying rows) | Copy the selected text |
| Ctrl/Cmd+X, Ctrl/Cmd+V | Cut, paste | |
| Ctrl+Z, Ctrl+Shift+Z, Ctrl+Y | Undo, redo (a word at a time) | |
| A character | Open the editor with that character (Typing trigger) |
Type it |
Tab stops at every visible column that isn't read-only, whatever its type, unless the column sets AllowTabStop="False". Tab and Shift+Tab never trap focus: with no current cell, or no further tab stop, the grid leaves the key unhandled and the host moves focus to the next control. The current cell is always scrolled fully into view, clear of the grouping panel, header, top summaries, frozen rows and columns, sticky group headers and the pinned footer. The filter popup handles its own keys while it is open.
Each host captures the keyboard through a native input view, and that decides which keys arrive: a hidden TextBox on Uno, a UITextInput responder on MAUI for iOS and Mac Catalyst, an input view on MAUI for Android, and the grid's own platform view on MAUI for Windows. This table is derived from the host code (KumikoUI.Uno/Input/InputMapping.cs, KumikoUI.Maui/KeyInputResponder.cs, KumikoUI.Maui/AndroidTextInputMapper.cs and KumikoUI.Maui/Input/WindowsKeyInput.cs); the device results are in docs/maui-verification.md and docs/uno/verification.md.
| Key | Uno, every head (hardware keyboard) | MAUI on iOS and Mac Catalyst | MAUI on Android (hardware keyboard) | MAUI on Windows |
|---|---|---|---|---|
| Characters, Space, Backspace, Enter | Yes | Yes | Yes | Yes |
| Arrow keys (with Shift) | Yes | Yes | Yes | Yes |
| Home, End, Page Up, Page Down | Yes | Yes | Yes | Yes |
| Tab, Shift+Tab | Yes | Yes | Yes; past the last tab stop Android moves focus on | Yes |
| Escape, F2, Delete | Yes | Yes | Yes | Yes |
| Ctrl+A, editor undo / redo | Yes; Cmd works as Ctrl on macOS, iOS and WebAssembly | Yes, with Cmd | Yes (Ctrl or Meta) | Yes |
| Ctrl/Cmd+C, X, V | Yes | Yes | Yes | Yes |
On Android, pressing the grid gives it keyboard focus, so a hardware keyboard navigates it without opening an editor. The soft keyboard appears only while a cell editor or the filter popup's search box is open.
The MAUI control drives the editors through ITextInputSession on every platform: a native text-input client (UITextInput) on iOS and Mac Catalyst, an InputConnection on Android, and the Windows text services (CoreTextEditContext) on Windows. So input-method composition (Japanese, Chinese, Korean, Gboard word suggestions), the emoji keyboard, dictation, voice and swipe input reach the editor whole. On Windows the text services compose in place where the system offers them to desktop apps; elsewhere, characters and text committed by an input method's own window arrive through WinUI's CharacterReceived, and Ctrl+Alt (AltGr) types characters, not shortcuts. The Uno host does the same through the composition events of its hidden text box (KumikoTextInputAdapter): input-method composition (Japanese, Chinese, Korean, dead keys) reaches the editor as marked text and is committed when it ends. Composition has been exercised with Gboard on Android; on WebAssembly and iOS it is covered by unit tests only, because no composing input method could be driven there (docs/TEXT-INPUT.md).
To keep the edited cell visible above the soft keyboard on Android, set the activity's WindowSoftInputMode (docs/TEXT-INPUT.md).
Ctrl/Cmd+C copies the selected rows to the clipboard as tab-separated text that Excel and other spreadsheets paste into cells: one line per row, the visible columns in their on-screen order, values formatted as the cells show them. Set ClipboardCopyIncludesHeaders to start the text with a row of column headers. Copy, cut, paste and select-all also work inside cell editors and the filter popup's search box. A cut deletes the text only after the clipboard accepted it. The on-screen keyboard has no Ctrl key, so there is no copy from touch alone.
Clipboard (an IKumikoClipboard) defaults to the platform clipboard; assign another implementation to redirect copy and paste, or null to turn them off:
kumiko.ClipboardCopyIncludesHeaders = true;Rows can be reordered by dragging. Both switches are bindable on the grid, RowReordered reports a move, and RowReorderRejected reports a drop the grid refused:
<kumiko:KumikoDataGrid ShowRowDragHandle="True" AllowRowDragDrop="False" />- Drag handle (
ShowRowDragHandle): a handle column on each row; a vertical drag that starts on a handle moves the row.KumikoStyle.RowDragHandlePositionputs it on theLeft(default) orRight, andRowDragHandleWidthsets its width. - Whole row (
AllowRowDragDrop): on touch, a swipe on a row scrolls the grid and a long press starts the drag (a column whose edit triggers includeLongPressedits on a long press instead). With a mouse or pen, a mostly vertical drag past a few pixels starts it. The handle starts on a small movement in any direction, on every device. - Autoscroll: dragging within
ScrollSettings.AutoScrollEdgeSize(40) of the top or bottom of the scrolling rows scrolls the grid, faster toward the edge up toAutoScrollMaxSpeed(1,200 px/s).
A drop moves the item in ItemsSource, and the view is rebuilt. Rows move within their group: a drop that would cross groups is refused. A drop is also refused while a sort is active (the sort would put the row back) and when ItemsSource is not a writable, resizable IList (an array, for example). A refused drop changes nothing and raises RowReorderRejected, whose Result says why (KumikoReorderResult: NotSupportedSorted, NotSupportedSource, NotSupportedAcrossGroups or OutOfRange). RowReordered is raised once, after a move that happened.
kumiko.RowReordered += (_, e) =>
Console.WriteLine($"{e.DataItem} moved from row {e.OldIndex} to row {e.NewIndex}");
kumiko.RowReorderRejected += (_, e) =>
Console.WriteLine($"Row {e.OldIndex} was not moved: {e.Result}");When you reorder in code, DataSource.ReorderRow returns the same KumikoReorderResult.
kumiko.Theme = KumikoThemeMode.Dark; // Light (default), Dark or HighContrastTheme replaces GridStyle with KumikoTheme.Create(mode). Theme, GridStyle and ScrollSettings are bindable on both hosts, so XAML can set or bind them:
<kumiko:KumikoDataGrid Theme="Dark" />On .NET MAUI the theme can follow the app's theme binding:
<kumiko:KumikoDataGrid Theme="{AppThemeBinding Light=Light, Dark=Dark}" />Following the system theme. FollowSystemTheme is on by default until you set Theme or GridStyle: the grid then shows the Light or Dark preset to match the operating system or app theme, and switches when it changes, so a default grid is dark in a dark app. Assigning Theme or GridStyle turns following off, unless you also set FollowSystemTheme yourself. The grid never switches to HighContrast by itself.
Every color, font, size and line width is a property of KumikoStyle. Change the style and assign it back, which repaints the grid and re-applies the host properties you set explicitly (see Precedence):
var style = KumikoTheme.Create(KumikoThemeMode.Light); // or kumiko.GridStyle
style.BackgroundColor = new KumikoColor(242, 242, 247);
style.AlternateRowColor = new KumikoColor(230, 230, 237);
style.HeaderBackgroundColor = new KumikoColor(51, 102, 204);
style.HeaderTextColor = KumikoColor.White;
style.SelectionColor = new KumikoColor(51, 102, 204, 60);
style.GridLineColor = new KumikoColor(204, 204, 204);
style.FrozenColumnDividerColor = new KumikoColor(102, 102, 102);
style.HeaderFont = new KumikoFont("Default", 14, bold: true);
style.CellFont = new KumikoFont("Default", 13);
style.ShowHorizontalGridLines = true;
style.ShowVerticalGridLines = false;
kumiko.GridStyle = style;KumikoColor takes bytes (R, G, B and an optional A) and has named colors such as White, Black and Transparent. In XAML, a KumikoColor property accepts R,G,B, R,G,B,A, #RGB, #ARGB, #RRGGBB, #AARRGGBB (alpha first, as in XAML and MAUI), any CSS color name (Orange, CornflowerBlue, SlateGray, ... in any case) and Transparent; text it cannot read throws a FormatException that names it. KumikoFont is a value (a readonly record struct): two fonts with the same content are equal, and you change one with with (style.CellFont = style.CellFont with { Size = 16 }). It has Family ("Default" is the platform font, or a family you registered, see Custom Fonts), Size, IsBold and IsItalic.
CellStyleResolver and RowStyleResolver on the style return overrides for one cell or row at draw time:
var style = kumiko.GridStyle;
style.CellStyleResolver = (item, column) =>
column.PropertyName == "Salary" && item is Employee e && e.Salary > 100_000m
? new KumikoCellStyle { TextColor = new KumikoColor(204, 26, 26), Font = new KumikoFont("Default", 13, bold: true) }
: null;
style.RowStyleResolver = item =>
item is Employee { IsActive: false } ? new KumikoRowStyle { TextColor = KumikoColor.Gray } : null;
kumiko.GridStyle = style;KumikoCellStyle has BackgroundColor, TextColor, Font, Padding and TextAlignment; KumikoRowStyle has BackgroundColor, TextColor and Font (every row has the grid's RowHeight; variable row height is tracked in #102). Every member is nullable, and null means "no override". A cell's style is composed from the cell resolver, then the column's CellStyle, then the row resolver's text color and font, then the grid style; the row resolver's background is drawn behind unselected rows. Resolvers run for every visible cell on every frame, so return cached instances rather than allocating new ones where you can.
Every settable member of KumikoStyle (KumikoUI.Core.Models), with its value in the Light theme (the default). KumikoTheme.CreateDark() and CreateHighContrast() change the colors. Sizes are in device-independent pixels. Version (read-only) counts changes; the renderer rebuilds its paints only when the style instance or its Version changes.
| Sizing | Type | Light | Meaning |
|---|---|---|---|
HeaderHeight |
float |
40 | Height of the header row (also the grid's HeaderHeight) |
RowHeight |
float |
36 | Height of each data row (also the grid's RowHeight) |
CellPadding |
float |
8 | Horizontal padding inside data cells |
| Colors | Type | Light | Meaning |
|---|---|---|---|
BackgroundColor |
KumikoColor |
White | Background of the grid canvas |
HeaderBackgroundColor |
KumikoColor |
230, 230, 230 | Background of the header row |
HeaderTextColor |
KumikoColor |
Black | Header text |
CellTextColor |
KumikoColor |
30, 30, 30 | Data cell text |
GridLineColor |
KumikoColor |
220, 220, 220 | Horizontal and vertical grid lines |
CheckBoxBorderColor |
KumikoColor? |
null (GridLineColor) |
Outline of a Boolean cell's check box |
SelectionColor |
KumikoColor |
0, 120, 215, 60 | Fill of selected rows |
SelectionTextColor |
KumikoColor |
255, 255, 255 | Text of selected cells, for custom renderers. Not used by the built-in drawing |
FocusedRowColor |
KumikoColor |
0, 120, 215, 30 | Highlight of the current row |
AlternateRowColor |
KumikoColor |
245, 245, 245 | Background of every second row |
SortIndicatorColor |
KumikoColor |
100, 100, 100 | Sort arrow in the header |
CurrentCellBorderColor |
KumikoColor |
0, 120, 215 | Border of the current cell |
CurrentCellBorderWidth |
float |
2 | Width of the current cell border |
AccentColor |
KumikoColor |
0, 120, 215 | Accent for interactive elements such as check marks |
| Fonts | Type | Light | Meaning |
|---|---|---|---|
HeaderFont |
KumikoFont |
14, bold | Header text |
CellFont |
KumikoFont |
13 | Data cell text |
| Header | Type | Light | Meaning |
|---|---|---|---|
HeaderBorderColor |
KumikoColor |
200, 200, 200 | Line below the header row |
HeaderPadding |
float |
8 | Padding inside header cells (instead of CellPadding) |
| Grid lines and alternate rows | Type | Light | Meaning |
|---|---|---|---|
GridLineWidth |
float |
1 | Width of grid lines |
ShowHorizontalGridLines |
bool |
true | Lines between rows |
ShowVerticalGridLines |
bool |
true | Lines between columns |
AlternateRowBackground |
bool |
true | Shade every second row with AlternateRowColor |
| Frozen columns and rows | Type | Light | Meaning |
|---|---|---|---|
FrozenColumnDividerColor |
KumikoColor |
180, 180, 180 | Divider between left-frozen and scrolling columns |
FrozenColumnDividerWidth |
float |
2 | Width of that divider |
FrozenColumnBackgroundColor |
KumikoColor |
250, 250, 250 | Background of left-frozen cells |
RightFrozenColumnDividerColor |
KumikoColor |
180, 180, 180 | Divider between scrolling and right-frozen columns |
RightFrozenColumnDividerWidth |
float |
2 | Width of that divider |
RightFrozenColumnBackgroundColor |
KumikoColor |
250, 250, 250 | Background of right-frozen cells |
MaxFrozenColumnsWidthRatio |
float |
0.667 (two thirds) | Largest share of the width the frozen columns keep when the grid scrolls; beyond it columns are unpinned (see Frozen columns and rows) |
FrozenRowDividerColor |
KumikoColor |
180, 180, 180 | Divider below frozen rows |
FrozenRowDividerWidth |
float |
2 | Width of that divider |
FrozenRowBackgroundColor |
KumikoColor |
250, 250, 250 | Background of frozen rows |
| Filter | Type | Light | Meaning |
|---|---|---|---|
FilterIconColor |
KumikoColor |
140, 140, 140 | Filter icon in headers |
FilterActiveIconColor |
KumikoColor |
0, 120, 215 | Filter icon of a column with an active filter |
| Grouping | Type | Light | Meaning |
|---|---|---|---|
GroupHeaderBackgroundColor |
KumikoColor |
240, 240, 240 | Background of group header rows |
GroupHeaderTextColor |
KumikoColor |
40, 40, 40 | Group header text, including the item count and caption summary |
GroupHeaderCountColor |
KumikoColor |
120, 120, 120 | Item count in group headers. Not used by the built-in drawing |
GroupChevronColor |
KumikoColor |
80, 80, 80 | Expand and collapse chevron |
GroupChevronBackgroundColor |
KumikoColor |
220, 225, 235 | Background behind the chevron |
GroupHeaderFont |
KumikoFont |
13, bold | Group header text, including the item count and caption summary |
GroupCountFont |
KumikoFont |
12 | Item count in group headers. Not used by the built-in drawing |
GroupIndentWidth |
float |
24 | Indent per grouping level |
GroupChevronSize |
float |
14 | Size of the chevron |
StickyGroupHeaders |
bool |
true | Pin the current groups' headers at the top while their rows scroll (Sticky group headers) |
GroupPanelHeight |
float |
40 | Height of the grouping panel |
GroupPanelBackgroundColor |
KumikoColor |
248, 249, 252 | Background of the grouping panel |
GroupPanelTextColor |
KumikoColor |
100, 105, 115 | Text in the grouping panel |
GroupPanelLabelColor |
KumikoColor |
130, 135, 145 | The panel's label ("Grouped by:") |
GroupPanelLabelFont |
KumikoFont |
11 | The panel's label |
GroupPanelFont |
KumikoFont |
12, bold | Chip labels |
GroupPanelChipBackgroundColor |
KumikoColor |
230, 235, 245 | Chip background |
GroupPanelChipBorderColor |
KumikoColor |
180, 190, 210 | Chip border |
GroupPanelChipAccentColor |
KumikoColor |
60, 120, 215 | Chip accent and sort arrow |
GroupPanelChipTextColor |
KumikoColor |
40, 45, 55 | Chip text |
GroupPanelChipRemoveColor |
KumikoColor |
140, 145, 155 | Chip remove button |
| Action buttons | Type | Light | Meaning |
|---|---|---|---|
ActionButtonDisabledBackgroundColor |
KumikoColor |
222, 226, 230 | Background of a button whose command can't execute |
ActionButtonDisabledTextColor |
KumikoColor |
134, 142, 150 | Label of a button whose command can't execute |
| Summaries | Type | Light | Meaning |
|---|---|---|---|
SummaryRowBackgroundColor |
KumikoColor |
235, 240, 248 | Background of table summary rows |
SummaryRowTextColor |
KumikoColor |
30, 30, 30 | Table summary values |
SummaryRowFont |
KumikoFont |
13, bold | Table summary values |
SummaryRowLabelColor |
KumikoColor |
100, 100, 100 | Table summary labels and titles |
SummaryRowLabelFont |
KumikoFont |
12 | Table summary labels. Not used by the built-in drawing |
SummaryRowHeight |
float |
36 | Height of table summary rows |
SummaryRowBorderColor |
KumikoColor |
200, 200, 200 | Border of table summary rows |
PinBottomSummaryRows |
bool |
true | Pin Position=Bottom table summary rows as a footer; false draws them after the last row |
GroupSummaryRowBackgroundColor |
KumikoColor |
242, 245, 250 | Background of group summary rows |
GroupSummaryRowTextColor |
KumikoColor |
50, 50, 50 | Group summary values |
GroupSummaryRowFont |
KumikoFont |
12, bold | Group summary values |
CaptionSummaryTextColor |
KumikoColor |
100, 100, 100 | Caption summaries in group headers. Not used by the built-in drawing (they use the group header's color) |
CaptionSummaryFont |
KumikoFont |
11 | Caption summaries in group headers. Not used by the built-in drawing (they use the group header's font) |
| Row drag and drop | Type | Light | Meaning |
|---|---|---|---|
AllowRowDragDrop |
bool |
false | Drag a row from any cell (also the grid's AllowRowDragDrop) |
ShowRowDragHandle |
bool |
false | Show a drag handle on each row (also the grid's ShowRowDragHandle) |
RowDragHandlePosition |
DragHandlePosition |
Left | Side of the drag handle column |
RowDragHandleWidth |
float |
32 | Width of the drag handle column |
RowDragHandleColor |
KumikoColor |
160, 160, 160 | Drag handle glyph |
RowDragHandleBackgroundColor |
KumikoColor |
248, 248, 248 | Background of the drag handle column |
RowDragHandleHeaderBackgroundColor |
KumikoColor |
235, 235, 235 | Background of the drag handle column's header |
RowDragOverlayColor |
KumikoColor |
255, 255, 255, 200 | Overlay on the row being dragged |
RowDragBorderColor |
KumikoColor |
0, 120, 215 | Border around the row being dragged |
RowDropIndicatorColor |
KumikoColor |
0, 120, 215 | Line marking the drop position |
RowDropIndicatorWidth |
float |
2 | Width of that line |
| Icons | Type | Light | Meaning |
|---|---|---|---|
IconProvider |
IKumikoIconProvider |
KumikoIconProvider.Default |
Draws every built-in glyph of the grid and of its editors and filter popup (see Icons); never null |
| Conditional styles | Type | Light | Meaning |
|---|---|---|---|
CellStyleResolver |
Func<object, KumikoColumn, KumikoCellStyle?>? |
null | Per-cell overrides from the row item and column |
RowStyleResolver |
Func<object, KumikoRowStyle?>? |
null | Per-row overrides from the row item |
Everything below exists on both hosts with the same name and default: KumikoUI.Maui.KumikoDataGrid (bindable properties) and KumikoUI.Uno.KumikoDataGrid (dependency properties). On Uno, set Mode=TwoWay explicitly where a binding should write back. Color properties use each host's color type (Microsoft.Maui.Graphics.Color on MAUI, Windows.UI.Color on Uno) and map to KumikoColor.
| Property | Type | Default | Meaning |
|---|---|---|---|
ItemsSource |
IEnumerable |
null | The rows; an INotifyCollectionChanged source is followed. |
Columns |
ObservableCollection<KumikoColumn> |
empty | Column definitions (the XAML content property). Never null. |
TableSummaryRows |
ObservableCollection<TableSummaryRow> |
empty | Table summary rows. |
GroupDescriptions |
ObservableCollection<GroupDescription> |
empty | Grouping, outermost first; synced to DataSource. |
GroupSummaryRows |
ObservableCollection<GroupSummaryRow> |
empty | Summary rows after each group; synced to DataSource. |
GridSelectionMode |
KumikoSelectionMode |
Extended |
None, Single, Multiple or Extended. |
SelectedItem, SelectedItems, SelectedIndex, CurrentCell |
see Selection in MVVM | Selection state. | |
ClearSelectionOnEmptyAreaTap |
bool |
true | A tap below the last row or right of the last column clears the selection. |
FrozenRowCount |
int |
0 | Top rows frozen while scrolling. |
RowHeight, HeaderHeight |
double |
36, 40 | Row and header heights. |
EditTriggers |
EditTrigger |
Default (DoubleTap, F2Key, Typing) |
Gestures and keys that start editing. |
EditTextSelectionMode |
EditTextSelectionMode |
SelectAll |
Text selection when editing starts. |
DismissKeyboardOnEnter |
bool |
true | Enter ends editing; false keeps editing on the next row. |
CellValidator |
Func<int, int, object?, CellValidationResult> |
null | Validates a converted value before it is written (row, column, value). |
ShowHorizontalGridLines |
bool? |
null (style: on) | Lines between rows. |
ShowVerticalGridLines |
bool? |
null (style: on) | Lines between columns. |
AlternateRowBackground |
Color? |
null (style) | Color of alternate rows; setting it also turns shading on. |
AllowRowDragDrop |
bool? |
null (style: off) | Drag a row from any cell. |
ShowRowDragHandle |
bool? |
null (style: off) | Drag handle on each row. |
ShowFrameStats |
bool |
false | Frame-time overlay (Performance). |
GridDescription |
string? |
null ("Data grid") | Accessible name; null uses KumikoStrings.AccessibleGridName (Accessibility). |
GridHint |
string? |
null (computed) | Accessible hint; null describes the row and column counts and the current cell. |
AnnounceChanges |
bool |
true | Announce the current cell, sort changes, edits and validation errors to a screen reader. |
Theme |
KumikoThemeMode |
Light |
Built-in theme; bindable. |
GridStyle |
KumikoStyle |
the Light style | The full style; bindable. |
FollowSystemTheme |
bool |
true until a theme or style is set | Follow the system light/dark setting at run time (Built-in themes). |
ScrollSettings |
ScrollSettings |
defaults | Scrolling and inertia (Scrolling); bindable. |
VerticalOffset, HorizontalOffset |
double |
0 | The scroll offsets; two-way (Scrolling). |
Clipboard |
IKumikoClipboard? |
the platform clipboard | Used for copy, cut and paste; null turns them off (Copying rows). |
ClipboardCopyIncludesHeaders |
bool |
false | Ctrl/Cmd+C starts the copied text with the column headers. |
RenderMode |
KumikoRenderMode |
Auto |
The drawing surface; ActiveRenderMode reports the one in use. MAUI: Auto rasterizes on the GPU (SKGLView) on Android and Mac Catalyst and on the CPU (SKCanvasView) on iOS and Windows; Hardware (the GPU view) and Software ask for one. Uno: Auto draws through Uno's GPU-backed SKCanvasElement on the Skia-rendered heads and through SKXamlCanvas elsewhere; Hardware and Software ask for one. |
IsReadOnly |
bool |
false | True refuses every edit, Boolean toggle and Tab stop; combines with KumikoColumn.IsReadOnly. |
AllowSorting, AllowFiltering |
bool |
true | False stops header-tap sorting, or hides and disables the header filter icons; a grid-level false wins over the column's setting. |
Methods: ScrollToRow, ScrollToItem, ScrollToColumn (Scrolling), GetLayoutState and ApplyLayoutState (Saving and restoring the layout) and SetCellRenderer(KumikoColumnType, ICellRenderer), which replaces the built-in renderer for every column of a type. Read-only members give access to the engine: DataSource (KumikoSource: data, sort, filter, grouping, summaries, culture, strings), Selection (KumikoSelectionModel), EditSession and InputController (KumikoInputController).
Each command is executed with the event arguments as its parameter (SelectionChangedCommand uses SelectionChangedCommandParameter when it is set).
| Command | Parameter | Executed when |
|---|---|---|
RowTappedCommand |
RowTappedEventArgs |
A row was tapped. |
CellTappedCommand |
KumikoCellTappedEventArgs |
A data cell was tapped (primary button or a finger). |
HeaderTappedCommand |
KumikoHeaderTappedEventArgs |
A column header was tapped, after it sorted. |
ContextMenuRequestedCommand |
KumikoContextRequestedEventArgs |
The user asked for a context menu (Context menus). |
CellValueChangedCommand |
CellValueChangedEventArgs |
An edit changed a cell value. |
SortChangedCommand |
SortColumnsChangedEventArgs |
The sort changed. |
SelectionChangedCommand |
KumikoSelectionChangedEventArgs |
The selection changed. |
RowTapped, RowDoubleTapped, CellTapped, HeaderTapped, ContextMenuRequested, CellBeginEdit, CellEndEdit, CellValueChanged, ValidationFailed, SortChanging, SortChanged, FilterChanging, FilterChanged, ViewChanged, GroupExpanding, GroupExpandedChanged, RowReordered, RowReorderRejected, ColumnReordered, ColumnResized, Scrolled and SelectionChanged. They forward to the matching events on DataSource, InputController, EditSession and Selection (ColumnReordered is raised by the grid once it has moved the column), which stay available for anything not listed (for example ScrollState.ScrollChanged through a custom host, or InputController.CursorChanged).
DataSource.ViewChanged reports every change of the view once, with its kind (Redraw, Rebuild, Insert, Remove); MapRow(oldRow) follows a row from before the change to after it, and GetViewRow(item) finds an item's row.
Only the primary mouse button (or a finger) selects, sorts, scrolls, drags and edits. A right click, and a long press with a finger or a pen, raise ContextMenuRequested instead (InputController.ContextRequested in Core) with what is under the point: Region (a cell, a header, a group row, the empty area), RowIndex, ColumnIndex, Column, DataItem, the position X/Y relative to the grid, IsHeader and Trigger (SecondaryButton or LongPress). A right click raises it when the button is released and never sorts, drags or edits; a long press raises it unless it starts a row drag (AllowRowDragDrop on touch, or the drag handle) or the cell edits on a long press (the LongPress edit trigger), and lifting the finger afterwards does not tap. A middle click does nothing.
On a data row the grid updates the selection first, as file managers and spreadsheets do: a row that is not selected becomes the selection, a row that is already selected keeps the whole selection (so a menu can act on every selected row), and the current cell moves to the cell under the point. An open edit on another cell is committed first; a right click inside the open editor, inside a popup, or one that closes a popup raises nothing.
kumiko.ContextMenuRequested += (sender, e) =>
{
if (e.IsHeader)
Console.WriteLine($"Column menu for {e.Column?.Header}");
else if (e.DataItem is Employee employee)
Console.WriteLine($"Row menu for {employee.Name}, {kumiko.Selection.SelectedItems.Count} selected ({e.Trigger})");
};On Uno, open a MenuFlyout at the pointer:
kumiko.ContextMenuRequested += (sender, e) =>
{
var menu = new Microsoft.UI.Xaml.Controls.MenuFlyout();
menu.Items.Add(new Microsoft.UI.Xaml.Controls.MenuFlyoutItem { Text = e.IsHeader ? "Clear sort" : "Delete row" });
menu.ShowAt(kumiko, new Microsoft.UI.Xaml.Controls.Primitives.FlyoutShowOptions
{
Position = new Windows.Foundation.Point(e.X, e.Y),
});
};MAUI cannot open a menu at a point, so the sample app shows an action sheet (DisplayActionSheetAsync). Right clicks are reported on Windows, Mac Catalyst and iPad (with a mouse or trackpad), and Android (with a mouse); CellTapped and HeaderTapped report primary taps with the column and the position.
From highest to lowest: the explicit properties below, together with RowHeight and HeaderHeight; then whichever of Theme or GridStyle was assigned last; then the system theme, while FollowSystemTheme is on. The order of attributes in XAML does not matter. Assigning GridStyle or ScrollSettings null resets it to the preset or the default settings.
ShowHorizontalGridLines, ShowVerticalGridLines, AlternateRowBackground, AllowRowDragDrop and ShowRowDragHandle are nullable. Null leaves the value to GridStyle and Theme; a value overrides it. Setting one writes it into the current style immediately, and assigning GridStyle or Theme afterwards re-applies every explicit value to the new style, so an explicit property wins over the theme in either order. Setting a property back to null stops overriding but doesn't restore the earlier value until the next style or theme assignment.
Invalidate() repaints the grid from its current state without rebuilding the view, and is safe to call from any thread. Use it after changing something the grid can't observe, such as a property of a style object you hold. DataSource.Refresh() rebuilds the view; it is needed only when data changed behind the grid's back.
The grid draws text with SkiaSharp, not with the platform's text views. It looks a KumikoFont family up in SkiaFontRegistrar (KumikoUI.SkiaSharp) first and then asks SkiaSharp's system font manager, so a font registered only with MAUI (ConfigureFonts) or bundled for WinUI isn't guaranteed to be found. Register the typeface with SkiaFontRegistrar under a family name, then use that name in a KumikoFont. This is the fix for two problems seen on Android (#5): Japanese, Chinese or Korean text drawn garbled or as boxes, and icon-font glyphs drawn as the wrong characters, because the system font manager doesn't give SkiaSharp those typefaces.
The library ships no fonts; your app supplies them.
Put the font files in Resources/Raw/ (the project template's MauiAsset item exposes them under their file name) and register them with KumikoFonts when the app starts, before the first grid draws:
private static void RegisterFonts()
{
// Not awaited: it completes quickly and never throws for a font problem.
_ = KumikoFonts.RegisterFromAppPackageAsync(new[]
{
("NotoSansJP", "NotoSansJP-Regular.ttf"),
("MaterialIcons", "MaterialIcons-Regular.ttf"),
});
}Call RegisterFonts() from the App constructor.
Fonts you add with ConfigureFonts are bridged into the grid renderer by UseKumikoUI(), so they need no extra call.
Put the font files in the app project as Content (for example Assets/Fonts/*.ttf) and register them with KumikoFonts in App.OnLaunched, before the window is activated:
protected override async void OnLaunched(LaunchActivatedEventArgs args)
{
await KumikoFonts.RegisterFromAppPackageAsync(new[]
{
("NotoSansJP", "ms-appx:///Assets/Fonts/NotoSansJP-Regular.ttf"),
("MaterialIcons", "ms-appx:///Assets/Fonts/MaterialIcons-Regular.ttf"),
});
// ... create and activate the window
}RegisterFromAppPackageAsync (the same on both hosts) is asynchronous and never throws for a font problem: a missing or unreadable font is logged with Debug.WriteLine and the grid uses the default font. KumikoFonts.RegisterFromStream(family, stream) registers a stream you opened yourself and does throw on an unreadable font.
Fonts added with ConfigureFonts also reach the grid once UseKumikoUI() is called, so a font alias from fonts.AddFont("MyFont.ttf", "MyAlias") can be used as a KumikoFont family directly; registering with SkiaFontRegistrar is needed only for fonts that ConfigureFonts doesn't cover.
var style = kumiko.GridStyle;
style.HeaderFont = new KumikoFont("NotoSansJP", 14, bold: true);
style.CellFont = new KumikoFont("NotoSansJP", 13);
kumiko.GridStyle = style;For an icon font, store the glyph's code point as the cell value and draw it with a renderer that uses the icon family:
public sealed class IconFontCellRenderer(string fontFamily, float fontSize) : ICellRenderer
{
// Created once and reused: only the color changes per cell
private readonly KumikoPaint _paint = new() { Font = new KumikoFont(fontFamily, fontSize), IsAntiAlias = true };
public void Render(IDrawingContext ctx, in CellRenderContext cell)
{
if (string.IsNullOrEmpty(cell.DisplayText)) return;
_paint.Color = cell.Style.CellTextColor;
ctx.DrawTextInRect(cell.DisplayText, cell.Bounds, _paint,
KumikoTextAlignment.Center, KumikoVerticalAlignment.Center);
}
}kumiko.Columns.Add(new KumikoColumn
{
Header = "Status",
PropertyName = "StatusIcon", // for example "\uE876", the Material Icons check mark
Width = 60,
IsReadOnly = true,
CustomCellRenderer = new IconFontCellRenderer("MaterialIcons", 22f),
});Bold and italic. A family can hold several faces. Register the bold or italic file under the same family name with a SKFontStyle, and bold or italic text uses the closest registered face. When the closest face lacks the style (a bold font with only a regular face registered), the text is emboldened or slanted synthetically.
Fallback fonts. Text that the requested font has no glyph for (emoji, CJK, symbols) is drawn glyph by glyph with a fallback font: first the families you list with SetFallbackFamilies, in order, then the platform font manager's own choice. An emoji sequence or a letter with combining marks is never split between two fonts, and an emoji sequence (a skin tone, a family, a flag) is drawn as the one glyph the emoji font has for it.
using KumikoUI.SkiaSharp;
using SkiaSharp;
public static class FontSetup
{
public static void Register(System.IO.Stream regular, System.IO.Stream bold, System.IO.Stream emoji)
{
SkiaFontRegistrar.RegisterTypefaceFromStream("NotoSansJP", regular);
SkiaFontRegistrar.RegisterTypefaceFromStream("NotoSansJP", bold, SKFontStyle.Bold);
SkiaFontRegistrar.RegisterTypefaceFromStream("NotoEmoji", emoji);
SkiaFontRegistrar.SetFallbackFamilies("NotoSansJP", "NotoEmoji");
}
}SkiaFontRegistrar member |
Description |
|---|---|
RegisterTypefaceFromStream(family, stream) |
Creates a typeface from a stream and registers it; the registrar owns it and disposes it when the family is replaced, unregistered or cleared. The stream may be disposed after the call. |
RegisterTypeface(family, typeface) |
Registers an SKTypeface you keep ownership of. |
RegisterTypefaceFromStream(family, stream, style), RegisterTypeface(family, typeface, style) |
Registers one face of a family for a SKFontStyle (bold, italic, ...). |
SetFallbackFamilies(params string[]) |
Sets FallbackFamilies, the families tried, in order, for characters the requested font can't draw. |
TryGetTypeface(family, out typeface) |
Looks up a registered family (an overload takes a SKFontStyle). |
IsRegistered(typeface) |
Whether a typeface is registered under any family. |
Unregister(family) |
Removes one family. |
Clear() |
Removes every registration and the fallback families. |
Version |
Incremented by every change. |
All members are thread-safe, and changes are safe while grids are alive: every grid drops the affected family before anything is disposed. A family name the platform can't resolve falls back to the default font in the same weight and slant, and is logged once through Trace.TraceWarning.
Every glyph the grid draws comes from one replaceable icon provider, KumikoStyle.IconProvider (KumikoUI.Core.Rendering): the group header chevrons, the sort arrows (headers, grouping chips and the filter popup), the filter button and its active state, the grouping chips' remove button and separator, the row drag grip, the check marks of boolean cells, check boxes and the filter popup, the combo box's dropdown arrow, the numeric editor's plus and minus, and the date picker's calendar button, month arrows and time arrows. Each slot is a KumikoIcon value. Glyph colors still come from the style (SortIndicatorColor, FilterActiveIconColor, GroupChevronColor, ...), so icons follow the theme; the provider decides the shape. Taps hit the same slots whatever is drawn in them.
Built-in set. KumikoIconProvider.Default draws each icon as filled polygons and joined strokes scaled to its slot. It is the default.
Icon fonts. KumikoFontIconProvider draws each icon as a glyph of an icon font, in the icon's color, centered in its slot. Register the font first (see Custom Fonts), then map icons to code points. CreateMaterialIcons returns a provider with every icon mapped for Material Icons (MaterialIcons-Regular.ttf, Apache License 2.0, shipped by your app):
var style = kumiko.GridStyle;
style.IconProvider = KumikoFontIconProvider.CreateMaterialIcons("MaterialIcons");
kumiko.GridStyle = style;For another font, map the icons you want; icons without a code point are drawn by Fallback, the built-in set unless you change it. Scale sets the glyph size relative to its slot, for fonts that leave a margin around each glyph:
var icons = new KumikoFontIconProvider("MyIcons") { Scale = 1.2f }
.SetGlyph(KumikoIcon.SortAscending, 0xE900)
.SetGlyph(KumikoIcon.SortDescending, 0xE901)
.SetGlyph(KumikoIcon.Filter, 0xE902)
.SetGlyph(KumikoIcon.FilterActive, 0xE903);
var style = kumiko.GridStyle;
style.IconProvider = icons;
kumiko.GridStyle = style;Your own drawing. Implement IKumikoIconProvider (one method, DrawIcon(ctx, icon, bounds, paint)), or derive from KumikoIconProvider and override DrawIcon to replace a few icons and keep the rest:
public sealed class RoundCheckIcons : KumikoIconProvider
{
// Reused every frame: DrawIcon runs for each visible glyph and should not allocate
private readonly KumikoPaint _dot = new() { IsAntiAlias = true };
public override void DrawIcon(IDrawingContext ctx, KumikoIcon icon, KumikoRect bounds, KumikoPaint paint)
{
if (icon != KumikoIcon.Check)
{
base.DrawIcon(ctx, icon, bounds, paint);
return;
}
// A filled dot instead of a tick, in the check mark's color
float size = Math.Min(bounds.Width, bounds.Height) * 0.5f;
_dot.Color = paint.Color;
ctx.FillRoundRect(new KumikoRect(bounds.X + (bounds.Width - size) / 2, bounds.Y + (bounds.Height - size) / 2, size, size),
size / 2, _dot);
}
}var style = kumiko.GridStyle;
style.IconProvider = new RoundCheckIcons();
kumiko.GridStyle = style;bounds is the slot: draw the glyph centered in it and scaled to it. paint carries the glyph's color and, for line glyphs, the line weight the slot asks for; read it, don't change or keep it. A drawn component used outside a grid (a DrawnCheckBox, DrawnComboBox, ...) has its own IconProvider property; the grid sets it from the style on the editors and popups it opens.
KumikoIcon |
Where | Built-in glyph |
|---|---|---|
GroupExpanded, GroupCollapsed |
Group header rows | Triangle down, triangle right |
SortAscending, SortDescending |
Column header, grouping chip, filter popup sort rows | Triangle up, triangle down |
Filter, FilterActive |
Column header filter button, without and with a filter | Funnel outline, solid funnel |
Remove |
Grouping chip remove button | × |
GroupSeparator |
Between grouping chips | Chevron right |
DragHandle |
Row drag handle | Six dots |
Check, Indeterminate |
Boolean cells, the filter popup's value list | Tick, dash |
DropDown, DropDownOpen |
DrawnComboBox |
Triangle down, triangle up |
Increment, Decrement |
DrawnNumericUpDown |
Plus, minus |
Calendar |
DrawnDatePicker field |
Calendar page |
CalendarPrevious, CalendarNext |
DrawnDatePicker month navigation |
Chevron left, chevron right |
SpinUp, SpinDown |
DrawnDatePicker time picker |
Chevron up, chevron down |
The All Components page of both samples switches between the built-in set and Material Icons.
The grid scrolls with touch drags (with inertia after a fling), the mouse wheel and trackpad, and the keyboard. Only the rows and columns in the viewport are drawn. ScrollSettings tunes scrolling:
kumiko.ScrollSettings = new ScrollSettings
{
Friction = 0.95f, // share of the fling speed kept every 16 ms (lower stops sooner; default 0.92)
WheelScrollMultiplier = 5f, // row heights per wheel step (default 3)
EnableInertia = true, // fling after a touch drag (default true)
};ScrollSettings member |
Default | Meaning |
|---|---|---|
Friction |
0.92 | Share of the fling speed kept every 16 ms, 0..1; lower stops sooner. Scaled by the actual frame time, so a fling behaves the same at any refresh rate |
MinVelocity |
0.5 | Speed (px/s) below which a fling stops |
MaxVelocity |
8000 | Highest fling speed (px/s) |
FlingThresholdMultiplier |
10 | A release must exceed MinVelocity times this to fling |
VelocitySmoothing |
0.3 | Smoothing of the tracked velocity, 0..1 (higher is smoother but slower to respond) |
WheelScrollMultiplier |
3 | Row heights scrolled per unit of wheel movement the platform reports |
EnableInertia |
true | Whether a release flings |
FlingHoldCutoffMs |
100 | A finger that rests this long before release does not fling |
AutoScrollEdgeSize, AutoScrollMaxSpeed |
40, 1200 | Autoscroll during a row drag (Row Drag and Drop) |
A drag that starts on a column header and moves sideways reorders the column rather than scrolling, and with AllowRowDragDrop a long press on touch (a mostly vertical drag with a mouse) on a cell moves the row. Trackpads scroll by pixels, Shift plus the wheel scrolls horizontally, and once the grid reaches its end the wheel scrolls the page instead. IsEnabled="False" stops all input.
ScrollToRow, ScrollToItem and ScrollToColumn scroll the grid from code. Each takes a KumikoScrollPosition (Nearest, the default, Start, Center or End), respects the header, summaries, frozen rows and sticky group headers, clamps to the scrollable range, and returns false when the target does not exist. ScrollToItem expands collapsed groups on the way unless you pass expandGroups: false.
kumiko.ScrollToRow(500, KumikoScrollPosition.Center);
kumiko.ScrollToItem(employees[^1], KumikoScrollPosition.End);
kumiko.ScrollToColumn(2);
kumiko.Scrolled += (_, e) =>
{
if (e.OffsetY + e.ViewportHeight >= e.ContentHeight - 200)
Console.WriteLine("Near the end: load more rows");
};VerticalOffset and HorizontalOffset are two-way properties that follow every scroll and scroll the grid when set. Scrolling before the grid has its first layout is applied once it has a size.
- Virtualized drawing. Only visible rows and columns are drawn.
- Allocation-free frames. Once the visible data has been drawn, redrawing it allocates nothing in the managed render loop: paints are rebuilt only when the style changes (
KumikoStyle.Version), each drawn cell's value and text are cached per row and column, and the built-in renderers reuse their paints. CI enforces this withRenderAllocationTests. - Native object reuse. Each grid keeps one
SkiaResourceCacheofSKPaint,SKFontandSKTypefaceobjects for its lifetime, so steady-state frames create no native Skia objects. - Incremental collection changes. Adding or removing one item of an
ObservableCollectionwhile no sort, filter or grouping is active updates the view without rebuilding it. - Live summaries. When an item changes a property that only table summaries use, Sum, Average and Count follow the change without reading the other rows, and Min, Max and Custom are recomputed without re-sorting, re-filtering or regrouping. 100 such changes on 100,000 rows take a few milliseconds in total.
- Keep custom renderers and style resolvers allocation-free. They run for every visible cell on every frame; create paints, fonts and styles once and reuse them.
- Batch changes. Wrap several sort, filter or grouping changes, or a loop of collection changes under an active sort or grouping, in
using (DataSource.BeginUpdate()) { ... }to rebuild once. - Know when a change rebuilds the view. A sort, filter or grouping change rebuilds the whole view. From 10,000 rows up the rebuild runs on a worker and the UI thread only swaps the result in (Threading); below that it runs on the UI thread, and is short. Measure on your target devices with your own data.
- Make collection and property changes on the UI thread. The grid throws for a change raised on any other thread (Threading).
- Implement
INotifyPropertyChangedso the grid re-reads only the changed cells, or callDataSource.Refresh()after changing items that don't. - Use generated accessors (
[KumikoGridItem]) or column delegates for large data; see Native AOT and Trimming.
Measured with BenchmarkDotNet (bench/KumikoUI.Benchmarks) on an Apple M4 Max, macOS 27.2, .NET 10.0.14, Release build, 2026-11-10 (sort, filter, grouping and live-update rows 2026-11-13). Frame figures are the managed render loop into a no-op drawing context, so they leave out SkiaSharp's own drawing time; the 100,000-row figures are one view rebuild, measured on the calling thread, except the live-update row. In a grid that rebuild runs on a worker (from 10,000 rows), so what the UI thread pays is the call, a copy of the item references and the swap, about 1 ms even for a sort of a million rows (BackgroundRebuildTests, bench/README.md).
| Operation | Time | Allocated |
|---|---|---|
| Render a 30 × 10 visible grid (steady state) | 2.9 µs | 0 B |
| Same, with sort, filter, grouping, summaries, a frozen column and the drag handle | 6.3 µs | 0 B |
| Render while scrolling (one new row per frame) | 3.7 µs | 501 B |
| Sort 100K rows (int / string / date column) | 24 / 57 / 173 ms | 3.4 / 1.1 / 3.4 MB |
| Filter 100K rows (text contains / numeric) | 2.2 / 1.4 ms | 1.3 KB / 2.3 MB |
| Group 100K rows by 1 / 2 levels, with summaries | 21 / 42 ms | 10.3 / 10.4 MB |
Add or remove one item of an ObservableCollection of 100K rows |
128 µs | 432 B |
100 PropertyChanged of a summed property, 100K rows with a Sum summary |
24 µs | 100 KB |
These figures don't include drawing on a device, so this README makes no frame-rate claim. To see what a device does, turn on ShowFrameStats (off by default; the Large Data page of both samples has a switch): the grid draws its render time, frames per second and bytes allocated per frame in its top-right corner. The budgets each operation is held to and how to rerun the benchmarks are in bench/README.md.
To host the engine on your own SkiaSharp surface, keep one SkiaResourceCache per control and pass it to each frame's SkiaDrawingContext:
using KumikoUI.SkiaSharp;
using SkiaSharp;
public sealed class MyGridSurface : IDisposable
{
private readonly SkiaResourceCache _resources = new(); // one per control
public void Paint(SKCanvas canvas, Action<IDrawingContext> draw)
{
using var ctx = _resources.CreateContext(canvas); // reused every frame; disposing ends the frame and keeps the cache
draw(ctx);
}
public void Dispose() => _resources.Dispose();
}The grid follows the standard .NET change notifications.
var employees = new ObservableCollection<Employee>(initialList);
kumiko.ItemsSource = employees;
employees.Add(new Employee { Name = "Alice" }); // the grid updates
employees.RemoveAt(3);Items added or removed honor the active sort, filters and grouping. Items may be of mixed runtime types (for example Dog and Cat in a List<Animal>): each column's property is resolved per item type, and an item without that property shows an empty cell. null entries never become rows.
Cell values update when the item implements INotifyPropertyChanged:
using System.ComponentModel;
public class Employee : INotifyPropertyChanged
{
private decimal _salary;
public string Name { get; set; } = "";
public decimal Salary
{
get => _salary;
set { _salary = value; PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(nameof(Salary))); }
}
public event PropertyChangedEventHandler? PropertyChanged;
}A change to a property that a sort, column filter or grouping uses re-sorts, re-filters or regroups; a change to a property that only table summaries use updates the summaries in place (Sum, Average and Count in constant time); any other change only repaints that cell. With a SetFilter predicate set, every change re-filters, since the predicate may read any property. A null or empty property name means every property changed. Items that don't implement INotifyPropertyChanged show changes made outside the grid after DataSource.Refresh(); values written through the grid always show.
PropertyName accepts dotted paths:
<core:KumikoColumn Header="City" PropertyName="Address.City" Width="120" />Only the row item is observed: for a sorted, filtered, grouped or summarized Address.City to update when the address changes, the item must raise PropertyChanged for Address (or with an empty name). A null value part-way along the path reads as an empty cell, and an edit to it is ignored.
The grid's data source belongs to the UI thread: the thread that assigned ItemsSource (more precisely, that last called DataSource.SetItems or Attach). Add, remove and replace items, raise PropertyChanged and call DataSource methods on that thread. A change raised on any other thread, such as employees.Add(...) inside Task.Run, throws an InvalidOperationException to the code that made it, before the grid reads anything; the grid then re-reads the collection on the UI thread so it shows what the collection holds. Code that runs under the UI thread's SynchronizationContext (an await continuation that resumes there) counts as the UI thread.
Do the slow work in the background and post only the change to the UI thread, with MainThread.BeginInvokeOnMainThread (MAUI), DispatcherQueue.TryEnqueue (Uno), or the UI thread's SynchronizationContext:
var ui = SynchronizationContext.Current!; // captured on the UI thread
_ = Task.Run(() =>
{
var hire = new Employee { Name = "Dana" }; // background work
ui.Post(_ => employees.Add(hire), null); // the change itself, on the UI thread
});For many changes at once, post one callback that makes them inside using (kumiko.DataSource.BeginUpdate()) { ... }, or build a new collection in the background and assign it to ItemsSource on the UI thread.
Large sources rebuild in the background. From DataSource.BackgroundRebuildThreshold items up (10,000 in the MAUI and Uno grids; a KumikoSource you create stays synchronous), sorting, filtering, grouping and summaries run on a worker. Requests made in one UI turn start one rebuild, and a newer one cancels a running one. The grid keeps drawing the current rows until the new view is swapped in on the UI thread (ViewChanged, then ViewUpdated); selection, the current cell and an open edit follow their items. DataSource.IsViewUpdatePending tells whether a rebuild is under way, and await DataSource.WhenViewUpdatedAsync() waits for the new order. While a rebuild runs, the worker reads item properties and calls your comparers, filter predicate, group selectors and custom aggregates, so these must only read.
All KumikoUI packages are marked IsAotCompatible and build with no trimming or Native AOT analyzer warnings. The grid reads and writes the item properties named by PropertyName through, in order:
- Column delegates:
ValueAccessorandValueSetteronKumikoColumn(andEditorDisplaySelector/EditorValueSelectorfor ComboBox items). - Generated accessors for types marked
[KumikoGridItem](KumikoUI.Core.Data). TheKumikoUI.Corepackage includes the source generator, which registers the accessors when the assembly loads. - Registered providers:
KumikoAccessorRegistry.Register(type, provider)orAddProvider(provider)with your ownIKumikoAccessorProvider, for example to read dictionary entries. - Reflection, for everything else. It is turned off automatically for
PublishAot=trueandTrimMode=full, because those publishes remove the metadata it reads; partial trimming (the .NET MAUI default) keeps it on. Set theKumikoReflectionPropertyAccessMSBuild property totrueorfalseto override.
With reflection off, a property that no tier can serve reads as null, edits to it are ignored, and a warning naming the type and property is traced once.
using KumikoUI.Core.Data;
using KumikoUI.Core.Models;
[KumikoGridItem] // generated accessors for Name, Age and Address
public class Customer
{
public string Name { get; set; } = "";
public int Age { get; set; }
public Address? Address { get; set; }
}
[KumikoGridItem] // mark every type a path walks through ("Address.City")
public class Address
{
public string City { get; set; } = "";
}
public static class CustomerColumns
{
// Or per column, without attributes
public static KumikoColumn Bonus() => new()
{
Header = "Bonus",
PropertyName = "Bonus", // still names the column for summaries and grouping
ValueAccessor = item => ((Customer)item).Age * 10m,
};
}CI publishes a Native AOT console smoke app (Linux, Windows and macOS) and the MAUI sample with Native AOT (iOS and Mac Catalyst), and the Uno WebAssembly sample trimmed. The sample row types use [KumikoGridItem] accessors.
The generator reports KUMIKO001 for generic types and KUMIKO002 for types it can't reference (private, protected or file-local); use delegates or a provider for those. Generated and delegate reads are measured in bench/KumikoUI.Benchmarks (PropertyAccessBenchmarks).
This is the current state, not the goal. The 1.0 target and the plan are in docs/ROADMAP.md (track L).
- Screen readers see one element. Cells, headers, editors and popups are drawn on a canvas and are not exposed to assistive technology individually, so a screen reader can't read or navigate cell contents. A per-cell accessibility tree is planned for 1.x.
- MAUI: the grid is in the accessibility tree with
GridDescription(default: the localizableKumikoStrings.AccessibleGridName, "Data grid") as its semantic description andGridHint(default: a hint with the row and column counts and the current cell) as its hint. - Uno: the grid has a UI Automation peer with the DataGrid control type. Its name comes from
GridDescriptionorKumikoStrings.AccessibleGridName, and its help text fromGridHintor a computed description of the rows and columns. The peer shows up in the accessibility trees of WebAssembly (as arole="grid"element) and Android; on the macOS desktop head VoiceOver cannot reach the grid yet (docs/uno/verification.md). The device verification passes inspected these accessibility trees but did not drive a screen reader on either host, so test with VoiceOver, TalkBack or Narrator before relying on it. - Announcements. With
AnnounceChangeson (the default), both hosts announce the current cell, sort changes, edit start and end, and validation errors to a running screen reader. Column numbers count visible columns in on-screen order. The texts areKumikoStringsproperties, so they localize with the rest of the grid.
- MAUI: the grid is in the accessibility tree with
- Keyboard. The grid can be used without a pointer on Uno and on MAUI for every platform, and never traps Tab. See Keys per platform.
- Hidden input fields. Most hosts keep an invisible native view to receive keyboard input: on MAUI, a
KeyInputResponderon Apple platforms and an input view on Android (on Windows the grid itself takes the keyboard focus); on Uno, aTextBox. It is kept out of the accessibility tree and takes no pointer input. - Right-to-left layout is not supported in 1.0. Under a right-to-left ancestor (
FlowDirection) the grid still draws left to right instead of mirroring; mirrored layout is tracked in #80. - Contrast and text size.
KumikoThemeMode.HighContrastis a high-contrast preset; the grid doesn't switch to it when the operating system's high-contrast mode is on. Font sizes come fromKumikoStyleand don't follow the operating system's text-size setting.
How do I put a button in each row that runs a view model command?
Use an action button column (Action Button Columns). On MAUI, MauiActionButtonDefinition binds Command in XAML; on Uno, UnoActionButtonDefinition does the same (the grid supplies its DataContext). A tap runs the command without opening an editor, whatever the grid's EditTriggers (#2, #6).
Japanese text or icon glyphs show up as boxes or the wrong characters on Android.
The grid draws text with SkiaSharp, which doesn't see fonts registered with MAUI or WinUI, and Android's font manager doesn't give it CJK or icon typefaces. Register the font with SkiaFontRegistrar (MAUI) or KumikoFonts (Uno) and use its family name in KumikoFont (Custom Fonts, #5).
Can one column edit on a single tap while the others need a double-tap?
Yes: set EditTriggers on that column; it overrides the grid's (Per-column edit triggers, #6).
I unchecked values in the filter popup and closed it, but nothing was filtered. The popup applies its checklist on OK. Cancel and a tap outside the popup discard the changes; Clear removes the column's filter.
How do I make the whole grid read-only, or turn off sorting or filtering?
Set IsReadOnly, AllowSorting or AllowFiltering to False on the grid. They combine with the KumikoColumn properties of the same names, and a grid-level False wins.
The soft keyboard covers the cell I'm editing on Android.
The grid places its input view over the edited cell. If the keyboard still covers the cell, the grid scrolls it above the keyboard. A cell in the last rows can only move as far as the grid can scroll, so let the window make room: set WindowSoftInputMode to adjustResize or adjustPan (docs/TEXT-INPUT.md).
My Uno app fails to load SkiaSharp, or draws nothing.
Set <SkiaSharpVersion>4.153.1</SkiaSharpVersion> in the app project and enable the SkiaRenderer Uno feature: Uno.Sdk defaults to SkiaSharp 3.x, and the app must resolve the same major as KumikoUI. On the Windows App SDK head, also reference SkiaSharp.Views.WinUI (Uno Platform).
My iOS or Mac Catalyst app terminates at launch. Adopt the UIScene lifecycle; see the note under .NET MAUI.
My column headers are cut off.
Headers fit their column unless the column has an explicit Width (or a MaxWidth that is smaller). Remove the Width, or make it wider (Column sizing).
Edits I make to items in code don't show.
Implement INotifyPropertyChanged on the items, or call DataSource.Refresh() after changing them (Live Data).
Can I bind Theme or GridStyle? Does the grid follow dark mode?
Yes: Theme, GridStyle and ScrollSettings are bindable, including Theme="{AppThemeBinding Light=Light, Dark=Dark}" on MAUI. Until you set a theme or style, FollowSystemTheme makes the grid follow the system light/dark setting (Built-in themes, Precedence).
Does the grid support right-to-left languages?
Text in Arabic or Hebrew is drawn, but the grid layout is not mirrored: it draws left to right under a right-to-left FlowDirection. Full right-to-left layout is not part of 1.0 (#80).
How do I keep the column order, widths and sort between sessions?
Save GetLayoutState().ToJson() and restore it with ApplyLayoutState(KumikoLayoutState.FromJson(json)) (Saving and restoring the layout). A user's column drag also moves the column in the grid's Columns collection.
Where are the scrollbars?
The grid doesn't draw scrollbars yet. It scrolls by touch, mouse wheel, trackpad and keyboard, and from code with the ScrollTo methods and VerticalOffset.
Can I update the collection from a background thread?
No. Make collection and item changes on the UI thread: a change raised on another thread throws InvalidOperationException. Do the work in the background and post the change to the UI thread (Threading).
KumikoUI.Core (net10.0): data, layout, rendering, input, editing; no UI framework or SkiaSharp dependency
↑
KumikoUI.SkiaSharp (net10.0): IDrawingContext on an SKCanvas, resource cache, font registry
↑ ↑
KumikoUI.Maui (.NET MAUI) KumikoUI.Uno (Uno Platform / WinUI)
KumikoDataGrid on an SKGLView KumikoDataGrid on an SKCanvasElement
(or an SKCanvasView, see RenderMode) (or an SKXamlCanvas, see RenderMode)
All drawing goes through the IDrawingContext abstraction, so Core has no dependency on MAUI, WinUI or SkiaSharp. The two host controls are thin: they forward pointer, wheel and keyboard input to KumikoInputController, step inertial scrolling from the platform's frame callback, redraw at caret blink transitions, and paint by calling KumikoRenderer.Render.
| Class | Responsibility |
|---|---|
KumikoRenderer |
Draws a frame: rows, grid lines, headers, frozen panes, summaries, group overlays, drag overlays, the editor and popups |
KumikoSource |
Data: sorting, filtering, grouping, summaries, culture and strings, change notifications |
KumikoLayoutEngine |
Column widths (Fixed, Star, Auto, header fit) and visible ranges |
KumikoHitTester |
Maps a point to a HitRegion (cell, header, resize grip, filter icon, group chevron, chip, summary row, ...) |
KumikoInputController |
Routes pointer and keyboard input to selection, editing, sorting, resizing, reordering and drag |
KumikoSelectionModel |
Item-based selection and the current cell |
EditSession |
Edit lifecycle: begin, convert, validate, commit, cancel |
CellEditorFactory |
Creates the drawn editor for a column type |
PaintCache |
The paints the grid draws with, rebuilt only when the style changes |
InertialScroller |
Fling deceleration (ScrollSettings) |
PopupManager (internal) |
Popup z-order and input priority (filter popup, combo box, date picker) |
SkiaDrawingContext, SkiaResourceCache |
The SkiaSharp drawing context and its per-control cache |
KumikoDataGrid (MAUI, Uno) |
The host controls |
See docs/ARCHITECTURE.md and docs/RENDERING.md for contributor detail, and the Uno user guide for the Uno host.
Every interaction timing and threshold (double tap, long press, drag and pan thresholds, touch target sizes, momentum presets, transition durations) is listed in docs/INTERACTION.md.
Both samples have the same pages (samples/README.md has the run commands and a map from each feature to its page):
| Page | What it shows |
|---|---|
| All Components | Every column type, frozen columns and rows, edit triggers, selection modes, summaries, adding and removing rows, theme switching, built-in or Material Icons glyphs |
| Grouping | Nested groups, the grouping panel, filter popups, group summaries |
| Large Data | 100,000 rows, load timings and the frame-time overlay switch |
| Theming | Light, Dark and HighContrast, and custom colors |
| MVVM Actions | Action button columns bound to view model commands, per-column EditTriggers, MVVM selection |
| Custom Fonts | Japanese headers with Noto Sans JP, and icon columns with Material Icons |
| Images | Image columns from app assets, ImageSources or BitmapImages and web URLs over 10,000 rows, with the bounded ImageCache |
| Styling | An image column, switching the icon set (KumikoStyle.IconProvider), per-cell and per-row styles (CellStyleResolver, RowStyleResolver) and AlternateRowBackground |
| Events | CellTapped, HeaderTapped, ContextMenuRequested and the other events in a log, the selection modes, a CellValidator, and saving and restoring the layout |
samples/SampleApp.Maui: .NET MAUI (iOS, Mac Catalyst, Android, Windows).samples/SampleApp.Uno: Uno Platform (desktop, WebAssembly, iOS, Android, Windows App SDK).
All Components |
Grouping |
Dark theme |
Large Data |
Contributions are welcome. Please open an issue before a large pull request so we can discuss the approach.
- Fork the repository and create your branch from
main. - Install the pinned toolchain and build as described in CONTRIBUTING.md.
- Run the tests:
dotnet test tests/KumikoUI.Core.Tests(andtests/KumikoUI.Uno.Testsfor Uno changes). - Submit a pull request with a clear description of the change.
MIT; see LICENSE.



