Data Grid

Use CDataGrid for application data that benefits from one composite Tab stop, cell navigation, row selection, accepted complete-collection sorting, or fixed-height server windowing. Use CTable instead for document-like tables, ordinary links and controls in cells, spans, footers, and print-first reading.

Build a complete grid

Columns and rows are immutable Python records. Every Row supplies exactly one Cell value for every Column key, and every key is a stable nonempty string.

Navigate a complete Data Grid

Show code

import citry_ui
from citry import Component, citry
from citry_ui import CDataGridColumn, CDataGridRow

citry.register_library(citry_ui)


class DataGridAtAGlance(Component):
    template = """
      <c-CDataGrid c-columns="columns" c-rows="rows" label="Project members" striped>
        <c-fill name="caption">Current project members</c-fill>
      </c-CDataGrid>
    """

    def template_data(self, _kwargs: object, _slots: object) -> dict[str, object]:
        return {
            "columns": (
                CDataGridColumn("name", "Name", width=190),
                CDataGridColumn("role", "Role", width=180),
                CDataGridColumn("status", "Status", width=130),
            ),
            "rows": (
                CDataGridRow("ada", {"name": "Ada Lovelace", "role": "Engineer", "status": "Active"}),
                CDataGridRow("grace", {"name": "Grace Hopper", "role": "Admiral", "status": "Active"}),
                CDataGridRow("katherine", {"name": "Katherine Johnson", "role": "Mathematician", "status": "Away"}),
            ),
        }


preview = DataGridAtAGlance()
preview  # noqa: B018

The server output is a native table with exact row and column positions. Once enhanced, one Header or Cell is in the page Tab order. Arrow keys move between rendered Cells; Home, End, Page Up, Page Down, Ctrl/Cmd+Home, and Ctrl/Cmd+End provide larger movement.

Request sorting and select rows

Set sortable=True on Columns that can be sorted. Header activation cycles ascending, descending, then unsorted. onSortChange receives the requested model, and accepted sort state must come back from the owner. When that accepted request belongs to a complete supplied collection, the grid visibly reorders Rows by rendered Cell text. It uses locale-aware numeric comparison, applies sort entries in priority order, and restores server order when sorting is cleared. Shift preserves other Columns when multi_sort=True.

Sort and select people

Show code

import citry_ui
from citry import Component, citry
from citry_ui import CDataGridColumn, CDataGridRow, CDataGridSort

citry.register_library(citry_ui)


class DataGridSortingSelection(Component):
    template = """
      <section x-data="{sort:[{key:'name',direction:'asc'}],notice:'Activate a sortable header or select a row'}">
        <output x-text="notice">Activate a sortable header or select a row</output>
        <c-CDataGrid
          c-columns="columns"
          c-rows="rows"
          c-sort="sort"
          label="Sortable people"
          selection="multiple"
          c-selected="['grace']"
          $c-props="{
            sort,
            onSortChange:(next)=>{
              sort=next;
              notice=next.length
                ? `Sorted: ${next.map((item,index)=>`${index + 1}. ${item.key} ${item.direction}`).join(', ')}`
                : 'Server row order restored';
            },
            onSelectionChange:(selected)=>notice=`Selected: ${selected.join(', ') || 'none'}`,
          }"
        />
      </section>
    """

    def template_data(self, _kwargs: object, _slots: object) -> dict[str, object]:
        return {
            "columns": (
                CDataGridColumn("name", "Name", sortable=True, width=190),
                CDataGridColumn("team", "Team", sortable=True, width=150),
                CDataGridColumn("score", "Score", sortable=True, width=100, align="end"),
            ),
            "rows": (
                CDataGridRow("ada", {"name": "Ada Lovelace", "team": "Platform", "score": 98}),
                CDataGridRow("grace", {"name": "Grace Hopper", "team": "Compiler", "score": 95}),
                CDataGridRow("lin", {"name": "Lin Clark", "team": "Runtime", "score": 91}),
            ),
            "sort": (CDataGridSort("name", "asc"),),
        }


preview = DataGridSortingSelection()
preview  # noqa: B018

selection="single" or selection="multiple" enables Row selection. Uncontrolled selection commits immediately. A non-null client selected array makes selection controlled, so the visible state waits for acceptance. In multiple mode, drag a mouse pointer across loaded Rows to select a range; starting on a selected Row removes the dragged range. Disabled Rows are skipped. Shift+Space toggles the focused Row in either direction. Touch remains ordinary scrolling rather than starting a drag selection.

Control models from Alpine

Pass sort, selected, and callbacks through $c-props. Invalid client models are diagnosed and the last valid state remains active.

Control Data Grid models

Show code

import citry_ui
from citry import Component, citry
from citry_ui import CDataGridColumn, CDataGridRow

citry.register_library(citry_ui)


