# State Container Use `ui-state-container` when a view needs a consistent state machine around async data. It keeps `loading`, `empty`, `error`, and `content` rendering in one place, which is usually cleaner than scattering conditionals across the page. ## Import ```ts import { StateContainerComponent, initialState, loadingState, loadedState, errorState, type State } from 'ui'; ``` ## Initial, loading, empty, loaded, and error ```ts import { Component } from '@angular/core'; import { StateContainerComponent, type State, initialState, loadedState, loadingState, errorState, } from 'ui'; interface UserCard { id: number; name: string; role: string; } @Component({ selector: 'app-state-container-basic-cycle-demo', standalone: true, imports: [StateContainerComponent], template: `
@for (preset of presets; track preset.label) {

{{ preset.label }}

@for (user of preset.state.data ?? []; track user.id) {
{{ user.name }}
{{ user.role }}
}
}
`, }) export class StateContainerBasicCycleDemoComponent { private readonly users: UserCard[] = [ { id: 1, name: 'Anna Kowalska', role: 'Administrator' }, { id: 2, name: 'Piotr Nowak', role: 'Project Manager' }, ]; protected readonly presets: Array<{ label: string; state: State }> = [ { label: 'Initial', state: initialState() }, { label: 'Loading', state: loadingState(initialState()) }, { label: 'Empty', state: loadedState([]) }, { label: 'Loaded', state: loadedState(this.users) }, { label: 'Error', state: errorState('Unable to load people data.') }, ]; } ``` ## Empty-on-initial behavior ```ts import { Component } from '@angular/core'; import { StateContainerComponent, initialState } from 'ui'; @Component({ selector: 'app-state-container-empty-initial-demo', standalone: true, imports: [StateContainerComponent], template: `

Initial hidden

Initial shown as empty

`, }) export class StateContainerEmptyInitialDemoComponent { protected readonly state = initialState(); } ``` ## Overlay loading on existing content ```ts import { Component, signal } from '@angular/core'; import { StateContainerComponent, type State, loadedState, loadingState } from 'ui'; interface SummaryCard { id: number; label: string; value: string; } @Component({ selector: 'app-state-container-overlay-demo', standalone: true, imports: [StateContainerComponent], template: `
@for (item of data; track item.id) {
{{ item.label }}
{{ item.value }}
}
`, }) export class StateContainerOverlayDemoComponent { protected readonly data: SummaryCard[] = [ { id: 1, label: 'Active projects', value: '12' }, { id: 2, label: 'Pending reviews', value: '4' }, { id: 3, label: 'Failed jobs', value: '1' }, ]; protected readonly refreshing = signal(true); protected readonly state = signal>(loadingState(loadedState(this.data))); protected toggleRefresh(): void { this.refreshing.update(value => !value); this.state.set( this.refreshing() ? loadingState(loadedState(this.data)) : loadedState(this.data), ); } } ``` ## Custom loading, empty, and data templates ```ts import { Component, signal } from '@angular/core'; import { StateContainerComponent, type State, initialState, loadedState, loadingState } from 'ui'; @Component({ selector: 'app-state-container-custom-templates-demo', standalone: true, imports: [StateContainerComponent], template: `
Syncing records...
Step 2 of 3
All caught up
There are no new records to review.
Data loaded successfully
Records: {{ data?.length ?? 0 }}
`, }) export class StateContainerCustomTemplatesDemoComponent { protected readonly state = signal>(loadingState(initialState())); constructor() { setTimeout(() => { this.state.set(loadedState([])); setTimeout(() => { this.state.set(loadedState(['Record A', 'Record B'])); }, 1200); }, 1200); } } ``` ## Embedded list or panel layout ```ts import { Component } from '@angular/core'; import { StateContainerComponent, errorState, type State, TextComponent, ButtonComponent, } from 'ui'; interface ActivityItem { id: number; title: string; } @Component({ selector: 'app-state-container-list-layout-demo', standalone: true, imports: [ButtonComponent, StateContainerComponent, TextComponent], template: `
Filter
@for (item of state.data ?? []; track item.id) {
{{ item.title }}
}
`, }) export class StateContainerListLayoutDemoComponent { protected readonly state: State = errorState( 'The activity feed could not be refreshed.', ); protected readonly retryAction = { label: 'Retry', variant: 'primary' as const, icon: 'arrow_sync' as const, action: () => {}, }; } ``` ## Data template without wrapper conditionals ```ts import { Component } from '@angular/core'; import { StateContainerComponent, loadedState, type State } from 'ui'; interface Metric { id: number; label: string; value: string; } @Component({ selector: 'app-state-container-data-template-demo', standalone: true, imports: [StateContainerComponent], template: `
@for (item of data ?? []; track item.id) {
{{ item.label }}
{{ item.value }}
}
`, }) export class StateContainerDataTemplateDemoComponent { protected readonly state: State = loadedState([ { id: 1, label: 'Open tasks', value: '24' }, { id: 2, label: 'Blocked items', value: '3' }, { id: 3, label: 'Approvals', value: '7' }, ]); } ``` ## Accessibility ### State clarity The visible branch should make it clear whether the view is loading, empty, failed, or ready. Titles and descriptions passed to the built-in states should be specific enough to explain what is happening. ### Actionable recovery When the container renders empty or error actions, those actions should lead to meaningful next steps. | Branch | Guidance | | --- | --- | | Loading | Explain what is being loaded when the wait is noticeable. | | Empty | Offer a next step only when one is genuinely available. | | Error | Prefer direct recovery such as retrying or navigating to help. | ### Custom templates If you override loading, empty, error, or data templates, preserve the same clarity and keyboard accessibility that the built-in state components provide.