NGX File Preview

中文 · English

NGX File Preview is a powerful Angular file preview component library that supports previewing a wide variety of file formats and offers flexible customization options, providing an efficient and user-friendly solution for developers.

Preview Examples

Default List View

Custom Template (Example, fully customizable)

Preview Effects for Different File Types

File Type	Preview Effect
Image
Video
Audio
PPT
Word
Excel
Text
Markdown
Zip
Unknown

Features

Support for Multiple File Formats: Fully compatible with image, PDF, PPT, Word, Excel, text, markdown, audio, video, and many other common file types.
Intuitive User Experience: Provides clear indicators for unknown file types and supports user-friendly interactions for different file formats.
Dark Mode and Light Mode: Adapts to various use cases with visual preferences for both dark and light modes, including auto mode switching.
Flexible Usage: Supports both directive-based and component-based usage, offering flexibility to meet different development requirements.
Lightweight Design: Optimized for performance and easy integration into any project, ensuring smooth and efficient operation.
Keyboard Shortcut Support: Increases efficiency by allowing easy navigation and closing of the preview with keyboard shortcuts.
Internationalization Support: Built-in i18n support with easy language pack registration and switching capabilities.

Installation

npm install @eternalheart/ngx-file-preview --save docx-preview hls.js pptx-preview xlsx ngx-extended-pdf-viewer markdown-it highlight.js

Internationalization (i18n)

Language Configuration

You can specify the language when using the directive:

<div [ngxFilePreview]="file" lang="en">Click to preview</div>

Register New Language Pack

import { I18nUtils } from '@eternalheart/ngx-file-preview';

// Register a new language pack
I18nUtils.register('fr', {
  preview: {
    error: {
      noFiles: 'Aucun fichier à afficher'
    },
    toolbar: {
      zoomIn: 'Zoom avant',
      zoomOut: 'Zoom arrière'
      // ... other translations
    }
  }
  // ... more translation keys
});

Using i18n Pipe(For developers)

Use the i18n pipe in templates to translate text:

{{ 'preview.toolbar.zoomIn' | i18n }}
// With parameters 
// Use ${0} as a numeric placeholder in the corresponding text. The number of placeholders is unlimited, but you must pass the corresponding number of arguments when using them.
// example: list.total ==> "共${0}个文件"
{{ 'list.total' | i18n:filesCount }}

Configuration

1. Font Icon Configuration and Resources

Add the necessary assets , styles and scripts to your angular.json file:

{
  "projects": {
    "your-app": {
      "architect": {
        "build": {
          "options": {
            "assets": [
              {
                "glob": "**/*",
                "input": "node_modules/ngx-extended-pdf-viewer/assets",
                "output": "assets"
              }
            ],
            "styles": [
              "node_modules/@eternalheart/ngx-file-preview/src/assets/icon/font/nfp.css"
            ],
            "scripts": [
              "node_modules/@eternalheart/ngx-file-preview/src/assets/icon/color/nfp.js"
            ]
          }
        }
      }
    }
  }
}

2. Module Imports

Import the required components in your Angular module:

import {
  PreviewDirective,
  PreviewListComponent,
  PreviewModalComponent
} from '@eternalheart/ngx-file-preview';

@Component({
  imports: [
    PreviewDirective,
    PreviewListComponent,
  ]
})

Usage

1. Directive Method

The simplest usage method: Apply the directive directly to an element:

import {PreviewDirective, PreviewEvent} from '@eternalheart/ngx-file-preview';

@Component({
  imports: [PreviewDirective],
  template: `
    <!-- Use themeMode to specify the display mode (dark/light). By default, it automatically switches based on time, but can also be manually toggled inside the preview page -->
    <div [ngxFilePreview]="file" themeMode="light">Click to preview a single file</div>
    <div [ngxFilePreview]="file" themeMode="dark" (previewEvent)="handlePreviewEvent($event)">Click to preview a single file</div>
    <div [ngxFilePreview]="file" themeMode="auto" [autoConfig]="{dark: {start: 19, end: 7}}">Click to preview a single file</div>
    <div [ngxFilePreview]="files">Click to preview multiple files</div>
  `
})
export class YourComponent {
  file: PreviewFile = {
    name: 'example.jpg',
    type: 'image',
    url: 'path/to/file.jpg'
  };

  files: PreviewFile[] = [
    // ... file array
  ];

  handlePreviewEvent(event: PreviewEvent) {
    const {type, message, event: targetEvent} = event;
    if (type === "error") {
      console.log(message); // Handle error event
    }
    if (type === "select") {
      console.log(targetEvent); // Handle file selection event
    }
  }
}

2. Component Method

Using the Default List Template:

