Data Grid

Use CDataGrid for application data that benefits from one composite Tab stop, cell navigation, row selection, server-owned 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. The grid never reorders application Rows itself: onSortChange receives a request, and accepted sort state must come back from the owner. 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,detail)=>{
              sort=next;
              notice=`Accepted sort: ${detail.columnKey} ${detail.direction ?? 'none'}`;
            },
            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.

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 is always request/accept because only the application understands its data. Selection becomes uncontrolled again when client selected is omitted or null. Accepted sort and selection 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 preview shows the final server range'}">
        <output x-text="notice">This preview shows the final server range</output>
        <c-CDataGrid
          c-columns="columns"
          c-rows="rows"
          label="Audit records"
          c-total_count="36"
          c-start_index="20"
          c-row_height="44"
          c-initial_index="20"
          $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(20, 36)
            ),
        }


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.

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 links, buttons, inputs, editable content, or another Tab stop in this first version; focus remains on the Header or Cell. Use onCellActivate for Enter and double-click activation.

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

Inline editing, arbitrary 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 server-authoritative 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 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.
`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.	Controls accepted sort indicators while supplied.
`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.

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`)	Always request-only; DOM Rows never reorder locally.
`onSelectionChange`	`(selected: string[], detail: CDataGridSelectionChangeDetail) => void` (`CDataGridSelectionChangeDetail`)	Pointer or Shift+Space requests a supplied-Row selection change.	`{selected, previousSelected, changed, rowKey, selectedRow, controlled, source, sourceEvent}` (`CDataGridSelectionChangeDetail`)	Uncontrolled state commits first; controlled state waits for acceptance.
`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 body Cell.	`{rowKey, columnKey, rowIndex, columnIndex, source, sourceEvent}` (`CDataGridCellActivateDetail`)	Does not enter edit mode or mutate data.

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-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="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"]`

`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.

`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.

`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.

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.