filestack-angular

Angular component library which allow you to easily integrate powerful filestack-api into your app.

---

Table of Contents

• Overview
• Usage
  • Installation
  • CDN
  • Available inputs
  • Available outputs
  • FilestackService
  • Examples
    • Open picker directly after component initialization
    • Open picker by clicking the custom button
    • Open picker in inline mode
    • Open picker in drop pane mode
    • Get transformed url using filestackTransform pipe
    • Select file and upload using sdk client.upload()
• Documentation
• Development
• Contributing

Overview

filestack-angular is a wrapper on filestack-js sdk which allow you to integrate with Filestack service in just a few lines of code. Almost all you are able to do with filestack-js you can also do using this component.

This repository a contains angular workspace with two projects:

• filestack-angular library which contains FilestackAngularModule published via npm
• example angular app to show examples of using FilestackModule features

FilestackAngularModule consists of

• FilestackService - wrapper for a filestack-js client class with added support for an observables
• FilestackTransformPipe - Pipe for easily creating url with transformations in your template
• PickerOverlayComponent - Filestack picker component that will open in overlay mode
• PickerInlineComponent - Filestack picker component that will open in a provided html container
• PickerDropPaneComponent - Filestack drop pane component that will open in a provided html container which can be also used independently if needed

Compatibility

@filestack/angular 4 requires Angular 19 or newer (@angular/core / @angular/common >=19.0.0) and Node 20.19+/22.12+. For Angular 18 use @filestack/angular v3.x.

filestack-js v4 (^4.0.0) is installed automatically as a dependency. The v4 client methods (download, prefetch, setSecurity, setCname, and the extra storeURL params) are exposed by the service and work out of the box. The wrapper is still source-compatible with filestack-js v3 (>=3.47.4) if you deliberately override the installed version, but those v4-only methods will be unavailable at runtime on v3.

Server-Side Rendering (SSR)

The library is SSR-safe (Angular Universal). Because the Filestack picker and preview() need the browser DOM, they are guarded by isPlatformBrowser:

• The picker components (ng-picker-overlay, ng-picker-inline, ng-picker-drop-pane) render their container element on the server but do not initialize or open the picker — that happens only in the browser, after hydration.
• FilestackService.preview() returns null on the server (its return type is HTMLIFrameElement | Window | null); guard for null in your code.
• FilestackService.init() is safe to call on the server (it only constructs the filestack-js client and does not touch the DOM). DOM-dependent methods such as picker() and preview() should still only be called in the browser.

No extra configuration is required — just render as usual; the components produce no errors during server rendering.

Lazy picker loading

If your app doesn't show the picker immediately, use FilestackService.openPicker() to load filestack-js on demand via a dynamic import(), keeping the SDK out of the initial bundle (it loads in a separate chunk the first time the picker is opened):

async showPicker() {
  // filestack-js is fetched only when this runs
  const picker = await this.filestackService.openPicker({ /* PickerOptions */ });
}

Returns the opened PickerInstance (or null on the server). For the bundle benefit to materialize, reach for openPicker() instead of eagerly calling synchronous client methods on the critical path.

Zoneless change detection

The SDK supports Angular's zoneless change detection (provideZonelessChangeDetection()):

