imagekitio-angular v5.0.0

ImageKit.io Angular SDK

ImageKit Angular SDK allows you to resize, optimize, deliver, and upload images and videos in your angular application.

ImageKit is complete media storage, optimization, and transformation solution that comes with an image and video CDN. It can be integrated with your existing infrastructure - storage like AWS S3, web servers, your CDN, and custom domain names, allowing you to deliver optimized images in minutes with minimal code changes.

Breaking changes

Upgrading from 3.x to 4.x version

1. Overlay syntax update

• In version 4.0.0, we've removed the old overlay syntax parameters for transformations, such as oi, ot, obg, and more. These parameters are deprecated and will start returning errors when used in URLs. Please migrate to the new layers syntax that supports overlay nesting, provides better positional control, and allows more transformations at the layer level. You can start with examples to learn quickly.
• You can migrate to the new layers syntax using the raw transformation parameter.

Upgrading from 2.x to 3.x version

3.x version has breaking changes as listed below.

• In version 3.0.0, we have deprecated the use of the authenticationEndpoint parameter. Instead, the SDK now introduces a new parameter named authenticator. This parameter expects an asynchronous function that resolves with an object containing the necessary security parameters i.e signature, token, and expire.

Example implementation for authenticator using Fetch API.

authenticator = async () => {
    try {

        // You can pass headers as well and later validate the request source in the backend, or you can use headers for any other use case.
        const headers = {
          'Authorization': 'Bearer your-access-token',
          'CustomHeader': 'CustomValue'
        };

        const response = await fetch('server_endpoint', {
            headers
        });

        if (!response.ok) {
            const errorText = await response.text();
            throw new Error(`Request failed with status ${response.status}: ${errorText}`);
        }

        const data = await response.json();
        const { signature, expire, token } = data;
        return { signature, expire, token };
    } catch (error) {
        throw new Error(`Authentication request failed: ${error.message}`);
    }
};

Note: Avoid generating security parameters on the client side. Always send a request to your backend to retrieve security parameters, as the generation of these parameters necessitates the use of your Imagekit privateKey, which must not be included in client-side code.

Version Support

Installation

npm install --save imagekitio-angular

or

yarn add imagekitio-angular

Support

For any feedback or to report any issues or general implementation support, please reach out to support@imagekit.io

Please note that this SDK version supports Angular version 9 and onwards. For older Angular versions, use v1.x.x.

Usage

Initialization

To use the SDK, you need to provide it with a few configuration parameters. The configuration parameters must be passed to the ImagekitioAngularModule module in your app.module.ts file. example:

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule,
    AppRoutingModule,
    ImagekitioAngularModule.forRoot({
      publicKey: environment.publicKey,
      urlEndpoint: environment.urlEndpoint,
    })
  ],
  providers: [],
  bootstrap: [AppComponent]
})

• urlEndpoint is required to use the SDK. You can get URL-endpoint from your ImageKit dashboard - https://imagekit.io/dashboard/url-endpoints.
• publicKey and authenticator parameters are required if you want to use the SDK for client-side file upload. You can get publicKey from the developer section in your ImageKit dashboard - https://imagekit.io/dashboard/developer/api-keys.
• transformationPosition is optional. The default value for the parameter is path. Acceptable values are path & query

Note: Do not include your private key in any client-side code.

Quick examples

// Render an image using a relative path - https://ik.imagekit.io/your_imagekit_id/default-image.jpg
<ik-image path="/default-image.jpg"></ik-image>

//  Overriding URL endpoint - https://www.custom-domain.com/default-image.jpg
<ik-image
  path="/default-image.jpg"
  urlEndpoint="https://www.custom-domain.com"
></ik-image>

// Render an image using an absolute URL and basic transformations- https://www1.custom-domain.com/default-image.jpg?tr=w-100,h-300
<ik-image
  src="https://www1.custom-domain.com/default-image.jpg" 
  [transformation]='[{
    "height": "300",
    "width": "100"
  }]'
></ik-image>

// Height and width manipulation - https://ik.imagekit.io/your_imagekit_id/tr:h-200,w-200/default-image.jpg
<ik-image 
  path="/default-image.jpg"
  [transformation]='[{
    "height": "200",
    "width": "200"
  }]'
></ik-image>

// Chained transformation - https://ik.imagekit.io/your_imagekit_id/tr:h-200,w-200:rt-90/default-image.jpg
<ik-image 
  path="/default-image.jpg"
  [transformation]='[{
      "height": "200",
      "width": "200"
    },
    {
      "rotation": "90"
    }]'
></ik-image>