import {PreviewListComponent} from '@eternalheart/ngx-file-preview';

@Component({
  imports: [PreviewListComponent],
  template: `
    <ngx-preview-list [files]="files" (fileSelect)="onFileSelect($event)">
    </ngx-preview-list>
  `
})

Using a Custom Template:

@Component({
  template: `
    <ngx-preview-list [files]="files">
      <ng-template #itemTemplate 
                   let-file 
                   let-index="index"
                   let-isActive="isActive"
                   let-preview="preview">
        <div class="custom-item" 
             [class.active]="isActive"
             (click)="preview()">
          <span>{{ file.name }}</span>
          <span>{{ formatFileSize(file.size) }}</span>
        </div>
      </ng-template>
    </ngx-preview-list>
  `
})

File Configuration

`PreviewFile` Interface

interface PreviewFile {
  url: string;          // File URL
  name: string;         // File name
  type?: PreviewType;    // File type - Not nessary
  size?: number;        // File size (optional)
  lastModified?: number;// Last modified time (optional)
  coverUrl?: string;    // Cover image URL (for video/audio, optional)
}

Supported File Types (`PreviewType`)

type PreviewType =
  | 'image'   // Image
  | 'pdf'     // PDF Document
  | 'ppt'     // PPT Presentation
  | 'word'    // Word Document
  | 'txt'     // Text File
  | 'video'   // Video
  | 'excel'   // Excel Spreadsheet
  | 'audio'   // Audio
  | 'zip'     // Compressed File
  | 'unknown' // Unknown Type

API Reference

PreviewListComponent

Property	Type	Default	Description
files	PreviewFile[]	[]	List of files to preview
themeMode	'light' \| 'dark' \| 'auto'	'auto'	Theme mode for the preview
autoConfig	{ dark: { start: number, end: number } }	{ dark: { start: 19, end: 7 } }	Auto theme mode configuration
lang	string	'zh'	Internationalization language setting, 'zh' and 'en' are registered by default
(fileSelect)	EventEmitter	-	Event emitted when a file is selected
(previewEvent)	EventEmitter	-	Event emitted during preview actions

Template Context Variables

Variable	Type	Description
file	PreviewFile	Current file object
index	number	Current file index
type	string	File type
isActive	boolean	Whether the current item is selected
select	() => void	Method to select the current file
preview	() => void	Method to preview the current file

PreviewDirective

Selector	Property	Type	Default	Description
[ngxFilePreview]	ngxFilePreview	PreviewFile \| PreviewFile[]	-	File(s) to preview
	themeMode	'light' \| 'dark' \| 'auto'	'auto'	Theme mode for the preview
	autoConfig	{ dark: { start: number, end: number } }	{ dark: { start: 19, end: 7 } }	Auto theme mode configuration
	lang	string	'zh'	Internationalization language setting, 'zh' and 'en' are registered by default
	(previewEvent)	EventEmitter	-	Event emitted during preview actions

PreviewEvent Types

Event Type	Description	Event Data
error	Error event	{ type: 'error', message: string }
select	File selection event	{ type: 'select', event: MouseEvent }

Keyboard Shortcuts

In preview mode, the following shortcuts are available:

← Previous file
→ Next file
Esc Close preview

Development Guide

Clone the repository:

git clone https://github.com/wh131462/ngx-file-preview.git

Install dependencies:

npm install

Start the development server:

npm run start

Build the library:

npm run build

Contribution Guidelines

Feel free to submit Issues and Pull Requests to help improve this project!

License

MIT

Acknowledgments

This project uses the following excellent open-source libraries:

docx-preview - Word document preview
pptx-preview - PPT presentation preview
xlsx - Excel spreadsheet preview
ngx-extended-pdf-viewer - PDF document preview
hls.js - HLS video stream support
markdown-it - Markdown support
highlight.js - The code in Markdown is highlighted by Markdown support

We appreciate the contributions from these open-source projects to the community!

@eternalheart/ngx-file-preview

NGX File Preview

Preview Examples

Default List View

Custom Template (Example, fully customizable)

Preview Effects for Different File Types

Features

Installation

Internationalization (i18n)

Language Configuration

Register New Language Pack

Using i18n Pipe(For developers)

Configuration

1. Font Icon Configuration and Resources

2. Module Imports

Usage

1. Directive Method

2. Component Method

Using the Default List Template:

Using a Custom Template:

File Configuration

PreviewFile Interface

Supported File Types (PreviewType)

API Reference

PreviewListComponent

Template Context Variables

PreviewDirective

PreviewEvent Types

Keyboard Shortcuts

Development Guide

Contribution Guidelines

License

Acknowledgments

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

`PreviewFile` Interface

Supported File Types (`PreviewType`)

Weekly Downloads