NgxViewState

The ngx-view-state library is designed to simplify managing Loading/Success/Error states in Angular applications that use NgRx.

Overview

- Installation
- Usage with NgRx
- Usage ngxViewState directive
- Components customization
- Usage with HttpClient
- Key parts of the library
- Documentation

$3

$3

Installation

Run: npm install ngx-view-state

Usage With NgRx

#### 1. Create view state feature and pass generic type for the error state

``typescript
// view-state.feature.ts
import { createViewStateFeature } from 'ngx-view-state';

export const { viewStatesFeature, selectActionViewStatus, selectIsAnyActionLoading } = createViewStateFeature();
`

#### 2. Provide the viewStateFeature and ViewStateEffect in the root

`typescript
// app.config.ts

import { provideState, provideStore } from '@ngrx/store';
import { provideEffects } from '@ngrx/effects';
import { viewStatesFeature } from './store/view-state.feature';
import { ViewStateEffects } from 'ngx-view-state';

export const appConfig: ApplicationConfig = {
providers: [provideStore({}), provideState(viewStatesFeature), provideEffects(ViewStateEffects)],
};
`

#### 3. Register actions in your effect to mark them as view state actions

`typescript
// todos.effects.ts

import { ViewStateActionsService } from 'ngx-view-state';

@Injectable()
export class TodosEffects {
constructor(
private actions$: Actions,
private viewStateActionsService: ViewStateActionsService
) {
this.viewStateActionsService.add([
{
startLoadingOn: TodosActions.loadTodos,
resetOn: [TodosActions.loadTodosSuccess],
errorOn: [TodosActions.loadTodosFailure],
},
{
startLoadingOn: TodosActions.addTodo,
resetOn: [TodosActions.addTodoSuccess],
errorOn: [TodosActions.addTodoFailure],
},
// Update and delete actions can be added in the same way
]);
}
}
`

#### 4. Create view state selectors

`typescript
// todos.selectors.ts

import { selectActionViewStatus, selectIsAnyActionLoading } from '../../store/view-state.feature';
import { TodosActions } from './todos.actions';

// Select loading/error/idle status of the loadTodos action
export const selectTodosViewStatus = selectActionViewStatus(TodosActions.loadTodos);

// To display an overlay when any of the actions are loading
export const selectIsTodosActionLoading = selectIsAnyActionLoading(
TodosActions.addTodo,
TodosActions.updateTodo,
TodosActions.deleteTodo
);
`

#### 5. Make use of previously created selectors and dispatch the load action.

`typescript
// todos.component.ts

import { selectTodos } from './store/todos.feature';
import { selectTodosViewStatus, selectIsTodosActionLoading } from './store/todos.selectors';
import { ViewStateDirective } from 'ngx-view-state';

@Component({
selector: 'app-todos',
imports: [ViewStateDirective],
templateUrl: './todos.component.html',
styleUrl: './todos.component.css'
})
export class TodosComponent {
public todos$ = this.store.select(selectTodos);

public viewState$ = this.store.select(selectTodosViewStatus);
public isOverlayLoading$ = this.store.select(selectIsTodosActionLoading);

constructor(private store: Store) {
this.store.dispatch(TodosActions.loadTodos());
}
`

Usage ngxViewState directive

Import the ViewStateDirective in your component and pass the view state value to the directive.

`html




You can provide your own components by using the provideLoadingStateComponent and provideErrorStateComponent functions.

By default, the library uses the ngx-view-state components with simple template

`typescript
// app.config.ts

import { provideLoadingStateComponent, provideErrorStateComponent } from 'ngx-view-state';

export const appConfig: ApplicationConfig = {
providers: [
// ...
provideLoadingStateComponent(LoadingComponent),
provideErrorStateComponent(ErrorComponent),
],
};
`

Usage with HttpClient

mapToViewModel is a utility function that can be used to map the response of an HTTP request to a ComponentViewModel interface that is compatible with the ngxViewState directive.

`typescript
import { mapToViewModel } from 'ngx-view-state';

@Injectable()
export class TodosService {
constructor(private http: HttpClient) {}

loadTodos(): Observable> {
return this.http.get('https://jsonplaceholder.typicode.com/todos').pipe(mapToViewModel());
}
}
`

And then in your component, you can use the ngxViewState directive to handle the view state of the HTTP request.

`typescript
// todos.component.ts

import { TodosService } from './todos.service';

@Component({
selector: 'app-todos',
imports: [ViewStateDirective],
templateUrl: './todos.component.html',
styleUrl: './todos.component.css',
})
export class TodosComponent {
public todos$ = this.todosService.loadTodos();

constructor(private todosService: TodosService) {}
}
`

`html




You can also perform custom mapping by passing an object with onSuccess and onError handlers to the mapToViewModel function.

`typescript
import { mapToViewModel } from 'ngx-view-state';


loadTodos(): Observable> {
return this.http.get('https://jsonplaceholder.typicode.com/todos').pipe(
mapToViewModel({
onSuccess: (data) => ({ viewStatus: loadedViewStatus(), data: data.map(...) }),
onError: (error) => ({ viewStatus: errorViewStatus('Failed to load todos') })
})
);
}
`

Key parts of the library

$3

- createViewStateFeature (view-state.feature.ts)
Factory that creates an NgRx feature to manage view states for actions.
Generates selectors such as selectActionViewStatus and selectIsAnyActionLoading.
- ViewStateActions (view-state.actions.ts)
Defines actions for starting, resetting, or reporting errors in view states.
- ViewStateEffects (view-state.effects.ts)
Listens for configured actions and dispatches view-state actions to update the store.
- ViewStateActionsService – a service that maps specific actions to “start loading,” “reset,” or “error” behaviors. It exposes helpers like add, remove, and checks for a given action type.
This service is typically injected in an NgRx effect to register which actions affect the view state

$3

- ViewStateDirective
Allows components to display content, loading, or error components based on a ViewStatus or ComponentViewModel.
Reacts to status changes and renders the appropriate template, spinner, or error component.

$3

- Factory functions for constructing ViewStatus values (loadingViewStatus, errorViewStatus, etc.).
- mapToViewModel
Helper to transform HTTP responses into a typed view model used by the directive.

$3

- Simple LoadingStateComponent and ErrorStateComponent are located in components/.
You can supply custom components via the provideLoadingStateComponent or provideErrorStateComponent tokens.

Documentation

- createViewStateFeature
- Selectors
- ViewStateActions
- ViewStateEffects
- ViewStatus
- ViewStateDirective
- provideLoadingStateComponent
- provideErrorStateComponent
- ViewStateErrorProps
- ComponentViewModel
- mapToViewModel

$3

Creates a feature that holds the view state of the actions.

State interface:

`typescript
export interface ViewState {
actionType: string;
viewStatus: ViewStatus;
}
`

Where E generic is the type of the error state.

- actionType is the static type property of the action.
- viewStatus is the view state of the action.

Returns an object with the following properties:

- initialState - Initial state of the view state feature.
- viewStatesFeatureName - Name of the view state feature.
- viewStatesFeature - NgRx feature that holds the view state of the actions.

$3

- selectViewStateEntities - returns the view state entities.
- selectViewStateActionTypes - returns the view state action types (TodosActions.loadTodos.type).
- selectAllViewState - returns all view states.
- selectActionViewStatus - returns the view status of the action.
- selectViewState - returns the view state entity by action type.
- selectIsAnyActionLoading - returns whether any of the provided actions are in LOADING state.
- selectIsAnyActionLoaded - returns whether any of the provided actions are in LOADED state.
- selectIsAnyActionError - returns whether any of the provided actions are in ERROR state.
- selectIsAnyActionIdle - returns whether any of the provided actions are in IDLE state.

$3

Action group to work with the view state reducer

`typescript
export const ViewStateActions = createActionGroup({
source: 'ViewState',
events: {
startLoading: props<{ actionType: string }>(),
reset: props<{ actionType: string }>(),
resetMany: props<{ actionTypes: string[] }>(),
error: props<{ actionType: string; error?: unknown }>(),
errorMany: props<{ actionTypes: { actionType: string; error?: unknown }[] }>(),
},
});
`

$3

An effect that listens to the actions and updates the view state of the action.

List of effects:

- startLoading$ - upsert the view state of the action to LOADING.
- reset$ - resets many view state actions to IDLE.
- error$ - upsert many view state actions to ERROR.

reset$ and error$ effects reset or error multiple view states because one action can be used in many configuration and change the view state of multiple actions.

$3

A union type that represents the view state:

`typescript
export interface ViewIdle {
readonly type: ViewStatusEnum.IDLE;
}

export interface ViewLoading {
readonly type: ViewStatusEnum.LOADING;
}

export interface ViewLoaded {
readonly type: ViewStatusEnum.LOADED;
}

export interface ViewError {
readonly type: ViewStatusEnum.ERROR;
readonly error?: E;
}

export type ViewStatus = ViewIdle | ViewLoading | ViewLoaded | ViewError;
`

factory functions:

- idleViewStatus - returns the idle view status.
- loadingViewStatus - returns the loading view status.
- loadedViewStatus - returns the loaded view status.
- errorViewStatus - returns the error view status with an optional error payload.

$3

A structural directive that handles the view state of the component.

is compatible with the ComponentViewModel and ViewStatus interfaces.

Handles view status in the following way:

`typescript
private viewStatusHandlers: ViewStatusHandlers = {
[ViewStatusEnum.IDLE]: () => {
this.createContent();
},
[ViewStatusEnum.LOADING]: () => {
this.createSpinner();
},
[ViewStatusEnum.LOADED]: () => {
this.createContent();
},
[ViewStatusEnum.ERROR]: ({ viewStatus }) => {
this.createErrorState(viewStatus.error);
},
};
`

When using the AsyncPipe, the directive will render the spinner for the first time

`typescript
if (value == null) {
this.viewContainerRef.clear();
this.createSpinner();
return;
}
`

$3

A utility functions that provides a custom loading component for the ViewStateDirective directive.

`typescript
import { provideLoadingStateComponent } from 'ngx-view-state';

export const appConfig: ApplicationConfig = {
providers: [
// ...
provideLoadingStateComponent(LoadingComponent),
],
};
`

$3

A utility functions that provides a custom error component for the ViewStateDirective directive.

`typescript
import { provideErrorStateComponent } from 'ngx-view-state';

export const appConfig: ApplicationConfig = {
providers: [
// ...
provideErrorStateComponent(ErrorComponent),
],
};
`

$3

An interface to implement the error state component.

`typescript
@Component({
selector: 'ngx-error-state',
imports: [],
template:

{{ viewStateError || 'There is an error displaying this data' }}

A generic interface that represents the view model of the component. Is used to handle the view state of the HTTP request along with mapToViewModel rxjs operator function.

`typescript
import { ViewLoaded, ViewStatus } from './view-status.model';

export type ComponentViewModel =
| { data?: T; viewStatus: Exclude, ViewLoaded> }
| { data: T; viewStatus: ViewLoaded };
`

$3

A utility function that maps the response of an HTTP request to a ComponentViewModel interface.
Accepts an object with onSuccess and onError handlers.

`typescript
import { mapToViewModel } from 'ngx-view-state';

@Injectable()
export class TodosService {
constructor(private http: HttpClient) {}

loadTodos(): Observable> {
return this.http.get('https://jsonplaceholder.typicode.com/todos').pipe(mapToViewModel());
}
}
``