react-file-preview-engine

A renderer driven React file preview engine designed for extensibility, correctness, and long term maintainability.

react-file-preview-engine lets you preview files by delegating rendering to small, isolated renderers that decide if they can handle a file based on runtime context. It supports common media types out of the box and makes it trivial to add or override renderers for custom formats.

Why react-file-preview-engine

Inspired by @codesmith-99/react-file-preview and redesigned to address its architectural and maintenance limitations.

• Renderer driven architecture instead of hard coded conditional rendering
• Built in support for images, video, audio, pdf, html, and plain text
• Automatic MIME type resolution using file name when needed
• Supports multiple file source types including URL, File, Blob, and ArrayBuffer
• Stable loading, ready, and error state handling
• Abortable fetches with proper cleanup for fast file switching
• First class support for custom renderers
• Optional, fully typed additional render context
• Pluggable error renderer
• Fully typed public API
• React is not bundled as a direct dependency
• Actively maintained and designed for long term extensibility

Installation

# npm
npm install react-file-preview-engine

# yarn
yarn add react-file-preview-engine

# pnpm
pnpm add react-file-preview-engine

# bun
bun add react-file-preview-engine

Usage

react-file-preview-engine exposes a single default export, the <FilePreviewer /> component.

You can pass it a file source and basic file metadata. The source can be a URL, File, Blob, or ArrayBuffer. Using the provided MIME type or file name, the engine dynamically resolves the most suitable renderer at runtime.

Basic Usage

This is the minimal setup. The previewer automatically infers the MIME type from fileName if not provided.

import React from "react";
import FilePreviewer from "react-file-preview-engine";

export default function App() {
  return <FilePreviewer src="https://example.com/sample.pdf" fileName="sample.pdf" />;
}

Previewing Local Files

You can preview files selected by the user without uploading them first. The engine automatically converts File, Blob, and ArrayBuffer sources to object URLs internally.

import React, { useState } from "react";
import FilePreviewer from "react-file-preview-engine";

export default function App() {
  const [file, setFile] = useState<File>();

  return (
    <>
      <input type="file" onChange={(e) => setFile(e.target.files?.[0])} />
      {file && <FilePreviewer src={file} fileName={file.name} mimeType={file.type} />}
    </>
  );
}

Providing MIME Type Explicitly

If you already know the MIME type, you can pass it directly. This ensures the engine uses the correct renderer even when inference is not possible.

import React from "react";
import FilePreviewer from "react-file-preview-engine";

export default function App() {
  return <FilePreviewer src={new Blob(["Hello world"], { type: "text/plain" })} mimeType="text/plain" fileName="hello.txt" />;
}

Handling Load and Error Events

You can listen to lifecycle events triggered by the active renderer.

import React from "react";
import FilePreviewer from "react-file-preview-engine";

export default function App() {
  return (
    <FilePreviewer
      src="/document.pdf"
      fileName="document.pdf"
      onLoad={() => {
        console.log("File loaded");
      }}
      onError={() => {
        console.error("Failed to load file");
      }}
    />
  );
}

Auto Play Media Files

For audio and video files, you can enable auto play.

import React from "react";
import FilePreviewer from "react-file-preview-engine";

export default function App() {
  return <FilePreviewer src="https://example.com/video.mp4" fileName="video.mp4" autoPlay={true} />;
}

Partial Customization

You can customize the loader, container props, and icon props without modifying any renderers.

import React from "react";
import FilePreviewer from "react-file-preview-engine";

export default function App() {
  return (
    <FilePreviewer
      src="/image.jpg"
      fileName="image.jpg"
      loader={<div>Loading preview…</div>}
      containerProps={{ style: { border: "1px solid #e5e7eb", padding: 8 } }}
      iconProps={{ style: { fontSize: 48 } }}
    />
  );
}

Custom Error Renderer

When a renderer reports an error, the previewer switches to errorRenderer.

import React from "react";
import FilePreviewer from "react-file-preview-engine";

const errorRenderer = {
  Component() {
    return <div>Preview unavailable</div>;
  },
};

export default function App() {
  return <FilePreviewer src="/missing.pdf" fileName="missing.pdf" errorRenderer={errorRenderer} />;
}

Custom Renderers

react-file-preview-engine resolves previews using renderers. A renderer declares whether it can handle a file using canRender and renders the preview inside its Component.

Renderers receive a render context that includes src, mimeType, fileName, lifecycle callbacks, and any values passed via additionalContext. The same context mechanism applies to customRenderers and errorRenderer.

Renderer Resolution Order

When previewing a file, the engine checks renderers in this order:

1. Your customRenderers (from first to last)
2. Built-in default renderers
3. fallbackRenderer (icon fallback)

This means you can override built-in renderers by providing a custom renderer with the same canRender logic.

Markdown Renderer Example

This example adds support for markdown files.

import React, { useEffect, useState } from "react";
import FilePreviewer from "react-file-preview-engine";
import type { Renderer } from "react-file-preview-engine/types";
import remarkGfm from "remark-gfm";
import rehypeRaw from "rehype-raw";
import { useRemark } from "react-remarkify";
import rehypeSanitize from "rehype-sanitize";