• Component state (e.g. the overlay's open/closed flag) is signal-based, so changes schedule change detection without zone.js.
• It never uses NgZone.run() or relies on zone.js patching.
• Outputs (uploadSuccess / uploadError) use the signal output() API.

No changes are needed on your side — it works the same with or without zone.js.

Usage

Installation

Install it through NPM

npm install @filestack/angular   # filestack-js is installed automatically

Or let the schematic install filestack-js and wire up the provider for you:

ng add @filestack/angular

Setup (standalone — recommended)

For standalone apps (bootstrapApplication), register the provider with provideFilestack() in your ApplicationConfig:

// app.config.ts
import { ApplicationConfig } from '@angular/core';
import { provideFilestack } from '@filestack/angular';

export const appConfig: ApplicationConfig = {
  providers: [
    provideFilestack({ apikey: 'YOUR_API_KEY' /*, options: ClientConfig */ })
  ]
};

// main.ts
import { bootstrapApplication } from '@angular/platform-browser';
import { AppComponent } from './app/app.component';
import { appConfig } from './app/app.config';

bootstrapApplication(AppComponent, appConfig);

The picker components and pipe are standalone — import them directly into any standalone component:

// app.component.ts
import { Component } from '@angular/core';
import {
  PickerOverlayComponent,
  PickerInlineComponent,
  PickerDropPaneComponent,
} from '@filestack/angular';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [PickerOverlayComponent, PickerInlineComponent, PickerDropPaneComponent],
  templateUrl: './app.component.html',
})
export class AppComponent {}

<!-- app.component.html — apikey is taken from provideFilestack(), no input needed -->
<ng-picker-overlay
  (uploadSuccess)="onUploadSuccess($event)"
  (uploadError)="onUploadError($event)">
  <button>Open picker</button>
</ng-picker-overlay>

A full working demo of all three pickers lives in projects/example-standalone. Run it with ng serve example-standalone.

Setup (NgModule — deprecated)

FilestackModule.forRoot() is kept for backward compatibility. Prefer provideFilestack() above for new apps.

import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';
import { FilestackModule } from '@filestack/angular';

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule,
    FilestackModule.forRoot({ apikey: YOUR_APIKEY, options: ClientConfig })
  ],
  bootstrap: [AppComponent]
})
export class AppModule {}

Use in .html file

<ng-picker-overlay
  apikey="YOUR_API_KEY">
</ng-picker-overlay>

CDN

The compiled filestack angular module is also available through our cdn

https://static.filestackapi.com/filestack-angular/{MODULE_VERSION}/filestack-angular.umd.min.js

and map file to module

https://static.filestackapi.com/filestack-angular/{MODULE_VERSION}/filestack-angular.umd.min.js.map

where {MODULE_VERSION} is desired version of this package

Available inputs

Name	Type	Required	Default	Description
apikey	String	True		Filestack api key
options	Object			Check pickerOptions
clientOptions.cname	String			Check cname
clientOptions.security	Object(Security)			Check security
clientOptions.sessionCache	Boolean			Check sessionCache
file	InputFile
source	String			Filestack handle or external url. Use it for 'transform', 'remove', 'metadata' or 'preview' action

Available outputs

Name	Type	Required	Default	Description
uploadSuccess	Subject			A subject that emits on uploadSuccess event
uploadError	Subject			A subject that emits on uploadError event

FilestackService

The FilestackService is an adapter on filestack-js client class and allows you to work with Observables instead of promises. Methods get the same input params as client class method.

method	return	description
init	void	Init filestack client with your apikey
picker	PickerInstance	Open or close picker instance
transform	string	Create a transformation url
retrieve	Observable	Deprecated (filestack-js v4) — use download or metadata instead
download	Observable	Download a file by its Filestack handle (filestack-js v4+)
metadata	Observable	Access files via their Filestack handles
storeURL	Observable	Store a file from a URL (supports v4 uploadTags/headers/workflowIds)
upload	Observable	Upload a file (or array of files via multiupload) to Filestack
prefetch	Observable	Check permissions before running operations (filestack-js v4+)
remove	Observable	Remove a file from the Filestack
removeMetadata	Observable	Remove a file only from the Filestack system. The file remains in storage.
preview	HTMLIFrameElement	Window
logout	Observable	Clear cloud session from picker procviders
setSecurity	void	Update the client security object at runtime (filestack-js v4+)
setCname	void	Update the client CNAME at runtime (filestack-js v4+)
setClientInstance	ClientInstance	Put an existing client instance into filestack service

Examples

Below you can find some basic examples.

You can also find and try these examples in angular-filestack-example app

To run it locally type