class ControlledDataGrid(Component):
    template = """
      <section x-data="{sort:[],selected:['ada']}">
        <button type="button" @click="selected=[]">Clear selection</button>
        <c-CDataGrid
          c-columns="columns"
          c-rows="rows"
          label="Controlled members"
          selection="multiple"
          $c-props="{
            sort,
            selected,
            onSortChange:(next)=>sort=next,
            onSelectionChange:(next)=>selected=next,
          }"
        />
      </section>
    """

    def template_data(self, _kwargs: object, _slots: object) -> dict[str, object]:
        return {
            "columns": (
                CDataGridColumn("name", "Name", sortable=True, width=190),
                CDataGridColumn("role", "Role", sortable=True, width=170),
            ),
            "rows": (
                CDataGridRow("ada", {"name": "Ada Lovelace", "role": "Engineer"}),
                CDataGridRow("grace", {"name": "Grace Hopper", "role": "Admiral"}),
            ),
        }


preview = ControlledDataGrid()
preview  # noqa: B018

Sort remains request/accept so an application can reject it or wait for a server response. Initial and programmatic models describe the server-authored order; local reordering occurs when the browser accepts a Header request for a complete collection. A server window cannot sort Rows it does not have, so its owner must return the newly ordered range. Selection becomes uncontrolled again when client selected is omitted or null. Accepted changes are announced politely.

Supply a server window

Set total_count and start_index when rows is one contiguous window of a larger collection. row_height is fixed geometry. onRangeChange receives a half-open desired range when scrolling, resizing, or navigation leaves the supplied range.

Request Data Grid windows

Show code

import citry_ui
from citry import Component, citry
from citry_ui import CDataGridColumn, CDataGridRow

citry.register_library(citry_ui)


class WindowedDataGrid(Component):
    template = """
      <section x-data="{notice:'This static preview supplies one complete window'}">
        <output x-text="notice">This static preview supplies one complete window</output>
        <c-CDataGrid
          c-columns="columns"
          c-rows="rows"
          label="Audit records"
          c-total_count="16"
          c-row_height="44"
          $c-props="{onRangeChange:(detail)=>notice=`Requested ${detail.startIndex}-${detail.endIndex - 1}`}"
        />
      </section>
    """

    def template_data(self, _kwargs: object, _slots: object) -> dict[str, object]:
        return {
            "columns": (
                CDataGridColumn("number", "Record", width=120),
                CDataGridColumn("action", "Action", width=230),
                CDataGridColumn("actor", "Actor", width=160),
            ),
            "rows": tuple(
                CDataGridRow(
                    f"audit-{index}",
                    {"number": f"#{index + 1:05d}", "action": "Signed deployment record", "actor": "Release bot"},
                )
                for index in range(16)
            ),
        }


preview = WindowedDataGrid()
preview  # noqa: B018

The component does not fetch. The owner handles supersession, retries, offline state, and replacement. Keep Row keys stable across windows. This first version does not select unloaded rows or expose a remote select-all operation.

Edit cells in place

Set editable=True on a CDataGridColumn, then choose its editor from text, number, checkbox, or select. Select editors require named CDataGridEditOption records. editor_attrs accepts only the documented attributes for that native control, such as min, max, step, maxlength, and placeholder.

Edit project assignments

Show code

# ruff: noqa: ANN001, ANN201 - public snippets keep focus on component use

import citry_ui
from citry import Component, citry
from citry_ui import CDataGridColumn, CDataGridEditOption, CDataGridRow

citry.register_library(citry_ui)


class EditableDataGrid(Component):
    def template_data(self, _kwargs, _slots):
        return {
            "columns": (
                CDataGridColumn("name", "Name", editable=True, editor_attrs={"maxlength": 80}),
                CDataGridColumn(
                    "role",
                    "Role",
                    editable=True,
                    editor="select",
                    editor_options=(
                        CDataGridEditOption("engineer", "Engineer"),
                        CDataGridEditOption("designer", "Designer"),
                        CDataGridEditOption("lead", "Lead"),
                    ),
                ),
                CDataGridColumn(
                    "allocation",
                    "Allocation",
                    editable=True,
                    editor="number",
                    editor_attrs={"min": 0, "max": 100, "step": 5},
                ),
                CDataGridColumn("active", "Active", editable=True, editor="checkbox"),
            ),
            "rows": (
                CDataGridRow("ada", {"name": "Ada", "role": "engineer", "allocation": 80, "active": True}),
                CDataGridRow("mira", {"name": "Mira", "role": "designer", "allocation": 60, "active": True}),
            ),
        }

    template = """
      <section x-data="{last:'Double-click or press Enter to edit'}">
        <c-CDataGrid
          c-columns="columns"
          c-rows="rows"
          label="Project assignments"
          $c-props="{onCellEditCommit:(value,detail)=>last=`${detail.rowKey}.${detail.columnKey}: ${value}`}"
        />
        <output x-text="last">Double-click or press Enter to edit</output>
      </section>
    """


preview = EditableDataGrid()
preview  # noqa: B018

