# Angular ImageKit SDK

Real-time image & video resizing, automatic optimization, responsive images, and file uploading in Angular using ImageKit.io.

The Angular ImageKit SDK is a wrapper built on top of the ImageKit JavaScript SDK. It seamlessly integrates ImageKit's URL generation, image and video optimization, responsive image handling, and file upload capabilities into Angular applications.

The SDK is lightweight and has first-class TypeScript support. It works with Angular 14+ (standalone components and directives). You can view the [source code](https://github.com/imagekit-developer/imagekit-angular) on Github.

## Installation and Setup

Install the Angular SDK via npm or yarn:

```bash
npm install @imagekit/angular
# or
yarn add @imagekit/angular
```

The SDK supports both server-side rendering (SSR) and client-side rendering (CSR), so it can be added to any Angular project.

This Angular SDK exports `IKImageDirective` and `IKVideoDirective` directives. These directives can be applied to native `<img>` and `<video>` elements to add ImageKit's optimization and transformation capabilities. They automatically handle URL generation, lazy loading, responsive images, and transformations while preserving all native HTML attributes.

## Modern Angular (14+) - Standalone Directives

For Angular 14 and above, you can import standalone directives directly:

```js
import { Component } from '@angular/core';
import { IKImageDirective, provideImageKit } from '@imagekit/angular';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [IKImageDirective],
  template: `
    <img
      ikSrc="/profile.png"
      [width]="500"
      [height]="500"
      alt="Picture of the author"
    />
  `
})
export class AppComponent {}
```

Configure the SDK globally using `provideImageKit()` in your application config:

```js
import { ApplicationConfig } from '@angular/core';
import { provideImageKit } from '@imagekit/angular';

export const appConfig: ApplicationConfig = {
  providers: [
    provideImageKit({
      urlEndpoint: 'https://ik.imagekit.io/your_imagekit_id',
    })
  ]
};
```

Besides `IKImageDirective` and `IKVideoDirective`, the SDK also provides utility functions and error classes that can be used independently of the components.

## Utility functions

- [`buildSrc`](/content/docs/integration/javascript#buildsrc-parameters/index.html) – Generates URLs for images and videos based on your URL endpoint and transformation parameters.
- [`buildTransformationString`](/content/docs/integration/javascript#buildtransformationstring-parameters/index.html) – Converts array of transformation objects into a URL query string.
- [`upload`](/content/docs/integration/javascript#upload-parameters/index.html) – Facilitates file uploads to ImageKit with built-in support for common error handling, progress tracking, and abort functionality.
- [`getResponsiveImageAttributes`](/content/docs/integration/javascript#getresponsiveimageattributes-parameters/index.html) – Generates responsive image attributes that can be used on raw HTML image elements. This SDK however handles this automatically for you when using the `IKImageDirective` component with `[responsive]="true"`.

Refer to linked documentation for detailed usage of these utility functions.

## Error classes for upload error handling

- `ImageKitInvalidRequestError` - For invalid requests.
- `ImageKitAbortError` - For aborted uploads.
- `ImageKitUploadNetworkError` - For network errors during upload.
- `ImageKitServerError` - For server-side errors.

## Image Directive

The `IKImageDirective` is applied to native HTML `<img>` elements using the `ikSrc` attribute. It enhances the image element with ImageKit's URL generation, transformations, lazy-loading, and responsive image capabilities.

**Important:** The directive selector is `img[ikSrc]`, meaning you must use `ikSrc` instead of the standard `src` attribute.

It preserves all HTML img attributes and additionally accepts the following ImageKit-specific inputs:

| Parameter | Description and Example |
| --- | --- |
| **urlEndpoint** | The base URL endpoint from your [ImageKit dashboard](/content/dashboard/url-endpoints/index.html). To avoid passing this input in every component, you can configure it globally using `provideImageKit()`. If you pass it in the component, it will override the global value.<br>Example: `https://ik.imagekit.io/your_imagekit_id`. |
| **ikSrc**<br>(Required) | A relative or absolute path to the image. This replaces the standard `src` attribute when using the directive.<br>- If a **relative path** is provided, it is appended to the `urlEndpoint`.<br>- If an **absolute path** is provided, it is used as-is and the `urlEndpoint` is ignored.<br>- **Do not include query parameters** directly in `ikSrc`. Use the `queryParameters` input instead.<br>- **When using a web proxy**, you can pass the full image URL and prepend it with a `/`. For example - `/https://example.com/image.jpg`.<br>**Examples:**<br>Relative - `ikSrc="/default-image.jpg"`<br>Absolute - `ikSrc="https://example.com/image.jpg"`<br>Web Proxy - `ikSrc="/https://example.com/image.jpg"` |
| **width** | The width of the image in pixels (in numbers). This is used to calculate the srcSet attribute and is only utilized when sizes is not provided. The prop is set on the `<img>` element as it is. If provided value is not a number, then `srcset` is generated using the full list of device breakpoints<br>Example: `[width]="300"` |
| **transformation** | An array of transformation objects. Each object can include properties like `width`, `height`, `rotation`, overlays, and advanced effects.<br>Example: `[transformation]="[{ width: 300, height: 300 }]"`<br>See all [supported transformation](/content/docs/integration/angular#supported-transformations/index.html) options and how to [handle unsupported transformations](/content/docs/integration/angular#handling-unsupported-transformations/index.html). |
| **queryParameters** | An object with additional query parameters to append to the URL.<br>Example: `[queryParameters]="{ v: 2 }"` |
| **responsive** | A boolean that determines if responsive image functionality is enabled. By default, this is `true`, meaning that a `srcset` attribute is automatically generated for responsive images. Set it to `false` to disable this behavior and only apply explicitly defined transformations. |
| **deviceBreakpoints**<br>(number[]) | It allows you to specify a list of device width breakpoints.<br>Defaults to `[640, 750, 828, 1080, 1200, 1920, 2048, 3840]`. |
| **imageBreakpoints**<br>(number[]) | It allows you to specify a list of image width breakpoints. It is concatenated with `deviceBreakpoints` before calculating `srcSet`.<br>Defaults to `[16, 32, 48, 64, 96, 128, 256, 384]`. |
| **transformationPosition** | Specifies whether the transformation string is included in the URL path or as a query parameter. Defaults to `