const markdownRenderer: Renderer = {
  name: "markdown",
  canRender({ mimeType }) {
    return mimeType === "text/markdown";
  },
  Component({ src, onLoad, onError }) {
    const [markdown, setMarkdown] = useState("");

    useEffect(() => {
      const controller = new AbortController();

      fetch(src, { signal: controller.signal })
        .then((res) => res.text())
        .then((text) => {
          setMarkdown(text);
          onLoad();
        })
        .catch(onError);

      return () => controller.abort();
    }, [src]);

    const reactContent = useRemark({
      markdown,
      remarkPlugins: [remarkGfm],
      rehypePlugins: [rehypeRaw, rehypeSanitize],
      remarkToRehypeOptions: { allowDangerousHtml: true },
    });

    return <div>{reactContent}</div>;
  },
};

export default function App() {
  return <FilePreviewer src="/README.md" fileName="README.md" customRenderers={[markdownRenderer]} />;
}

Passing Additional Context

You can extend renderers with custom configuration using additionalContext. This example enhances the markdown renderer to toggle between HTML and raw text rendering.

Important: additionalContext must remain stable across renders. Use useMemo for dynamic values or define it outside your component for static values.

import React, { useEffect, useMemo, useState } from "react";
import FilePreviewer from "react-file-preview-engine";
import type { Renderer } from "react-file-preview-engine/types";
import remarkGfm from "remark-gfm";
import rehypeRaw from "rehype-raw";
import { useRemark } from "react-remarkify";
import rehypeSanitize from "rehype-sanitize";

const markdownRenderer: Renderer<{ renderAsHtml?: boolean }> = {
  name: "markdown",
  canRender({ mimeType }) {
    return mimeType === "text/markdown";
  },
  Component({ src, onLoad, onError, renderAsHtml = true }) {
    const [markdown, setMarkdown] = useState("");

    useEffect(() => {
      const controller = new AbortController();

      fetch(src, { signal: controller.signal })
        .then((res) => res.text())
        .then((text) => {
          setMarkdown(text);
          onLoad();
        })
        .catch(onError);

      return () => controller.abort();
    }, [src]);

    const reactContent = useRemark({
      markdown,
      remarkPlugins: [remarkGfm],
      rehypePlugins: [rehypeRaw, rehypeSanitize],
      remarkToRehypeOptions: { allowDangerousHtml: true },
    });

    return renderAsHtml ? <div>{reactContent}</div> : <pre>{markdown}</pre>;
  },
};

export default function App() {
  const [renderAsHtml, setRenderAsHtml] = useState(true);
  const additionalContext = useMemo(() => ({ renderAsHtml }), [renderAsHtml]); // Keep stable across renders

  return (
    <>
      <button onClick={() => setRenderAsHtml(!renderAsHtml)}>Toggle {renderAsHtml ? "Raw" : "HTML"}</button>
      <FilePreviewer src="/README.md" fileName="README.md" customRenderers={[markdownRenderer]} additionalContext={additionalContext} />
    </>
  );
}

Default Renderers

The library includes built-in renderers for text, pdf, html, images, audio, and video. These handle common file types without any configuration.

You can explore the actual renderer definitions in the defaultRenderers constant on GitHub.

API Reference

FilePreviewer Component

Here is the full API for the <FilePreviewer> component, these properties can be set on an instance of FilePreviewer:

| Prop | Type | Required | Default | Description | | ------------------- | ------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | | src | FileSource | Yes | – | Source URL of the file to preview | | mimeType | string | No | inferred | MIME type of the file | | fileName | string | No | - | Used for MIME inference and accessibility | | autoPlay | boolean | No | false | Auto play audio and video | | loader | ReactNode | No | <Loader /> | Shown while the file is loading | | customRenderers | Renderer[] | No | - | Additional or overriding renderers | | additionalContext | object | No | - | Extra data passed to the renderers. Must remain stable across renders | | errorRenderer | Renderer | No | fallbackRenderer | Renderer used on error | | containerProps | DivProps | No | - | Props applied to preview container | | iconProps | DivProps | No | - | Props applied to fallback icon | | onLoad | Eventhandler | No | – | Called when preview is ready | | onError | Eventhandler | No | – | Called when preview fails |

Types

DivProps

import type { DetailedHTMLProps, HTMLAttributes } from "react";

type DivProps = DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>;

EventHandler

export type EventHandler = () => void;

FileSource

export type FileSource = string | File | Blob | ArrayBuffer;

Renderer

type RenderContext<T extends object = {}> = {
  src: string;
  mimeType: string;
  fileName: string;
  autoPlay: boolean;
  iconProps: DivProps;
  onLoad: () => void;
  onError: () => void;
} & T;
type Renderer<T extends object = {}> = {
  name?: string;
  canRender?(ctx: RenderContext<T>): boolean;
  Component(ctx: RenderContext<T>): JSX.Element;
};

License

This project is licensed under the MIT License.