Enter, F2, typing, Backspace, Delete, or double-click enters edit mode where appropriate. Enter commits, Escape cancels, and Tab commits before moving to the adjacent Cell. onCellEditCommit receives the typed value and stable Row and Column details. Returning False rejects the value and keeps the editor open. The component does not mutate server Rows: update the owner and render the accepted value back into rows.

The static documentation preview uses a small self-contained range with no omitted leading or trailing Rows. It therefore never exposes scrollable blank space that the static page cannot replace. In an application, a partial range keeps its spacers only until the owner replaces it after onRangeChange.

Loading, empty, and error states

state="loading" and state="error" replace ready Rows with one spanning state output. Ready with total_count=0 becomes empty. Fill the corresponding Slot for richer server content, or override the plain localized label.

Render Data Grid states

Show code

import citry_ui
from citry import Component, citry
from citry_ui import CDataGridColumn, CDataGridRow

citry.register_library(citry_ui)


class DataGridStates(Component):
    template = """
      <div class="grid-states">
        <c-CDataGrid c-columns="columns" c-rows="[]" label="Empty records" />
        <c-CDataGrid c-columns="columns" c-rows="rows" label="Loading records" state="loading" />
        <c-CDataGrid c-columns="columns" c-rows="rows" label="Failed records" state="error">
          <c-fill name="error"><strong>Records are unavailable.</strong> Try again from the toolbar.</c-fill>
        </c-CDataGrid>
      </div>
    """
    css = ":where(.grid-states){display:grid;gap:1rem}"

    def template_data(self, _kwargs: object, _slots: object) -> dict[str, object]:
        return {
            "columns": (CDataGridColumn("name", "Name"), CDataGridColumn("status", "Status")),
            "rows": (CDataGridRow("placeholder", {"name": "Placeholder", "status": "Pending"}),),
        }


preview = DataGridStates()
preview  # noqa: B018

Accessibility and Cell content

The family follows the ARIA data-grid interaction model. Header and Cell Slot content cannot contain caller-authored links, buttons, inputs, editable content, or another Tab stop; focus remains on the Header or Cell. Built-in editors temporarily move focus into one owned native control. Use onCellActivate for Enter and double-click activation on noneditable Cells.

Use exact positions and disabled Rows

Show code

import citry_ui
from citry import Component, citry
from citry_ui import CDataGridColumn, CDataGridRow

citry.register_library(citry_ui)


class AccessibleDataGrid(Component):
    template = """
      <c-CDataGrid
        c-columns="columns"
        c-rows="rows"
        label="Deployment approvals"
        selection="multiple"
      >
        <c-fill name="caption">Use Arrow keys to move and Shift+Space to select an enabled Row.</c-fill>
      </c-CDataGrid>
    """

    def template_data(self, _kwargs: object, _slots: object) -> dict[str, object]:
        return {
            "columns": (
                CDataGridColumn("change", "Change", width=240),
                CDataGridColumn("owner", "Owner", width=160),
                CDataGridColumn("status", "Approval status", width=160),
            ),
            "rows": (
                CDataGridRow("api", {"change": "API release", "owner": "Ada", "status": "Approved"}),
                CDataGridRow(
                    "locked",
                    {"change": "Security policy", "owner": "Grace", "status": "Locked"},
                    disabled=True,
                ),
                CDataGridRow("docs", {"change": "Guide update", "owner": "Lin", "status": "Review"}),
            ),
        }


preview = AccessibleDataGrid()
preview  # noqa: B018

Column labels and Cell values belong to the application and should already be localized. State labels and browser announcements use the Citry UI catalog by default. Explicit label overrides remain caller-owned and do not switch with the client locale.

Styling and scope boundaries

Use density, striped, column_borders, and sticky_header for common presentation. Customize the root and native table separately with attrs and table_attrs, or use the documented public variables and part selectors.

Customize a Data Grid

Show code

import citry_ui
from citry import Component, citry
from citry_ui import CDataGridColumn, CDataGridRow

citry.register_library(citry_ui)


class CustomizedDataGrid(Component):
    template = """
      <div class="custom-grid">
        <c-CDataGrid
          c-columns="columns"
          c-rows="rows"
          label="Compact metrics"
          density="compact"
          striped
          column_borders
          c-style="{
            '--cui-data-grid-radius':'1rem',
            '--cui-data-grid-selected-background':'color-mix(in srgb, #7c3aed 20%, Canvas)',
          }"
        />
      </div>
    """
    css = """
      :where(.custom-grid [data-citry-ui-part="header-cell"]) { text-transform:uppercase;letter-spacing:.04em; }
      :where(.custom-grid [data-column-key="value"]) { font-variant-numeric:tabular-nums; }
    """

    def template_data(self, _kwargs: object, _slots: object) -> dict[str, object]:
        return {
            "columns": (
                CDataGridColumn("metric", "Metric", width=220),
                CDataGridColumn("value", "Value", width=120, align="end"),
            ),
            "rows": (
                CDataGridRow("latency", {"metric": "P95 latency", "value": "128 ms"}),
                CDataGridRow("errors", {"metric": "Error rate", "value": "0.04%"}),
                CDataGridRow("uptime", {"metric": "Uptime", "value": "99.99%"}),
            ),
        }