// Lazy loading
<ik-image path="/default-image.jpg" loading="lazy"></ik-image>

/*
  Low-quality image placeholder
  Will first load https://ik.imagekit.io/your_imagekit_id/tr:h-200,w-200:q-20,bl-6/default-image.jpg, while the original image, i.e., https://ik.imagekit.io/your_imagekit_id/tr:h-200,w-200/default-image.jpg is being loaded in the background.
*/
<ik-image 
  path="default-image.jpg" 
  [transformation]='[{
    "height": "200",
    "width": "200"
    }]'
  [lqip]="{active:true, quality: 20, blur: 6}"
></ik-image>

// Low-quality image placeholder and lazy loading of original image in the background
<ik-image 
  path="default-image.jpg" 
  [lqip]="{active:true}"
  loading= "lazy"
></ik-image>

// Video element with basic transformation, reduced quality by 50% using q:50
<ik-video 
  path="default-video.mp4" 
  [transformation]='[{
    "quality": "50"
  }]'
></ik-video>

// File upload with optional custom event handling
// See section "ik-upload" in README for more info
<ik-upload 
  fileName= "test.jpg" 
  (onError)="handleUploadError($event)"
  (onSuccess)="handleUploadSuccess($event)"
  [tags]='["sample-tag1", "sample-tag2"]'
  customCoordinates="10,10,10,10"
  [isPrivateFile]="false"
  [responseFields]='["tags"]'
  folder="/sample-folder"
  [validateFile]="validateFileFunction"
  [onUploadStart]="onUploadStartFunction"
  [onUploadProgress]="onUploadProgressFunction"
  [authenticator]="authenticator"
  [transformation]="{
    'pre': 'l-text,i-Imagekit,fs-50,l-end', 
    'post': [
        {
            'type': 'transformation', 
            'value': 'w-100'
        }
    ]
  }"
></ik-upload>

Demo application

• The official step-by-step Angular quick start guide - https://docs.imagekit.io/getting-started/quickstart-guides/angular

Components

The library includes three components:

• ik-image for image resizing. This renders a <img> tag.
• ik-video for video resizing. This renders a <video> tag.
• ik-upload for client-side file uploading. This renders a <input type= "file"> tag.

You can also access the underlying ImageKit javascript SDK. See here for more details.

Note: URL endpoints of each component can be overridden explicitly. See here for more details

ik-image

The ik-image component renders an img tag. It is used for rendering and manipulating images in real-time. ik-image component accepts the following props:

Basic resizing examples

The transformation prop is an array of objects. Each object can have the following properties. When you specify more than one object, each object is added as a chained transformation. For example:

// The following resizes the image to 300x300px 
flexibleTransformationOne: Array<Transformation> = [{
  height: "300",
  width: "300"
}];

Sample usage of ik-image component:

// Loading image with no transformation
<ik-image
  path="/default-image.jpg"
  urlEndpoint="https://ik.imagekit.io/your_imagekit_id/"
  >
</ik-image>

// Loading image with transformation
<ik-image
  path="/default-image.jpg"
  urlEndpoint="https://ik.imagekit.io/your_imagekit_id/"
  [transformation]="flexibleTransformationOne"
  >
</ik-image>

See the complete list of transformations supported in ImageKit here. The SDK gives a name to each transformation parameter e.g. height for h and width for w parameter. It makes your code more readable. If the property does not match any of the following supported options, it is added as it is in the URL.

Adding overlays

ImageKit.io enables you to apply overlays to images and videos using the raw parameter with the concept of layers. The raw parameter facilitates incorporating transformations directly in the URL. A layer is a distinct type of transformation that allows you to define an asset to serve as an overlay, along with its positioning and additional transformations.

Text as overlays

You can add any text string over a base video or image using a text layer (l-text).

For example:

<ik-image
    path="/default-image.jpg"
    [transformation]='[{ "width": 400, "height": 300, "raw": "l-text,i-Imagekit,fs-50,l-end" }]'>
</ik-image>

Sample Result URL

https://ik.imagekit.io/your_imagekit_id/tr:h-300,w-400,l-text,i-Imagekit,fs-50,l-end/default-image.jpg

Image as overlays

You can add an image over a base video or image using an image layer (l-image).

For example:

<ik-image
    path="/default-image.jpg"
    [transformation]='[{ "width": 400, "height": 300, "raw": "l-image,i-default-image.jpg,w-100,b-10_CDDC39,l-end" }]'>
</ik-image>

Sample Result URL

https://ik.imagekit.io/your_imagekit_id/tr:h-300,w-400,l-image,i-default-image.jpg,w-100,b-10_CDDC39,l-end/default-image.jpg

