Angular frontend framework (Beta)

Important
The Angular frontend framework library is currently in BETA. There may be minor changes to parameter names or other implementation details before the general access release. We invite you to try it out. We would appreciate any feedback via our support team.

  • Video rendering is not supported in this release.

Quick start

If you're ready to get coding, jump straight to our Quickstart guide. Otherwise, keep reading to get a more in-depth understanding of the Angular frontend framework library.

Overview

Cloudinary's Angular frontend framework library provides image rendering capabilities and plugins that you can implement using code that integrates seamlessly with your existing Angular application.

Related topics
This guide relates to the latest released version of the Cloudinary Angular library, released from the frontend-frameworks GitHub repository.

For details on all new features and fixes from previous versions, see the CHANGELOG.

Getting started with Angular

The Angular frontend framework library must be used in conjunction with the Cloudinary JavaScript SDK v2 Base library to provide all of Cloudinary's transformation and optimization functionality.

Installation

Install both the JavaScript SDK v2 Base and Angular packages using the NPM package manager:

Copy to clipboard
npm install --save @cloudinary/base
npm install --save @cloudinary/angular

Configuration

You can specify the configuration parameters that are used to create the delivery URLs, either using a Cloudinary instance or per image/video.

Note
Specify the configuration parameters in camelCase, for example cloudName.

Cloudinary instance configuration

If you want to use the same configuration to deliver all your media assets, it's best to set up the configuration through a Cloudinary instance, for example:

Copy to clipboard
// In your app.module.ts inject the library:
import {CloudinaryModule} from '@cloudinary/angular';

imports: [
  ...,
  CloudinaryModule,
],
...

// In your component.ts use `@cloudinary/base` to set your configuration.

import {Cloudinary, CloudinaryImage} from "@cloudinary/base";

export class AppComponent {
  img: CloudinaryImage;

  ngOnInit() {

    // Create a Cloudinary instance, setting some Cloud and URL configuration parameters.
    const cld = new Cloudinary({
      cloud: {
        cloudName: 'demo'
      }
    });

    // cld.image returns a CloudinaryImage with the configuration set.
    this.img = cld.image('sample');

    // The URL of the image is: https://res.cloudinary.com/demo/image/upload/sample
  }
}

// In your view add the advanced-image component and pass your Cloudinary image.
<advanced-image [cldImg]="img"></advanced-image>

You can set other configuration parameters related to your cloud and URL as required, for example, if you have your own custom domain name, and want to generate a secure URL (HTTPS):

Copy to clipboard
// Create a Cloudinary instance, setting some Cloud and URL configuration parameters.
const cld = new Cloudinary({
  cloud: {
    cloudName: 'demo'
  },
  url: {
    secureDistribution: 'www.example.com', 
    secure: true 
  }
});

// This creates a URL of the form: http://www.example.com/demo/image/upload/sample

Asset instance configuration

If you need to specify different configurations to deliver your media assets, you can specify the configuration per image/video instance, for example:

Copy to clipboard
// In your app.module.ts inject the library:
import {CloudinaryModule} from '@cloudinary/angular';

imports: [
  ...,
  CloudinaryModule,
],
...

// In your component.ts use `@cloudinary/base` to set your configuration.

import {CloudinaryImage} from "@cloudinary/base/assets/CloudinaryImage";
import URLConfig from "@cloudinary/base/config/URLConfig";
import CloudConfig from "@cloudinary/base/config/CloudConfig";

export class AppComponent {
  img: CloudinaryImage;

  ngOnInit() {

    // Set the Cloud configuration and URL configuration
    const cloudConfig = new CloudConfig({cloudName: 'demo'});
    const urlConfig = new URLConfig({secure: true});

    // Instantiate and configure a CloudinaryImage object.
    this.img = new CloudinaryImage('sample', cloudConfig, urlConfig);

    // The URL of the image is: https://res.cloudinary.com/demo/image/upload/sample
  }
}

// In your view add the advanced-image component and pass your Cloudinary image.
<advanced-image [cldImg]="img"></advanced-image>

Transformations

To transform a media asset, use the cloudinary-js-base library to create the transformation, then pass the transformed image or video object to the cldImg attribute in your advanced-image component to render the media on your site. For example:

Copy to clipboard
// In your app.module.ts inject the library:
import {CloudinaryModule} from '@cloudinary/angular';

imports: [
  ...,
  CloudinaryModule,
],
...

// In your component.ts use `@cloudinary/base` to generate your transformations.

import {Cloudinary, CloudinaryImage} from "@cloudinary/base";
import {Transformation} from "@cloudinary/base";

// Import required actions.
import {thumbnail} from "@cloudinary/base/actions/resize";
import {byRadius} from "@cloudinary/base/actions/roundCorners";

// Import required qualifiers.
import {face} from "@cloudinary/base/qualifiers/focusOn";
import {focusOn} from "@cloudinary/base/qualifiers/gravity";

export class AppComponent {
  img: CloudinaryImage;

  ngOnInit() {

    // Create and configure your Cloudinary instance.
    const cld = new Cloudinary({
      cloud: {
        cloudName: 'demo'
      }
    }); 

    // Use the image with public ID, 'front_face'.
    this.img = cld.image('front_face');

    // Apply the transformation.
    this.img
    .resize(thumbnail().width(150).height(150).gravity(focusOn(face())))  // Crop the image, focusing on the face.
    .roundCorners(byRadius(20));    // Round the corners.
  }
}

// In your view add the advanced-image component and pass your Cloudinary image.
<advanced-image [cldImg]="img"></advanced-image>

