` has `overflow-auto` to handle wide tables on small screens
without breaking the page layout. The table itself is `w-full caption-bottom
text-sm` so it fills its container and uses bottom-positioned captions.
## Example
<.data_grid>
...
<.data_grid_body id="rows" phx-update="stream">
...
## Attributes
* `id` (`:string`) - Optional ID for the outer wrapper div; used to build the aria-live status region ID. Defaults to `nil`.
* `status_message` (`:string`) - Screen reader announcement for sort/filter/page changes. E.g.: 'Sorted by Name, ascending'. Defaults to `""`.
* `responsive_mode` (`:atom`) - Controls responsive behavior on small screens.
- `:scroll` β default horizontal scroll on overflow (via `overflow-x-auto`)
- `:stack` β below `md:`, each row becomes a vertical card layout
- `:hide_columns` β no change to the grid itself; columns with a `priority`
attr can be hidden via `hidden md:table-cell` in the consuming template
Defaults to `:scroll`. Must be one of `:scroll`, `:stack`, or `:hide_columns`.
* `sticky_header` (`:boolean`) - When `true`, the `
` is sticky at the top of the scrollable container.
Adds `sticky top-0 z-10 bg-background` to the thead via a child selector.
Defaults to `false`.
* `loading` (`:boolean`) - When `true`, renders a semi-transparent overlay with a spinner icon over the
table to indicate an in-flight data fetch. The table content remains visible
but non-interactive beneath the overlay.
Defaults to `false`.
* `class` (`:string`) - Additional CSS classes for the outer overflow wrapper. Defaults to `nil`.
* Global attributes are accepted. HTML attributes forwarded to the `` element (e.g. `aria-label`, `data-*`).
## Slots
* `inner_block` (required) - Table structure: thead, data_grid_body/1, tfoot.
# `data_grid_active_filters`
Flex row of active filter chips with a "Clear all" button.
Renders nothing when `filters` is empty. Each chip fires `on_remove` with
`phx-value-key` set to the filter's `:value`. A "Clear all" button fires
`on_clear_all`.
## Example
<.data_grid_active_filters
:if={@filters != []}
filters={@filters}
on_remove="remove_filter"
on_clear_all="clear_filters"
/>
Where `@filters` is e.g.:
[%{label: "Role: Admin", value: "role"}, %{label: "Status: Active", value: "status"}]
## Attributes
* `filters` (`:list`) (required) - List of active filter maps. Each must have:
- `label` β display string (e.g. "Role: Admin")
- `value` β key sent to `on_remove` handler (e.g. "role")
* `on_remove` (`:string`) - phx-click event fired by each chip. Defaults to `"remove_filter"`.
* `clear_all_label` (`:string`) - Label for the clear-all button. Defaults to `"Clear all"`.
* `on_clear_all` (`:string`) - phx-click event for clear all. Defaults to `"clear_all_filters"`.
* `class` (`:string`) - Defaults to `nil`.
# `data_grid_aggregation_row`
Renders a visually distinct aggregation row for totals, averages, or sums.
Use at the bottom of `data_grid_body/1` (or after a group's rows).
Applies a top double-border and `font-medium bg-muted/30` styling.
## Example
<.data_grid_aggregation_row>
<.data_grid_cell class="font-semibold">Total
<.data_grid_cell class="tabular-nums">{@sum}
## Attributes
* `class` (`:string`) - Defaults to `nil`.
* Global attributes are accepted.
## Slots
* `inner_block` (required) - data_grid_cell/1 children with aggregate values.
# `data_grid_body`
Renders the `` element.
The `[&_tr:last-child]:border-0` rule removes the bottom border from the
last row so the table does not appear to have a double border with the
pagination row below it.
Supports `phx-update="stream"` for incremental LiveView Streams updates.
Always provide an `id` attribute when using streams so LiveView can track
the element across patches.
## Example
<.data_grid_body id="user-rows" phx-update="stream">
<.data_grid_row :for={{dom_id, user} <- @streams.users} id={dom_id}>
<.data_grid_cell><%= user.name %>
## Attributes
* `class` (`:string`) - Additional CSS classes. Defaults to `nil`.
* Global attributes are accepted. HTML attributes forwarded to the `` element. The most important
use is `phx-update="stream"` for LiveView Streams:
<.data_grid_body id="users" phx-update="stream">
<.data_grid_row :for={{dom_id, user} <- @streams.users} id={dom_id}>
...
When using streams, `id` is also required on the `` itself.
## Slots
* `inner_block` (required) - data_grid_row/1 children.
# `data_grid_cell`
Renders a `| ` data cell with consistent `px-4 py-3` padding.
The `[&:has([role=checkbox])]:pr-0` rule removes right padding from cells
containing a checkbox (`data_grid_row_checkbox/1`), keeping checkboxes
visually aligned with the select-all header.
## Example
<.data_grid_cell>John Smith
<.data_grid_cell class="text-right font-mono">$1,234.56
<.data_grid_cell>
<.badge variant={:secondary}><%= user.role %>
## Attributes
* `density` (`:atom`) - Padding density for the data cell:
- `:compact` β `px-3 py-1.5`
- `:normal` β `px-4 py-3` (default)
- `:comfortable` β `px-4 py-4`
Defaults to `:normal`. Must be one of `:compact`, `:normal`, or `:comfortable`.
* `class` (`:string`) - Additional CSS classes for the cell. Defaults to `nil`.
* Global attributes are accepted. HTML attributes forwarded to the ` | ` element (e.g. `colspan`, `rowspan`).
## Slots
* `inner_block` (required) - Cell content β text, badges, buttons, avatars, etc.
# `data_grid_column_group`
Renders a ` | ` spanning multiple columns for two-row grouped headers.
Use inside a top ` | ` in `` above the individual column headers.
## Example
<.data_grid_column_group colspan={2} label="Personal Info" />
<.data_grid_column_group colspan={3} label="Work Details" />
<.data_grid_head>Name
<.data_grid_head>Email
...
## Attributes
* `colspan` (`:integer`) (required) - Number of columns this group spans.
* `label` (`:string`) - Group header text. Defaults to `""`.
* `class` (`:string`) - Defaults to `nil`.
* Global attributes are accepted.
# `data_grid_column_toggle`
Renders a column-visibility toggle button with a dropdown checklist.
Clicking the "Columns" button calls `JS.toggle/1` to show/hide a dropdown
menu listing all columns with checkboxes. Checking/unchecking a box fires
`on_toggle` with `phx-value-column` set to the column key. All visibility
state is managed in the LiveView β this component is stateless.
The dropdown is positioned `absolute right-0 top-10` so it opens below
and to the right of the button. Ensure the parent has `position: relative`
(the wrapper div adds this automatically).
## Example
<.data_grid_column_toggle
id="user-columns"
columns={@columns}
on_toggle="toggle_column"
/>
## Attributes
* `id` (`:string`) (required) - Unique element ID. Used to build the dropdown menu ID (e.g. `"my-grid-menu"`)
and as the toggle target for `JS.toggle/1`. Must be unique on the page.
* `columns` (`:list`) (required) - List of column definition maps. Each map must have:
- `key` β String used as `phx-value-column` when the checkbox is clicked
- `label` β Human-readable column name shown in the dropdown
- `visible` β Boolean controlling the checked state of the checkbox
Example: `[%{key: "name", label: "Name", visible: true}, ...]`
* `on_toggle` (`:string`) - `phx-click` event fired when a column checkbox is toggled. Receives
`phx-value-column` set to the column `key`. Handle with:
def handle_event("toggle_column", %{"column" => key}, socket) do
columns = Enum.map(socket.assigns.columns, fn col ->
if col.key == key, do: %{col | visible: !col.visible}, else: col
end)
{:noreply, assign(socket, columns: columns)}
end
Defaults to `"toggle_column"`.
* `class` (`:string`) - Additional CSS classes for the wrapper div. Defaults to `nil`.
# `data_grid_density_toggle`
Three-button toggle to switch between compact / normal / comfortable row density.
Fires `on_change` with `phx-value-density` set to the selected value string.
Pass the resulting density atom to `data_grid_head/1` and `data_grid_cell/1`.
## Example
<.data_grid_toolbar>
<.data_grid_density_toggle density={@density} on_change="set_density" />
## Handler
def handle_event("set_density", %{"density" => d}, socket) do
{:noreply, assign(socket, density: String.to_existing_atom(d))}
end
## Attributes
* `density` (`:atom`) - Currently active density. Defaults to `:normal`. Must be one of `:compact`, `:normal`, or `:comfortable`.
* `on_change` (`:string`) - phx-click event name. Defaults to `"change_density"`.
* `class` (`:string`) - Defaults to `nil`.
# `data_grid_detail_row`
Renders a full-width detail panel row for expandable row content.
Place immediately after the expanded `data_grid_row/1`. Toggle visibility
in your LiveView by conditionally rendering this row.
## Example
<.data_grid_row id={dom_id}>
...
<.data_grid_cell>
<.data_grid_detail_row :if={row.id in @expanded} colspan={5}>
Detailed view for {row.name}
## Attributes
* `colspan` (`:integer`) (required) - Number of columns to span (equals total column count).
* `class` (`:string`) - Defaults to `nil`.
* Global attributes are accepted.
## Slots
* `inner_block` (required)
# `data_grid_export_button`
Renders a client-side CSV export button.
The `PhiaGridExport` hook reads visible `` columns (skipping those
with `data-hidden`) and all ` | ` in the `
` to build a CSV blob
and trigger a browser download. Entirely client-side β no server call.
## Example
<.data_grid_toolbar>
<.data_grid_export_button
id="users-export"
target_id="users-grid"
filename="users.csv"
/>
<.data_grid id="users-grid">...
## Attributes
* `id` (`:string`) (required) - Unique ID (required for phx-hook).
* `target_id` (`:string`) (required) - ID of the `data_grid` table to export.
* `filename` (`:string`) - Downloaded filename. Defaults to `"export.csv"`.
* `label` (`:string`) - Defaults to `"Export CSV"`.
* `class` (`:string`) - Defaults to `nil`.
* Global attributes are accepted.
# `data_grid_filter_chip`
Badge-style chip showing an active filter with a remove button.
Fires `on_remove` with `phx-value-key={value}` when the Γ is clicked.
## Example
<.data_grid_filter_chip label="Role: Admin" value="role" on_remove="clear_filter" />
## Attributes
* `label` (`:string`) (required) - Display text for the filter chip.
* `value` (`:string`) (required) - phx-value-key sent when chip is removed.
* `on_remove` (`:string`) - phx-click event name. Defaults to `"remove_filter"`.
* `class` (`:string`) - Defaults to `nil`.
# `data_grid_group_head`
Full group header row wrapper for two-level column grouping.
Renders a `` that should be placed as the first row in ``.
Fill it with `data_grid_column_group/1` cells.
## Example
<.data_grid_group_head>
<.data_grid_column_group colspan={2} label="Identity" />
<.data_grid_column_group colspan={2} label="Status" />
## Attributes
* `class` (`:string`) - Defaults to `nil`.
* Global attributes are accepted.
## Slots
* `inner_block` (required)
# `data_grid_group_row`
Renders a collapsible row-group header with a chevron and optional count badge.
Fires `on_toggle` with `phx-value-value={value}` when clicked.
Your LiveView maintains the expanded/collapsed state per group key.
## Example
<.data_grid_group_row
label="Active Users"
count={length(@active_users)}
expanded={@groups_expanded["active"]}
on_toggle="toggle_group"
value="active"
colspan={5}
/>
## Attributes
* `label` (`:string`) (required) - Group name displayed in the header row.
* `count` (`:any`) - Item count shown as a badge (nil to hide). Defaults to `nil`.
* `expanded` (`:boolean`) - Controls chevron direction. Defaults to `true`.
* `on_toggle` (`:string`) - phx-click event name. Defaults to `"toggle_group"`.
* `value` (`:string`) (required) - phx-value-value identifying this group.
* `colspan` (`:integer`) - Colspan for the group label cell. Defaults to `1`.
* `class` (`:string`) - Defaults to `nil`.
* Global attributes are accepted.
# `data_grid_head`
Renders a `| ` column header with optional sort button.
When `:sort_key` is set, the header content is wrapped in a ` |