Solid color blocks as overlays

You can add solid color blocks over a base video or image using an image layer (l-image).

For example:

<ik-video
    path="/img/sample-video.mp4"
    [transformation]='[{ "width": 400, "height": 300, "raw": "l-image,i-ik_canvas,bg-FF0000,w-300,h-100,l-end" }]'>
</ik-video>

Sample Result URL

https://ik.imagekit.io/your_imagekit_id/tr:h-300,w-400,l-image,i-ik_canvas,bg-FF0000,w-300,h-100,l-end/img/sample-video.mp4

List of supported transformations

Chained Transforms

Chained transformations provide a simple way to control the sequence in which transformations are applied.

// Using chained transformation. First, resize and then rotate the image to 90 degrees.
<ik-image 
  path="/default-image.jpg"
  [transformation]='[{
      "height": "200",
      "width": "200"
    },
    {
      "rotation": "90"
    }]'
  >
</ik-image>

In the above case, the rotation will be performed first, and resizing according to width and aspect ratio will be performed afterward.

Lazy loading images

You can lazy load images using loading= "lazy```. When you useloading= "lazy`, all images that are immediately viewable without scrolling load normally. Those far below the device viewport are only fetched when the user scrolls near them.

The SDK uses a fixed threshold based on the effective connection type to ensure that images are loaded early enough so that they have finished loading once the user scrolls near to them.

On fast connections (e.g 4G), the value of threshold is 1250px and on slower connections (e.g 3G), it is 2500px.

You should always set the height and width of the image element to avoid layout shift when lazy-loading images.

Example usage:

// Lazy loading images
<ik-image
    path="/default-image.jpg"
    [transformation]='[{
      "height": "300",
      "width": "400"
    }]'
    loading= "lazy"
    height= "300"
    width= "400"
    >
</ik-image>

Low-quality image placeholders (LQIP)

To improve user experience, you can use a low-quality blurred variant of the original image as a placeholder while the original image is being loaded in the background. Once the original image is loaded, the placeholder is replaced with the original image.

<ik-image 
  path="/default-image.jpg"
  [lqip]="{active:true}"
  >
</ik-image>

By default, the SDK uses the quality:20 and blur:6. You can change this. For example:

<ik-image 
  path="/default-image.jpg"
  [lqip]="{active:true, quality: 40, blur: 5}"
  >
</ik-image>

You can also specify a raw transformation if you want more control over the URL of the low-quality image placeholder. The SDK ignores quality and blur parameters in this case.

<ik-image
  path="/default-image.jpg"
  [lqip]='{active:true, raw: "n-lqip_named_transformation"}'
  >
</ik-image>

Combining lazy loading with low-quality placeholders

You can lazy-load the original image only when the user scrolls near them. Until then, only a low-quality placeholder is loaded. This saves a lot of network bandwidth if the user never scrolls further down.

// Loading a blurred low-quality image placeholder and lazy-loading original when the user scrolls near them
<ik-image
    path="/default-image.jpg"
    loading= "lazy"
    [lqip]="{ active: true, quality: 20, blur: 30 }"
  >
</ik-image>

Arithmetic expressions in transformations

ImageKit allows use of arithmetic expressions in certain dimension and position-related parameters, making media transformations more flexible and dynamic.

For example:

<ik-image
    path="/default-image.jpg"
    loading= "lazy"
    [transformation]='[{
        "height": "ih_div_2",
        "width": "iw_div_4",
        "border": "cw_mul_0.05_yellow"
    }]'
  >
</ik-image>

Sample Result URL

https://ik.imagekit.io/your_imagekit_id/default-image.jpg?tr=w-iw_div_4,h-ih_div_2,b-cw_mul_0.05_yellow

ik-video

The ik-video component renders a video tag. It is used for rendering and manipulating videos in real time. ik-video component accepts the following props:

Basic video resizing examples

// Video from related file path with no transformations - https://ik.imagekit.io/your_imagekit_id/sample-video.mp4
<ik-video
  path="/sample-video.mp4"
></ik-video>

// Video resizing - https://ik.imagekit.io/your_imagekit_id/tr:w-h-300,w-400/sample-video.mp4
<ik-video
  path="/sample-video.mp4"
  [transformation]='[{
    "height": "300",
    "width": "400"
  }]'
></ik-video>

// Loading video from an absolute file path with no transformations - https://www.custom-domain.com/default-video.mp4
<ik-video
  src="https://www.custom-domain.com/default-video.mp4"
></ik-video>

// Using a new transformation parameter that is not there in this SDK yet - https://ik.imagekit.io/your_imagekit_id/tr:custom-value/sample-video.mp4
<ik-video
  path="/sample-video.mp4"
  [transformation]='[{
    "custom": "value"
  }]'
></ik-video>

ik-upload

The SDK provides a component to upload files to the ImageKit Media Library.

ik-upload component accepts all the parameters supported by the ImageKit Upload API as attributes e.g. tags, useUniqueFileName, folder, isPrivateFile, customCoordinates etc.

Note: urlEndpoint and publicKey must be present in the attribute for them to take effect. Otherwise, the SDK will fall back to the values specified in app.module.ts.

Sample usage

// Added to app.component.ts
validateFileFunction(res: File) {
    console.log('validating')
    if(res.size < 1000000){ // Less than 1mb file size
      return true;
    }
    return false;
  }
  
  onUploadStartFunction(res: Event) {
    console.log('onUploadStart')
  }
  
  onUploadProgressFunction(res: ProgressEvent) {
    console.log('progressing')
  }
  
  handleUploadError = (event: any) => {
    console.log('Error');
    console.log(event);
  };
  
  handleUploadSuccess = (event: any) => {
    console.log('Success');
    console.log(event.$ResponseMetadata.statusCode); // 200
    console.log(event.$ResponseMetadata.headers); // headers
    console.log(event);
  };

// Added to app.component.html
<ik-upload 
    fileName= "test.jpg" 
    (onError)="handleUploadError($event)"
    (onSuccess)="handleUploadSuccess($event)"
    [validateFile]="validateFileFunction"
    [onUploadStart]="onUploadStartFunction"
    [onUploadProgress]="onUploadProgressFunction"
    [transformation]="{
      'pre': 'l-text,i-Imagekit,fs-50,l-end', 
      'post': [
          {
              'type': 'transformation', 
              'value': 'w-100'
          }
      ]
    }"
    >
  </ik-upload>

Custom button example, using buttonRef

// Set the [buttonRef] attribute
<ik-upload 
    fileName= "test.jpg" 
    (onError)="handleUploadError($event)"
    (onSuccess)="handleUploadSuccess($event)"
    [validateFile]="validateFileFunction"
    [onUploadStart]="onUploadStartFunction"
    [onUploadProgress]="onUploadProgressFunction"
    [buttonRef]="myBtn"
    [transformation]="{
      'pre': 'l-text,i-Imagekit,fs-50,l-end', 
      'post': [
          {
              'type': 'transformation', 
              'value': 'w-100'
          }
      ]
    }"
    >
  </ik-upload>

// Make sure to add the reference name using #
<button #myBtn type="button" style="color:blue">
  <span>Upload</span>
</button>

Abort upload

// Added to app.component.ts
@ViewChild('upload') uploadComponent:IkUploadComponent;// @ViewChild can be used to get instance of IKUpload component.

onAbortFunction(){
    this.uploadComponent && this.uploadComponent.abort();
}

// Added to app.component.html
<ik-upload 
  #upload
  fileName= "test.jpg" 
  (onError)="handleUploadError($event)"
  (onSuccess)="handleUploadSuccess($event)"
  [validateFile]="validateFileFunction"
  [onUploadStart]="onUploadStartFunction"
  [onUploadProgress]="onUploadProgressFunction"
  [authenticator]="authenticator"
  [transformation]="{
    'pre': 'l-text,i-Imagekit,fs-50,l-end', 
    'post': [
        {
            'type': 'transformation', 
            'value': 'w-100'
        }
    ]
  }"
></ik-upload>
<button 
  (click)="onAbortFunction()"
>Abort</button>

Accessing Imagekit core JS SDK

Sample usage

import { ImagekitService } from 'imagekitio-angular';
...
// Initializing the service with configuration
service = new ImagekitService({
  urlEndpoint: "https://ik.imagekit.io/your_imagekit_id/endpoint/",
  publicKey: "your_public_key",
});

// Generating URL
// Note: You can choose to override the publicKey if necessary
const url = this.service.ikInstance.url({
  path: "/default-image.jpg",
  urlEndpoint: "https://ik.imagekit.io/your_imagekit_id/endpoint/",
  publicKey: "your_overriding_public_key_if_needed",
});

Overriding urlEndpoint

You can use the urlEndpoint property in a component to change url for it.

Here is an example where the ik-image component's URL endpoint can be explicitly set:

<ik-image
  path="/path-to-my-image"
  urlEndpoint="https://images.custom-domain.com"
></ik-image>

Links

• Documentation
• Main website

License

Released under the MIT license.