Data View
Typed grid/list presentation with controlled layout switching, stable identity, and deterministic loading, error, and empty states.
- Selector
- ui-data-view
- Package
- @ngnova/ui/data-view
Import
import { UiDataViewComponent, UiDataViewItemDirective } from '@ngnova/ui/data-view';Usage & variants
Live examples use the public ui-data-view API, paired with the exact snippet a product team would paste into an Angular app.
Component catalog
Typed grid/list presentation with controlled layout switching, stable identity, and deterministic loading, error, and empty states.
Button
Actions and intent · grid
Input
Text entry and validation · grid
Table
Structured enterprise data · grid
Production guidance
Use these notes to decide when the component belongs in a product workflow and what to verify before shipping.
When to use
Use for catalogs, search results, media collections, and records that are easier to scan as cards than strict columns.
Watch for
layout is controlled; update it after layoutChange to update the pressed state and template context.
Product recipes
Apply Data View in distinct, copyable product scenarios—not just an isolated component state.
Controlled catalog layout
The toggle emits a request and retains its pressed state until parent state updates.
1 2 3 4 5 6 7 8 9 10 11 12
<ui-data-view
[items]="products()"
[layout]="layout()"
(layoutChange)="layout.set($event)"
[trackBy]="trackProduct"
showLayoutToggle
ariaLabel="Product results"
>
<ng-template uiDataViewItem let-product let-layout="layout">
<app-product-card [product]="product" [compact]="layout === 'list'" />
</ng-template>
</ui-data-view>Async states
State precedence is loading, error, empty, then populated records.
1 2 3 4 5 6 7 8
<ui-data-view
[items]="results()"
[loading]="loading()"
[error]="requestFailed()"
loadingText="Loading products..."
errorText="Products could not be loaded."
emptyText="No products match these filters."
/>API Reference
Inputs and outputs are semver-sensitive public API. Keep examples aligned with this table.
Inputs
items [] readonly T[] Ordered records rendered through the item template or safe text fallback.
layout 'grid' 'grid' | 'list' Controlled visual layout.
gap 'md' 'sm' | 'md' | 'lg' Tokenized space between records.
showLayoutToggle false boolean Shows the optional controlled grid/list switch.
loading false boolean Shows and announces the loading state.
error false boolean Shows the alert state when loading is inactive.
loadingText 'Loading items...' string Localized loading message.
errorText 'Unable to load items.' string Localized failure message.
emptyText 'No items found.' string Localized empty-result message.
ariaLabel 'Data view' string Accessible name for the view section.
layoutToggleAriaLabel 'Choose layout' string Accessible name for the layout switch group.
gridLabel 'Grid' string Localized visible grid-layout label.
listLabel 'List' string Localized visible list-layout label.
trackBy null UiDataViewTrackBy<T> | null Optional stable record identity; item identity is the fallback.
uiDataViewItem optional directive Typed item template with item, index, layout, first, and last context.
| Name | Type | Default | Description |
|---|---|---|---|
items | readonly T[] | [] | Ordered records rendered through the item template or safe text fallback. |
layout | 'grid' | 'list' | 'grid' | Controlled visual layout. |
gap | 'sm' | 'md' | 'lg' | 'md' | Tokenized space between records. |
showLayoutToggle | boolean | false | Shows the optional controlled grid/list switch. |
loading | boolean | false | Shows and announces the loading state. |
error | boolean | false | Shows the alert state when loading is inactive. |
loadingText | string | 'Loading items...' | Localized loading message. |
errorText | string | 'Unable to load items.' | Localized failure message. |
emptyText | string | 'No items found.' | Localized empty-result message. |
ariaLabel | string | 'Data view' | Accessible name for the view section. |
layoutToggleAriaLabel | string | 'Choose layout' | Accessible name for the layout switch group. |
gridLabel | string | 'Grid' | Localized visible grid-layout label. |
listLabel | string | 'List' | Localized visible list-layout label. |
trackBy | UiDataViewTrackBy<T> | null | null | Optional stable record identity; item identity is the fallback. |
uiDataViewItem | directive | optional | Typed item template with item, index, layout, first, and last context. |
Outputs
layoutChange OutputEmitterRef<UiDataViewLayout> Emits the requested layout while the parent remains state owner.
| Name | Type | Description |
|---|---|---|
layoutChange | OutputEmitterRef<UiDataViewLayout> | Emits the requested layout while the parent remains state owner. |
Accessibility
- The named section contains list/listitem semantics independent of grid or list visual layout.
- The optional layout group uses native buttons and aria-pressed; async states use status or alert semantics.
- Keep meaningful headings, links, and actions inside the item template.
Keyboard behavior
- Layout buttons use native Tab, Enter, and Space behavior with visible keyboard focus.
- Interactive content inside each item retains its own native keyboard order.
Testing guidance
- Assert typed context, responsive layout classes, stable tracking, controlled layout requests, async-state precedence, semantics, localization, and UiDataViewHarness behavior.