preview = CustomizedDataGrid()
preview  # noqa: B018

Arbitrary caller-authored Cell widgets, built-in filtering, grouping, aggregation, pivoting, tree Rows, pinning, reordering, resizing, clipboard mutation, export, and browser-owned data sources are outside this first family. Compose application controls around the grid instead.

API reference

Inputs

CDataGrid server inputs

Server inputs are passed in a template through <c-CDataGrid ... /> or in Python through CDataGrid(...).

Input	Type	Default	Effect
`columns`	`Sequence[CDataGridColumn]`	required	Defines the nonempty ordered structural Column schema.
`rows`	`Sequence[CDataGridRow]`	required	Supplies a complete collection or one contiguous server window.
`label`	`str`	required	Supplies the required accessible grid name.
`id`	`str \| None`	generated	Sets root identity and bases stable Header Row and Cell IDs.
`state`	`CDataGridState` (`CDataGridState`)	`"ready"`	Selects ready loading or error output; zero ready Rows become empty.
`sort`	`Sequence[CDataGridSort]`	`"()"`	Supplies the initial server-authored ordered sort model.
`multi_sort`	`bool`	`True`	Allows Shift-modified sort requests to preserve other Columns.
`selection`	`CDataGridSelection` (`CDataGridSelection`)	`"none"`	Selects no single or multiple supplied-Row selection.
`selected`	`Sequence[str]`	`"()"`	Supplies unique initially selected Row keys.
`disabled`	`bool`	`False`	Blocks sorting selection activation editing and navigation.
`total_count`	`int \| None`	`None`	Sets logical Row count; omission means the complete supplied collection.
`start_index`	`int`	`0`	Sets the zero-based logical index of the first supplied Row.
`row_height`	`int`	`48`	Sets the fixed Row stride in CSS pixels.
`viewport_size`	`int`	`400`	Sets initial scroll-viewport block size in CSS pixels.
`overscan`	`int`	`3`	Adds 0 through 100 Rows around each desired range.
`initial_index`	`int`	`0`	Performs one initial scroll to a clamped logical Row.
`density`	`CDataGridDensity` (`CDataGridDensity`)	`"comfortable"`	Selects compact comfortable or spacious Row presentation.
`striped`	`bool`	`False`	Adds alternate supplied-Row surfaces.
`column_borders`	`bool`	`False`	Shows boundaries between Columns.
`sticky_header`	`bool`	`True`	Keeps Headers at the viewport block start.
`loading_label`	`str`	`"Loading data..."`	Overrides the localized loading state.
`empty_label`	`str`	`"No data."`	Overrides the localized empty state.
`error_label`	`str`	`"Unable to load data."`	Overrides the localized error state.
`sort_ascending_label`	`str`	`"{column} sorted ascending"`	Overrides ascending-sort announcements and must retain column.
`sort_descending_label`	`str`	`"{column} sorted descending"`	Overrides descending-sort announcements and must retain column.
`sort_cleared_label`	`str`	`"Sort cleared for {column}"`	Overrides cleared-sort announcements and must retain column.
`selected_one_label`	`str`	`"One row selected"`	Overrides the one-Row selection announcement.
`selected_label`	`str`	`"{count} rows selected"`	Overrides multi-Row selection announcements and must retain count.
`edit_label`	`str`	`"Edit {column}"`	Overrides owned editor names and must retain column.
`editing_label`	`str`	`"Editing {column}"`	Overrides edit-start announcements and must retain column.
`edit_submitted_label`	`str`	`"Changes submitted for {column}"`	Overrides edit-commit announcements and must retain column.
`edit_cancelled_label`	`str`	`"Changes cancelled for {column}"`	Overrides edit-cancel announcements and must retain column.
`edit_invalid_label`	`str`	`"Enter a valid value for {column}"`	Overrides rejected or invalid edit announcements and must retain column.
`class_`	`CClassValue \| None` (`CClassValue`)	`None`	Adds root classes.
`style`	`CStyleValue \| None` (`CStyleValue`)	`None`	Adds root styles merged with owned geometry variables.
`attrs`	`Mapping[str, object] \| None`	`None`	Adds copied allowed root attributes without replacing state or runtime ownership.
`table_attrs`	`Mapping[str, object] \| None`	`None`	Adds copied allowed native table attributes without replacing Grid semantics or positions.

CDataGrid client inputs

Client inputs are passed in the browser through the $c-props="{ ... }" attribute on <c-CDataGrid />.