Here, the front_face image is cropped to a 150 x 150 pixel thumbnail with rounded corners, focusing on the face, resulting in this URL:

Transformed face

To find out more about transforming your assets using the JavaScript SDK v2, see:

Plugins

The Cloudinary Angular library provides plugins to render the media on your site in the most optimal way and improve your user's experience:

  • Lazy Loading to delay loading images if they are not yet visible on the screen.
  • Responsive images to resize your images automatically based on the viewport size.
  • Image accessibility to make your images more accessible to your users with visual disabilities.
  • Image placeholders to display a lightweight version of an image while the target image is downloading.

Both lazy loading and image placeholders are great techniques for helping to optimize your page load times and, in turn, improve your metrics related to Core Web Vitals.

In this example, the responsive and accessibility plugins are applied:

Copy to clipboard
// In your app.module.ts inject the library:
import {CloudinaryModule} from '@cloudinary/angular';

imports: [
  ...,
  CloudinaryModule,
],
...

// In your component.ts use `@cloudinary/base` to generate your transformations.
import {Cloudinary, CloudinaryImage} from "@cloudinary/base";

// Import the plugins you wish to use.
import {
  accessibility,
  responsive,
  lazyload,
  placeholder
} from '@cloudinary/angular';

export class AppComponent {
  img: CloudinaryImage;

   // Use the responsive and accessibility plugins
  plugins = [responsive(), accessibility()]

  ngOnInit() {

    // Create and configure your Cloudinary instance.
    const cld = new Cloudinary({
      cloud: {
        cloudName: 'demo'
      }
    }); 

    // Use the image with public ID, 'front_face'.
    this.img = cld.image('sample');  
  }
}

// In your view add the advanced-image component and pass your Cloudinary image and plugins.
<advanced-image [cldImg]="img" [plugins]="plugins"></advanced-image>

Plugin order

We recommend the following order when using our plugins to achieve the best results (omitting any you don't need):

Copy to clipboard
plugins = [lazyload(), responsive(), accessibility(), placeholder()]

Lazy loading

Lazy loading tells the browser not to download images that are not yet visible on the user's screen, and wait until the user scrolls to that image. This feature can potentially save bandwidth for images that are not actually viewed, and decrease the time needed to load a page.

To enable the lazy loading feature for a particular image, use the lazyload() plugin. It accepts two arguments:

Argument Type Description
rootMargin string The margin applied to the root element's bounding box at which the intersection test is performed. The root element identifies the viewport for the image. Use syntax similar to the CSS margin property.

Default: 0px.

threshold float The percentage of the image's visibility at which point the image should load.

Range: 0.0 to 1.0. Default: 0.1 (10%).

Example: Set root margin and threshold

Load an image when 25% of it is visible. Specify a bounding box around the root element with margins, top: 10px, right: 20px, bottom: 10px, left: 30px:

Copy to clipboard
plugins = [lazyload('10px 20px 10px 30px', 0.25)]

Responsive images

You can make your images responsive, so that they automatically resize based on the viewport size, using the responsive() plugin. It accepts one argument:

Argument Type Description
steps integer | array Specify either:

  • The step size in pixels.
  • A set of image sizes in pixels.
Default: 100.

Example 1: Set step size

Set the step size to 200 pixels:

Copy to clipboard
plugins = [responsive(200)]

Example 2: Specify a set of image sizes to use

Specify a set of image sizes (800, 1000 and 1400 pixels):

Copy to clipboard
plugins = [responsive([800, 1000, 1400])]

Image accessibility

The image accessibility feature makes an image more accessible to users that may have a visual disability that impairs their ability to view images.

To enable the accessibility feature for a particular image, use the accessibility() plugin. It accepts one argument:

Argument Type Description
mode constant The accessibility mode to use.

Possible values:

  • monochrome: Reduces the image to only use one color.
  • darkmode: Adds a dark tinting effect to the image.
  • brightmode: Adds a bright tinting effect to the image.
  • colorblind: Adds an effect to differentiate between colors that are similar.
Default: darkmode.

Example: Apply an accessibility transformation

Help color blind users by using the colorblind mode:

Copy to clipboard
plugins = [accessibility('colorblind')]

Image placeholders

An image placeholder is a lightweight version of a target image that can be downloaded quickly, and will occupy the same location as the intended target image, while the target image is still downloading. Once the target image download has been completed the placeholder is replaced with the final image. This feature is especially useful together with large images.

Placeholder images offer the following features:

  • The page loads quickly without blank locations.
  • No page content 'jumping' as the elements dynamically adjust to add downloaded images.

To add a placeholder for a particular image, use the placeholder() plugin. It accepts one argument:

Argument Type Description
mode constant The placeholder mode to use.

Possible values:

  • vectorize: A low quality, vectorized version of the target image.
  • pixelate: A low quality, pixelated version of the target image.
  • blur: A low quality, vectorized version of the target image.
  • predominant-color: A solid, single color image - the predominant color in the target image.
Default: vectorize.

Example 1: Apply a placeholder transformation

Use a blurred placeholder image while waiting for the full quality image to download:

Copy to clipboard
plugins = [placeholder('blur')]

Example 2: Combine lazy loading with a placeholder

You can also combine placeholder images with the lazy loading feature. In this case, when the user scrolls to the image location, the placeholder image is downloaded followed by the target image.

For example, to use a solid, single-color placeholder image and the lazy loading feature:

Copy to clipboard
plugins = [lazyload(), placeholder('predominant-color')]

Sample projects

View these sample projects for complete code examples:

✔️ Feedback sent!

Rate this page: