ngx-view-state is a library for managing the Loading/Success/Error states of views in Angular applications that use Ngrx or HttpClient
npm install ngx-view-stateThe ngx-view-state library is designed to simplify managing Loading/Success/Error states in Angular applications that use NgRx.
- Installation
- Usage with NgRx
- Usage ngxViewState directive
- Components customization
- Usage with HttpClient
- Key parts of the library
- Documentation
Run: npm install ngx-view-state
#### 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());
}
`
Import the ViewStateDirective in your component and pass the view state value to the directive.
`html`
// Render todos
Directive will then render the appropriate component based on the view state value.
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),
],
};
`
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
}
}
`
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`
// Render todos
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
mapToViewModel({
onSuccess: (data) => ({ viewStatus: loadedViewStatus(), data: data.map(...) }),
onError: (error) => ({ viewStatus: errorViewStatus('Failed to load todos') })
})
);
}
`
- createViewStateFeature (view-state.feature.ts) selectActionViewStatus
Factory that creates an NgRx feature to manage view states for actions.
Generates selectors such as and selectIsAnyActionLoading.ViewStateActions
- (view-state.actions.ts) ViewStateEffects
Defines actions for starting, resetting, or reporting errors in view states.
- (view-state.effects.ts) ViewStateActionsService
Listens for configured actions and dispatches view-state actions to update the store.
- – 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
- 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.
- Factory functions for constructing ViewStatus values (loadingViewStatus, errorViewStatus, etc.).mapToViewModel
-
Helper to transform HTTP responses into a typed view model used by the directive.
- Simple LoadingStateComponent and ErrorStateComponent are located in components/. provideLoadingStateComponent
You can supply custom components via the or provideErrorStateComponent tokens.
- createViewStateFeature
- Selectors
- ViewStateActions
- ViewStateEffects
- ViewStatus
- ViewStateDirective
- provideLoadingStateComponent
- provideErrorStateComponent
- ViewStateErrorProps
- ComponentViewModel
- mapToViewModel
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.
- 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.
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 }[] }>(),
},
});
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.
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
`
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.
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;
}
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),
],
};
`
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),
],
};
`
An interface to implement the error state component.
`typescript
@Component({
selector: 'ngx-error-state',
imports: [],
template:
,
changeDetection: ChangeDetectionStrategy.OnPush,
})
export class ErrorStateComponent implements ViewStateErrorComponent {
@Input() public viewStateError?: string;
}
`$3
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());
}
}
``