Input	Type	Omitted behavior	Effect
`sort`	`Array<{key: string, direction: "asc" \| "desc"}> \| null`	Uses the server sort model.	Accepts sort indicators and reorders a complete collection after a matching Header request.
`selected`	`string[] \| null`	Omission or null releases control to committed selection.	Controls unique supplied-Row selection while supplied.
`disabled`	`boolean`	Uses the server value.	Reactively disables owned interaction.
`overscan`	`number`	Uses the server value.	Reactively changes desired range buffering.
`onSortChange`	`function`	Sort activation emits no callback.	Receives request-only sort changes.
`onSelectionChange`	`function`	Selection still commits when uncontrolled.	Receives selection requests or commits.
`onRangeChange`	`function`	Uncovered ranges only reflect pending state.	Receives animation-frame-coalesced desired ranges.
`onCellActivate`	`function`	Enter and double-click have no activation callback.	Receives enabled Cell activation.
`onCellEditStart`	`function`	No edit-start callback runs.	Receives entry into an owned native editor.
`onCellEditCommit`	`function`	Valid edits close without a data-change request.	Receives changed typed values; returning false rejects synchronously.
`onCellEditCancel`	`function`	No edit-cancel callback runs.	Receives Escape and reactive disabling cancellations.

Slots

Slots are passed as nested content or <c-fill> tags in a template, or through the slots={...} argument in Python.

CDataGrid slots

Slot	Required	Data	Fallback
`caption`	no	`{}` (`CDataGridCaptionSlotData`)	Omitted.
`toolbar`	no	`{}` (`CDataGridToolbarSlotData`)	Omitted before the viewport.
`header`	no	`{column, column_index, sort_direction, sort_priority}` (`CDataGridHeaderSlotData`)	Escaped Column label plus owned sort indicator.
`cell`	no	`{row, column, cell, row_index, column_index, selected}` (`CDataGridCellSlotData`)	Escaped or component-like Cell value.
`loading`	no	`{}` (`CDataGridLoadingSlotData`)	Localized loading label.
`empty`	no	`{}` (`CDataGridEmptySlotData`)	Localized empty label.
`error`	no	`{}` (`CDataGridErrorSlotData`)	Localized error label.

Events

Component events are callback inputs supplied through $c-props. Native browser events remain available through Alpine @... attributes.

CDataGrid events

Event	Signature	Trigger and timing	Detail	Controlled and cancellation behavior
`onSortChange`	`(sort: sort[], detail: CDataGridSortChangeDetail) => void` (`CDataGridSortChangeDetail`)	Click or Enter activates an enabled sortable Header.	`{sort, previousSort, columnKey, direction, source, sourceEvent}` (`CDataGridSortChangeDetail`)	Request-only until accepted; a matching accepted request reorders complete supplied Rows by rendered text while a partial window waits for server replacement.
`onSelectionChange`	`(selected: string[], detail: CDataGridSelectionChangeDetail) => void` (`CDataGridSelectionChangeDetail`)	Click Shift+click Shift+Space or mouse drag requests a supplied-Row selection change.	`{selected, previousSelected, changed, rowKey, selectedRow, controlled, source, sourceEvent}` (`CDataGridSelectionChangeDetail`)	Uncontrolled state commits first; controlled state waits for acceptance; disabled Rows are skipped.
`onRangeChange`	`(detail: CDataGridRangeChangeDetail) => void` (`CDataGridRangeChangeDetail`)	Scroll resize configuration or navigation exposes an uncovered desired range.	`{startIndex, endIndex, visibleStartIndex, visibleEndIndex, requestId, reason, sourceEvent}` (`CDataGridRangeChangeDetail`)	Coalesced per animation frame with a monotonic request ID.
`onCellActivate`	`(detail: CDataGridCellActivateDetail) => void` (`CDataGridCellActivateDetail`)	Enter or double-click activates an enabled noneditable body Cell.	`{rowKey, columnKey, rowIndex, columnIndex, source, sourceEvent}` (`CDataGridCellActivateDetail`)	Does not mutate data.
`onCellEditStart`	`(detail: CDataGridCellEditDetail) => void` (`CDataGridCellEditDetail`)	Enter F2 typing Backspace Delete or double-click enters an editable Cell.	`{rowKey, columnKey, rowIndex, columnIndex, editor, previousValue, source, reason, sourceEvent}` (`CDataGridCellEditDetail`)	The owned native editor receives focus and grid navigation pauses.
`onCellEditCommit`	`(value: string \| number \| boolean, detail: CDataGridCellEditDetail) => boolean \| void` (`CDataGridCellEditDetail`)	Enter F2 Tab outside pointer or a replacement editor submits a valid changed value.	`{rowKey, columnKey, rowIndex, columnIndex, editor, previousValue, source, reason, sourceEvent}` (`CDataGridCellEditDetail`)	Returning false or throwing keeps the editor open and invalid; otherwise the editor closes while server Rows remain authoritative.
`onCellEditCancel`	`(detail: CDataGridCellEditDetail) => void` (`CDataGridCellEditDetail`)	Escape or reactive disabling cancels an active edit.	`{rowKey, columnKey, rowIndex, columnIndex, editor, previousValue, source, reason, sourceEvent}` (`CDataGridCellEditDetail`)	Restores server-rendered Cell content without a commit callback.

