CASL Angular

This package allows to integrate @casl/ability with Angular application. It provides deprecated AblePipe, AblePurePipe and new AbilityService and AbilityServiceSignal to Angular templates, so you can show or hide components, buttons, etc based on user ability to see them.

Installation

npm install @casl/angular @casl/ability
# or
yarn add @casl/angular @casl/ability
# or
pnpm add @casl/angular @casl/ability

Configure AppModule

To add pipes into your application's templates, you need to import the one you need

import { NgModule } from '@angular/core';
import { AblePipe } from '@casl/angular';
import { createMongoAbility, Ability } from '@casl/ability';

@NgModule({
  imports: [
    // other modules
    AblePipe
  ],
  providers: [
    { provide: Ability, useValue: createMongoAbility() }
  ]
  // other properties
})
export class AppModule {}

Read CASL and TypeScript to get more details about MongoAbility type configuration.

Update Ability instance

Majority of applications that need permission checking support have something like AuthService or LoginService or Session service (name it as you wish) which is responsible for user login/logout functionality. Whenever user login (and logout), we need to update Ability instance with new rules.

Let's imagine that server returns user with a role on login:

import { Ability, AbilityBuilder } from '@casl/ability';
import { Injectable } from '@angular/core';

@Injectable({ provideIn: 'root' })
export class Session {
  #token: string

  constructor(@Inject(Ability) private ability: MongoAbility) {}

  login(details) {
    const params = { method: 'POST', body: JSON.stringify(details) };
    return fetch('path/to/api/login', params)
      .then(response => response.json())
      .then((session) => {
        this.updateAbility(session.user);
        this.#token = session.token;
      });
  }

  private updateAbility(user) {
    const { can, rules } = new AbilityBuilder(createMongoAbility);

    if (user.role === 'admin') {
      can('manage', 'all');
    } else {
      can('read', 'all');
    }

    this.ability.update(rules);
  }

  logout() {
    this.#token = null;
    this.ability.update([]);
  }
}

See Define rules to get more information of how to define Ability.

Then use this Session service in LoginComponent:

import { Component } from '@angular/core';
import { Session } from '../services/Session';

@Component({
  selector: 'login-form',
  template: `
    <form (ngSubmit)="login()">
      <input type="email" [(ngModel)]="email" />
      <input type="password" [(ngModel)]="password" />
      <button type="submit">Login</button>
    </form>
  `
})
export class LoginForm {
  email: string;
  password: string;

  constructor(private session: Session) {}

  login() {
    const { email, password } = this;
    return this.session.login({ email, password });
  }
}

Check permissions in templates using AbilityService

AbilityService is a service that provides ability$ observable. This observable injects provided in DI Ability instance and emits it each time its rules are changed. This allows efficiently use permissions checks, especially in case we use ChangeDetectionStrategy.OnPush.

Let's first see how it can be used in any component:

@Component({
  selector: 'my-home',
  template: `
    @if (ability$ | async as ability) {
      <h1>Home Page</h1>
      @if (ability.can('create', 'Post')) {
        <button>Create Post</button>
      }
    }
  `
})
export class HomeComponent {
  readonly ability$: Observable<AppAbility>;

  constructor(abilityService: AbilityService<AppAbility>) {
    this.ability$ = abilityService.ability$;
  }
}

It also can be safely used inside *ngFor and other directives. If we use ChangeDetectionStrategy.OnPush, it will give us additional performance improvements because ability.can(...) won't be called without a need.

This approach works good from performance point of view because it creates only single subscription per component (not per check as in case of ablePure pipe) and doesn't require our component to use Default or OnPush strategy.

But let's also see how we can do permission checks using pipes and what are performance implications of that:

Signals support

The latest version of @casl/angular also supports new signal. To utilize it in your app, instead of AbilityService use AbilityServiceSignal:

import { AbilityServiceSignal } from '@casl/angular';
import { AppAbility } from './AppAbility';

@Component({
  selector: 'my-home',
  template: `
      <h1>Home Page</h1>
      @if (can('create', 'Post')) {
        <button>Create Post</button>
      }
  `
})
export class HomeComponent {
  private readonly abilityService = inject<AbilityServiceSignal<AppAbility>>(AbilityServiceSignal);
  protected readonly can = this.abilityService.can;
}

