https://github.com/filestack/filestack-angular
An official angular component library for the Filestack
https://github.com/filestack/filestack-angular
angular file-upload filestack upload
Last synced: 4 months ago
JSON representation
An official angular component library for the Filestack
- Host: GitHub
- URL: https://github.com/filestack/filestack-angular
- Owner: filestack
- License: mit
- Created: 2019-07-25T09:21:20.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2024-10-28T06:31:41.000Z (about 1 year ago)
- Last Synced: 2024-11-13T17:12:13.274Z (12 months ago)
- Topics: angular, file-upload, filestack, upload
- Language: TypeScript
- Homepage:
- Size: 889 KB
- Stars: 9
- Watchers: 11
- Forks: 10
- Open Issues: 28
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-angular - filestack-angular - Integrate [Filestack](https://www.filestack.com/) into your Angular app for a faster, safer, and more reliable file upload experience. (Third Party Components / File Upload)
- trackawesomelist - filestack-angular (⭐10) - Integrate [Filestack](https://www.filestack.com/) into your Angular app for a faster, safer, and more reliable file upload experience. (Recently Updated / [Feb 28, 2025](/content/2025/02/28/README.md))
- fucking-awesome-angular - filestack-angular - Integrate 🌎 [Filestack](www.filestack.com/) into your Angular app for a faster, safer, and more reliable file upload experience. (Third Party Components / File Upload)
README
filestack-angular
Angular component library which allow you to easily integrate powerful filestack-api into your app.
**Table of Contents**
- [Overview](#overview)
- [Usage](#usage)
- [Installation](#installation)
- [CDN](#cdn)
- [Available inputs](#available-inputs)
- [Available outputs](#available-outputs)
- [FilestackService](#filestackservice)
- [Examples](#examples)
- [Open picker directly after component initialization](#open-picker-directly-after-component-initialization)
- [Open picker by clicking the custom button](#open-picker-by-clicking-the-custom-button)
- [Open picker in inline mode](#open-picker-in-inline-mode)
- [Open picker in drop pane mode](#open-picker-in-drop-pane-mode)
- [Get transformed url using filestackTransform pipe](#get-transformed-url-using-filestacktransform-pipe)
- [Select file and upload using sdk client.upload()](#select-file-and-upload-using-sdk-clientupload)
- [Documentation](#documentation)
- [Development](#development)
- [Contributing](#contributing)
## Overview
filestack-angular is a wrapper on [filestack-js](https://github.com/filestack/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](https://filestack.github.io/filestack-js/index.html) 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](https://www.filestack.com/docs/api/processing/) 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
## Usage
### Installation
Install it through NPM
```bash
npm install filestack-js
npm install @filestack/angular
```
Include ```FilestackModule``` in ```app.module.ts```
```javascript
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
```html
```
### 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](https://filestack.github.io/filestack-js/interfaces/pickeroptions.html) |
| clientOptions.cname | String | | | Check [cname](https://filestack.github.io/filestack-js/interfaces/clientoptions.html#cname) |
| clientOptions.security | Object([Security](https://filestack.github.io/filestack-js/interfaces/security.html)) | | | Check [security](https://filestack.github.io/filestack-js/interfaces/clientoptions.html#security) |
| clientOptions.sessionCache | Boolean | | | Check [sessionCache](https://filestack.github.io/filestack-js/interfaces/clientoptions.html#sessioncache) |
| file | [InputFile](https://filestack.github.io/filestack-js/globals.html#inputfile) | | | | Use it to insert a file object for 'upload' action |
| 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](https://filestack.github.io/filestack-js/classes/client.html)
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](https://filestack.github.io/filestack-js/interfaces/pickerinstance.html) | Open or close picker instance |
| transform | string | Create a transformation url |
| retrieve | Observable | Retrieve an info about a filestack handle |
| metadata | Observable | Access files via their Filestack handles |
| storeURL | Observable | Get info about a filestack handle metadata |
| upload | Observable | Upload a file to the Filestack |
| 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 | Get preview of uploaded file (need additional addon in your Filestack account)|
| logout | Observable | Clear cloud session from picker procviders |
| setClientInstance | [ClientInstance](https://filestack.github.io/filestack-js/classes/client.html) | 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`
```typescript
export class AppComponent implements OnInit {
apikey: string;
ngOnInit() {
this.apikey = 'YOUR_API_KEY';
}
}
```
`component.html`
```html
```
#### Open picker by clicking the custom button
`component.ts`
```typescript
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`
```html
Open picker
```
#### Open picker in inline mode
`component.ts`
```typescript
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`
```html
Open picker
```
#### Open picker in drop pane mode
`component.ts`
```typescript
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`
```html
```
#### Get transformed url using filestackTransform pipe
`component.ts`
```typescript
...
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`
```html
```
#### Select file and upload using sdk client.upload()
`component.ts`
```typescript
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`
```html
Upload file
```
## 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/](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.