Methods

CSS

CSS variables to theme the components. Set them on an ancestor or the component itself.

CDataGrid CSS variables

Apply these variables to CDataGrid or one of its ancestors.

Variable	Type	Purpose	Default
`--cui-data-grid-viewport-size`	`length`	Maximum scroll-viewport block size.	`Server viewport_size or 400px`
`--cui-data-grid-row-height`	`length`	Fixed ready-Row and Cell block size.	`Server row_height or 48px`
`--cui-data-grid-min-width`	`length`	Horizontal overflow threshold.	`Sum of Column widths`
`--cui-data-grid-background`	`color`	Grid surface.	`Canvas`
`--cui-data-grid-foreground`	`color`	Primary text.	`CanvasText`
`--cui-data-grid-muted`	`color`	State and secondary text.	`Accessible CanvasText mix`
`--cui-data-grid-border-color`	`color`	Row Column and viewport borders.	`Adaptive neutral`
`--cui-data-grid-header-background`	`color`	Header surface.	`Adaptive neutral`
`--cui-data-grid-selected-background`	`color`	Selected Row surface.	`Adaptive blue`
`--cui-data-grid-striped-background`	`color`	Alternate Row surface.	`Subtle neutral`
`--cui-data-grid-hover-background`	`color`	Pointer Row feedback.	`Subtle Highlight mix`
`--cui-data-grid-focus-color`	`color`	Active Header and Cell outline.	`Highlight`
`--cui-data-grid-radius`	`length`	Viewport corners.	`0.625rem`

Attributes

HTML attributes defined on the components that you can refer to for CSS, inspection, and testing. Read-only.

CDataGrid attributes

Attribute	Element	Type	Meaning
`role`	Native table	`grid`	Exposes one composite data grid.
`aria-rowcount`	Native table	`integer`	Reports logical Rows plus the Header Row.
`aria-colcount`	Native table	`integer`	Reports logical Column count.
`aria-rowindex`	Header and supplied Rows	`positive integer`	Reports exact one-based logical position.
`aria-colindex`	Headers and Cells	`positive integer`	Reports exact one-based Column position.
`aria-sort`	Sorted Header	`ascending \| descending \| absent`	Reflects accepted sort direction.
`aria-selected`	Supplied Row	`boolean-string \| absent`	Reflects accepted selection when selection is enabled.
`data-row-key`	Supplied Row and Cells	`string`	Exposes stable Row identity.
`data-column-key`	Header and Cells	`string`	Exposes stable Column identity.
`data-row-index`	Supplied Row and Cells	`nonnegative integer`	Exposes zero-based logical Row position for owned navigation.
`data-column-index`	Header and Cells	`nonnegative integer`	Exposes zero-based Column position for owned navigation.
`data-selected`	Supplied Row	`present \| absent`	Reflects accepted selection for styling.
`data-pending`	Root	`present \| absent`	Marks a desired range outside the supplied window.
`data-selecting`	Root	`present \| absent`	Marks an active mouse drag-selection gesture.
`data-editable`	Root and editable Cells	`present \| absent`	Marks that editing is available.
`data-editing`	Root and active Cell	`present \| absent`	Marks the active edit session.
`data-editor`	Editable Cell	`CDataGridEditor` (`CDataGridEditor`)	Reflects the owned editor kind.
`data-state`	Root	`ready \| loading \| empty \| error`	Reflects settled server output state.
`tabindex`	Viewport Header or Cell	`0 \| -1`	Maintains one composite page Tab stop.

Selectors

Selectors for the DOM nodes in the components that you can use for CSS, inspection, and testing.

CDataGrid selectors

Selector	Element	Purpose
`[data-citry-ui-part="data-grid"]`	Root div	State reflections attrs and theme destination.
`[data-citry-ui-part="toolbar"]`	Optional toolbar wrapper	Application controls before the viewport.
`[data-citry-ui-part="status"]`	Visually hidden polite live region	Accepted sort and selection announcements.
`[data-citry-ui-part="viewport"]`	Scroll div	Horizontal and vertical scroll ownership.
`[data-citry-ui-part="table"]`	Native table Grid	Semantic and keyboard owner.
`[data-citry-ui-part="caption"]`	Optional native caption	Supplementary visible description.
`[data-citry-ui-part="header"]`	thead	Header Row group.
`[data-citry-ui-part="header-row"]`	Header tr	Exact Header Row position.
`[data-citry-ui-part="header-cell"]`	th	Navigable sortable Column Header.
`[data-citry-ui-part="sort-indicator"]`	Decorative span	Accepted sort direction glyph.
`[data-citry-ui-part="body"]`	tbody	Supplied Rows spacers and state output.
`[data-citry-ui-part="row"]`	Supplied tr	Stable selection and Row customization.
`[data-citry-ui-part="cell"]`	Supplied td	Navigable application Cell.
`[data-citry-ui-part="editor"]`	Runtime-owned input or select	Temporarily edits one checked Cell value.
`[data-citry-ui-part="loading"]`	Loading td	Localized loading output.
`[data-citry-ui-part="empty"]`	Empty td	Localized empty output.
`[data-citry-ui-part="error"]`	Error td	Localized failure output.
`[data-citry-ui-part="state-row"]`	State tr	Loading empty or error output.
`[data-citry-ui-part="spacer-row"]`	Presentation tr	Represents omitted fixed-height Rows.