Explain permission checks with whyCan and whyCannot

AbilityServiceSignal whyCan and whyCannot methods help to answer the question of why action is allowed or defined:

const abilityService = inject<AbilityServiceSignal<AppAbility>>(AbilityServiceSignal);

abilityService.update([
  { action: 'create', subject: 'Post', reason: 'You can create posts' },
  {
    inverted: true,
    action: 'delete',
    subject: 'Post',
    reason: 'Only administrators can delete posts'
  }
]);

abilityService.whyCan('create', 'Post'); // { reason: 'You can create posts' }
abilityService.whyCan('delete', 'Post'); // null
abilityService.whyCannot('delete', 'Post'); // { reason: 'Only administrators can delete posts' }
abilityService.whyCan('update', 'Post'); // null
abilityService.whyCannot('update', 'Post'); // { reason: undefined }
abilityService.whyCannot('create', 'Post'); // null

Expose these methods to templates the same way as can and use them like this:

@if (whyCannot('delete', 'Post'); as forbidden) {
  <span>{{ forbidden.reason || 'You cannot delete posts' }}</span>
} @else {
  <button (click)="deletePost()">Delete Post</button>
}

A matching inverted rule without a reason returns an object with reason: undefined when the method's condition is met. This keeps a denial truthy even when no explanation is available.

Create permission signals with defer* methods

The defer* methods return computed signals. Each argument (action, subject, or optional field) can be a plain value or a signal. The returned signal recalculates when the ability's rules or any signal argument changes.

Create these signals once, for example in component field initializers, and read them in the template:

import { Component, inject, input } from '@angular/core';
import { AbilityServiceSignal } from '@casl/angular';
import type { AppAbility } from './AppAbility';

@Component({
  selector: 'post-action',
  template: `
    @if (whyCannotPerformAction(); as forbidden) {
      <p>{{ forbidden.reason || 'This action is forbidden' }}</p>
    } @else {
      <button>Perform action</button>
    }
  `
})
export class PostActionComponent {
  private readonly abilityService = inject<AbilityServiceSignal<AppAbility>>(AbilityServiceSignal);
  readonly action = input.required<'create' | 'delete'>();

  protected readonly whyCannotPerformAction = this.abilityService.deferWhyCannot(this.action, 'Post');
}

The parent supplies the action, for example <post-action [action]="'delete'" />. The permission signal updates whenever that input changes.

Pass the signal itself (this.action) to track its changes. Passing its current value (this.action()) fixes that argument to the value it had when the deferred check was created. The deferWhy* methods preserve the null and missing-reason behavior of why* methods; use deferCan or deferCannot when you only need a boolean permission check.

Check permissions in templates using pipe (deprecated)

To check permissions in any template you can use AblePipe:

@if ('create' | able: 'Post') {
  <a (click)="createPost()">Add Post</a>
}

TypeScript support

This package is written in TypeScript, so it will warn you about wrong usage.

It may be a bit tedious to use application specific abilities in Angular app because everywhere you inject Ability instance you will need to import its generic parameters:

import { Ability } from '@casl/ability';
import { Component } from '@angular/core';
import { AppAbilities } from '../services/AppAbility';

@Component({
  selector: 'todo-item'
})
export class TodoItem {
  constructor(
    private ability: Ability<AppAbilities>
  ) {}
}

To make the life easier, you can use AbilityClass<TAbility> class to utilize Companion object pattern:

import { Ability, AbilityClass } from '@casl/ability';

type Actions = 'create' | 'read' | 'update' | 'delete';
type Subjects = 'Article' | 'User';

export type AppAbility = MongoAbility<[Actions, Subjects]>;
export const AppAbility = Ability as AbilityClass<AppAbility>;

And use AppAbility everywhere in your app:

import { NgModule } from '@angular/core';
import { AppAbility } from './services/AppAbility';

@NgModule({
  // other configuration
  providers: [
    { provide: AppAbility, useValue: createMongoAbility() },
  ]
})
export class AppModule {}

Want to help?

Want to file a bug, contribute some code, or improve documentation? Excellent! Read up on guidelines for contributing.

If you'd like to help us sustain our community and project, consider to become a financial contributor on Open Collective

See Support CASL for details

License

MIT License