ng serve filestack-angular-example

then visit

http://localhost:4200/

Open picker directly after component initialization

component.ts

export class AppComponent implements OnInit {
  apikey: string;

  ngOnInit() {
    this.apikey = 'YOUR_API_KEY';
  }
}

component.html

<ng-picker-overlay
  [apikey]="apikey">
</ng-picker-overlay>

Open picker by clicking the custom button

component.ts

export class AppComponent implements OnInit {
  apikey: string;

  ngOnInit() {
    this.apikey = 'YOUR_API_KEY';
    this.onSuccess = (res) => console.log('###onSuccess', res);
    this.onError = (err) => console.log('###onErr', err);
  }

  onUploadSuccess(res: object) {
    console.log('###uploadSuccess', res);
  }

  onUploadError(err: any) {
    console.log('###uploadError', err);
  }
}

component.html

<ng-picker-overlay
  [apikey]="apikey"
  (uploadSuccess)="onUploadSuccess($event)"
  (uploadError)="onUploadError($event)">
  <button>Open picker</button>
</ng-picker-overlay>

Open picker in inline mode

component.ts

export class AppComponent implements OnInit {
  apikey: string;

  ngOnInit() {
    this.apikey = 'YOUR_API_KEY';
  }

  onUploadSuccess(res: object) {
    console.log('###uploadSuccess', res);
  }

  onUploadError(err: any) {
    console.log('###uploadError', err);
  }
}

component.html

<ng-picker-inline
  [apikey]="apikey"
  (uploadSuccess)="onUploadSuccess($event)"
  (uploadError)="onUploadError($event)">
  <button>Open picker</button>
</ng-picker-inline>

Open picker in drop pane mode

component.ts

export class AppComponent implements OnInit {
  apikey: string;

  ngOnInit() {
    this.apikey = 'YOUR_API_KEY';
  }

  onUploadSuccess(res: object) {
    console.log('###uploadSuccess', res);
  }

  onUploadError(err: any) {
    console.log('###uploadError', err);
  }
}

component.html

<ng-picker-drop-pane
  [apikey]="apikey"
  (uploadSuccess)="onUploadSuccess($event)"
  (uploadError)="onUploadError($event)">
</ng-picker-drop-pane>

Get transformed url using filestackTransform pipe

component.ts

...
import { TransformOptions } from 'filestack-js';

export class AppComponent implements OnInit {
  transformOptions: TransformOptions;

  constructor(private filestackService: FilestackService) {}

  ngOnInit() {
    this.transformOptions = {
      resize: {
        width: 400
      },
      sepia: {
        tone: 80
      }
    }
  }
}

component.html

  <img src="{{'5aYkEQJSQCmYShsoCnZN' | filestackTransform: transformOptions}}">

Select file and upload using sdk client.upload()

component.ts

export class AppComponent implements OnInit {
  file: any;

  constructor(private filestackService: FilestackService) {}

  ngOnInit() {
    this.filestackService.init('YOUR_API_KEY'); 
  }
  fileChanged(e) {
    this.file = e.target.files[0];
  }
  uploadFile() {
    this.filestackService.upload(this.file)
      .subscribe(res => console.log(res));
  }
}

component.html

  <input type='file' (change)="fileChanged($event)">
  <button (click)="uploadFile()">Upload file</button>

Documentation

You can find necessary info about avalaible options for actions (Client class methods) at https://filestack.github.io/filestack-js/

Development

After adding changes to FilestackAngularModule in /projects/filestack-angular/src

you need to build this module

ng build filestack-angular

this command will produce /dist which conatins ready to use filestack module

you can check correctness of it by checking examples from example app:

1. Update api key in /projects/example/src/app/app.component.ts

2. start app locally

ng serve example

3. visit http://localhost:4200/

Contributing

Any of your contributions or ideas are more than welcome. Please consider that we follow the conventional commits specification to ensure consistent commit messages and changelog formatting.