Interfaces

Aliases and data shapes referenced above.

Input type aliases

Interface	Definition
`CClassValue`	`str \| Mapping[str, bool] \| Sequence[CClassValue]`
`CStyleValue`	`str \| Mapping[str, object] \| Sequence[CStyleValue]`
`CDataGridState`	`Literal["ready", "loading", "error"]`
`CDataGridDensity`	`Literal["comfortable", "compact", "spacious"]`
`CDataGridSelection`	`Literal["none", "single", "multiple"]`
`CDataGridAlign`	`Literal["start", "center", "end"]`
`CDataGridSortDirection`	`Literal["asc", "desc"]`
`CDataGridSortSource`	`Literal["pointer", "keyboard", "client"]`
`CDataGridSelectionSource`	`Literal["pointer", "keyboard", "client"]`
`CDataGridRangeReason`	`Literal["initial", "scroll", "resize", "configuration", "navigation"]`
`CDataGridEditor`	`Literal["text", "number", "checkbox", "select"]`
`CDataGridEditSource`	`Literal["pointer", "keyboard"]`

`CDataGridColumn`

Field	Type	Default	Meaning
`key`	`str`	-	Unique stable Column identity and Row mapping key.
`label`	`str`	-	Application-localized accessible Header label.
`sortable`	`bool`	-	Whether Header activation can request sorting.
`width`	`int`	-	Initial 40 through 2000 CSS-pixel Column width.
`align`	`CDataGridAlign` (`CDataGridAlign`)	-	Logical Cell text alignment.
`header_attrs`	`Mapping[str, object] \| None`	-	Copied allowed Header attributes.
`cell_attrs`	`Mapping[str, object] \| None`	-	Copied allowed attributes merged into every Cell in the Column.
`editable`	`bool`	-	Enables the built-in Cell editor for this Column.
`editor`	`CDataGridEditor` (`CDataGridEditor`)	-	Selects text number checkbox or select control.
`editor_options`	`Sequence[CDataGridEditOption]`	-	Supplies unique application-localized select options.
`editor_attrs`	`Mapping[str, str \| int \| float \| bool] \| None`	-	Adds checked kind-specific attributes such as min max step maxlength and placeholder.

`CDataGridCell`

Field	Type	Default	Meaning
`value`	`object`	-	Escaped or component-like server Cell output.
`attrs`	`Mapping[str, object] \| None`	-	Copied allowed attributes merged after Column Cell attributes.
`editable`	`bool \| None`	-	Overrides the Column editing policy for this Cell.

`CDataGridEditOption`

Field	Type	Default	Meaning
`value`	`str`	-	Unique submitted select value.
`label`	`str`	-	Application-localized visible option label.
`disabled`	`bool`	-	Prevents selection of this option.

`CDataGridRow`

Field	Type	Default	Meaning
`key`	`str`	-	Unique stable supplied-Row identity.
`cells`	`Mapping[str, object \| CDataGridCell]`	-	Exact one-to-one mapping for every Column key.
`disabled`	`bool`	-	Blocks selection and activation for this Row.
`attrs`	`Mapping[str, object] \| None`	-	Copied allowed Row attributes.

`CDataGridSort`

Field	Type	Default	Meaning
`key`	`str`	-	Known sortable Column key.
`direction`	`CDataGridSortDirection` (`CDataGridSortDirection`)	-	Accepted ascending or descending direction.

Field	Type	Default	Meaning
`column`	`CDataGridColumn`	-	Current Column record.
`column_index`	`int`	-	Zero-based Column position.
`sort_direction`	`CDataGridSortDirection \| None`	-	Accepted direction or none.
`sort_priority`	`int \| None`	-	One-based multi-sort priority or none.

`CDataGridCellSlotData`

Field	Type	Default	Meaning
`row`	`CDataGridRow`	-	Current Row record.
`column`	`CDataGridColumn`	-	Current Column record.
`cell`	`CDataGridCell`	-	Normalized Cell record.
`row_index`	`int`	-	Zero-based logical Row position.
`column_index`	`int`	-	Zero-based Column position.
`selected`	`bool`	-	Initial accepted supplied-Row selection.

Field	Type	Default	Meaning
`sort`	`list[dict[str, str]]`	-	Requested ordered sort model.
`previousSort`	`list[dict[str, str]]`	-	Accepted model before the request.
`columnKey`	`str`	-	Activated Column key.
`direction`	`CDataGridSortDirection \| None`	-	Requested direction or none when cleared.
`source`	`CDataGridSortSource`	-	Pointer keyboard or client cause.
`sourceEvent`	`object \| None`	-	Native source Event.

