Skip to content

Latest commit

聽

History

History
96 lines (69 loc) 路 4.62 KB

image-directive-setup.md

File metadata and controls

96 lines (69 loc) 路 4.62 KB
Raw

Setting up NgOptimizedImage

This tutorial explains how to set up the NgOptimizedImage. For information on using NgOptimizedImage, see Getting Started with NgOptimizedImage.

Import NgOptimizedImage

You can import NgOptimizedImage from the @angular/common module. The directive is defined as a standalone directive, so components should import it directly.

Configure an ImageLoader

A "loader" is a function that generates the image transformation URL for a given image file. When appropriate, NgOptimizedImage sets the size, format, and image quality transformations for an image.

NgOptimizedImage provides a generic loader as well as loaders for various third-party image services; it also supports writing your own custom loader.

Loader type Behavior
Generic loader The URL returned by the generic loader will always match the value of src. In other words, this loader applies no transformations. Sites that use Angular to serve images are the primary intended use case for this loader.
Loaders for third-party image services The URL returned by the loaders for third-party image services will follow API conventions used by that particular image service.
Custom loaders A custom loader's behavior is defined by its developer. You should use a custom loader if your image service isn't supported by the loaders that come preconfigured with NgOptimizedImage.

Based on the image services commonly used with Angular applications, NgOptimizedImage provides loaders preconfigured to work with the following image services:

Image Service Angular API Documentation
Cloudflare Image Resizing provideCloudflareLoader Documentation
Cloudinary provideCloudinaryLoader Documentation
ImageKit provideImageKitLoader Documentation
Imgix provideImgixLoader Documentation

You must configure an image loader to use NgOptimizedImage.

These instructions explain how to set up an image loader for use with the NgOptimizedImage.

  1. Import the NgOptimizedImage directive into the application by adding it to the imports section of an NgModule or a standalone Component.
import { NgOptimizedImage } from '@angular/common'; // Include NgOptimizedImage in the appropriate NgModule @NgModule({ imports: [ // ... other imports NgOptimizedImage, ], })

class AppModule {}

@Component({ standalone: true, imports: [ // ... other imports NgOptimizedImage, ], })

class MyStandaloneComponent {}

  1. Configure a loader that you want to use.

To use the generic loader: no additional code changes are necessary.

To use an existing loader for a third-party image service: add the provider factory for your chosen service to the providers array. In the example below, the Imgix loader is used:

providers: [ provideImgixLoader('https://my.base.url/'), ],

The base URL for your image assets should be passed to the provider factory as an argument. For most sites, this base URL should match one of the following patterns:

You can learn more about the base URL structure in the docs of a corresponding CDN provider.

To use a custom loader: provide your loader function as a value for the IMAGE_LOADER DI token. In the example below, the custom loader function returns a URL starting with https://example.com that includes src and width as URL parameters.

providers: [ { provide: IMAGE_LOADER, useValue: (config: ImageLoaderConfig) => { return `https://example.com/images?src=${config.src}&width=${config.width}`; }, }, ],

A loader function for the NgOptimizedImage directive takes an object with the ImageLoaderConfig type (from @angular/common) as its argument and returns the absolute URL of the image asset. The ImageLoaderConfig object contains the srcand width properties.

Note: a custom loader must support requesting images at various widths in order for ngSrcset to work properly.