`CDataGridSelectionChangeDetail`

Field	Type	Default	Meaning
`selected`	`list[str]`	-	Requested or committed selected supplied-Row keys.
`previousSelected`	`list[str]`	-	Accepted selection before the request.
`changed`	`list[str]`	-	Keys whose selection changed.
`rowKey`	`str \| None`	-	Directly activated Row key.
`selectedRow`	`bool \| None`	-	Requested state of the directly activated Row.
`controlled`	`bool`	-	Whether client selected owns the model.
`source`	`CDataGridSelectionSource`	-	Pointer keyboard or client cause.
`sourceEvent`	`object \| None`	-	Native source Event.

`CDataGridRangeChangeDetail`

Field	Type	Default	Meaning
`startIndex`	`int`	-	Desired inclusive logical start.
`endIndex`	`int`	-	Desired exclusive logical end.
`visibleStartIndex`	`int`	-	Estimated visible inclusive start.
`visibleEndIndex`	`int`	-	Estimated visible exclusive end.
`requestId`	`int`	-	Monotonic instance-local request ID.
`reason`	`CDataGridRangeReason`	-	Initial scroll resize configuration or navigation cause.
`sourceEvent`	`object \| None`	-	Native source Event when available.

`CDataGridCellActivateDetail`

Field	Type	Default	Meaning
`rowKey`	`str`	-	Activated Row key.
`columnKey`	`str`	-	Activated Column key.
`rowIndex`	`int`	-	Zero-based logical Row position.
`columnIndex`	`int`	-	Zero-based Column position.
`source`	`keyboard \| pointer`	-	Activation cause.
`sourceEvent`	`object`	-	Native source Event.

`CDataGridCellEditDetail`

Field	Type	Default	Meaning
`rowKey`	`str`	-	Edited Row key.
`columnKey`	`str`	-	Edited Column key.
`rowIndex`	`int`	-	Zero-based logical Row position.
`columnIndex`	`int`	-	Zero-based Column position.
`editor`	`CDataGridEditor`	-	Active native control kind.
`previousValue`	`str \| float \| bool`	-	Server-authored value at edit start.
`source`	`CDataGridEditSource`	-	Keyboard or pointer entry source.
`reason`	`str`	-	Entry commit or cancellation reason.
`sourceEvent`	`object`	-	Native source Event.

Translation keys

Catalog keys used by this family. An explicit component input or slot listed in Override takes precedence over the catalog for that instance.

CDataGrid translation keys

Key	Purpose	Variables	Override	Browser updates
`citry-ui-data-grid-loading`	Labels the loading state.	`None.`	`loading_label`	Stable `$c-tr` text follows client locale changes.
`citry-ui-data-grid-empty`	Labels the empty state.	`None.`	`empty_label`	Stable `$c-tr` text follows client locale changes.
`citry-ui-data-grid-error`	Labels the error state.	`None.`	`error_label`	Stable `$c-tr` text follows client locale changes.
`citry-ui-data-grid-sort-ascending`	Announces accepted ascending sorting.	`column: str`	`sort_ascending_label` with `{column}`	One-shot `i18n.tr()` writes the live region after acceptance.
`citry-ui-data-grid-sort-descending`	Announces accepted descending sorting.	`column: str`	`sort_descending_label` with `{column}`	One-shot `i18n.tr()` writes the live region after acceptance.
`citry-ui-data-grid-sort-cleared`	Announces accepted cleared sorting.	`column: str`	`sort_cleared_label` with `{column}`	One-shot `i18n.tr()` writes the live region after acceptance.
`citry-ui-data-grid-selected-one`	Announces one selected supplied Row.	`None.`	`selected_one_label`	One-shot `i18n.tr()` writes the live region after commit or acceptance.
`citry-ui-data-grid-selected`	Announces multiple selected supplied Rows.	`count: str`	`selected_label` with `{count}`	One-shot `i18n.tr()` writes the live region after commit or acceptance.
`citry-ui-data-grid-edit`	Names the runtime-owned editor.	`column: str`	`edit_label` with `{column}`	One-shot `i18n.tr()` applies when an editor is created.
`citry-ui-data-grid-editing`	Announces edit entry.	`column: str`	`editing_label` with `{column}`	One-shot `i18n.tr()` writes the live region.
`citry-ui-data-grid-edit-submitted`	Announces a submitted edit request.	`column: str`	`edit_submitted_label` with `{column}`	One-shot `i18n.tr()` writes the live region.
`citry-ui-data-grid-edit-cancelled`	Announces edit cancellation.	`column: str`	`edit_cancelled_label` with `{column}`	One-shot `i18n.tr()` writes the live region.
`citry-ui-data-grid-edit-invalid`	Announces native validation or callback rejection.	`column: str`	`edit_invalid_label` with `{column}`	One-shot `i18n.tr()` writes the live region.