# How to Use Static Files in Remotion Compositions: The Complete Guide

> Learn to use static files in Remotion compositions. Discover how to place assets in public/ and use the staticFile function for a seamless workflow in Remotion Studio and deployed players.

- Repository: [Remotion/remotion](https://github.com/remotion-dev/remotion)
- Tags: how-to-guide
- Published: 2026-02-16

---

**Place assets in a `public/` folder and resolve them using the `staticFile()` function, which validates paths, encodes unsafe characters, and returns a runtime URL that works in both the Remotion Studio and deployed players.**

Managing static assets is essential when building programmatic video with React. In the `remotion-dev/remotion` repository, the framework provides a dedicated API to handle images, fonts, audio, and other files through a `public/` directory workflow. This guide explains how to use static files in Remotion compositions using the `staticFile()`, `getStaticFiles()`, and `watchStaticFile()` utilities.

## Setting Up the Public Directory

Remotion expects static assets to live in a folder named `public/` located at the same level as your [`package.json`](https://github.com/remotion-dev/remotion/blob/main/package.json) that contains the Remotion dependency. You can create subdirectories inside `public/` to organize images, fonts, videos, or JSON data.

Place any static asset in this folder, then reference it by its path relative to the `public/` directory without including the `public/` prefix in your code.

## Resolving Asset Paths with staticFile()

The `staticFile()` function is the primary API for converting a file path into a URL that the Remotion Player and Studio can serve at runtime. According to the source code in [[`packages/core/src/static-file.ts`](https://github.com/remotion-dev/remotion/blob/main/packages/core/src/static-file.ts)](https://github.com/remotion-dev/remotion/blob/main/packages/core/src/static-file.ts), this utility performs three critical tasks:

1. **Validation**: It throws descriptive errors if you pass remote URLs (starting with `http://` or `https://`), relative paths (starting with `./` or `../`), absolute system paths, or paths that already include the `public/` prefix.
2. **Encoding**: Since version 4.0, it automatically applies `encodeURIComponent` to each path segment, ensuring that filenames with spaces or special characters work without manual encoding.
3. **Base URL Prefixing**: It prepends the correct static base URL that the Studio or Player serves at runtime, abstracting away deployment-specific paths like `/static-abc123/`.

### Basic Usage Example

```tsx
import {Img, staticFile} from 'remotion';

export const MyComposition = () => {
  // Resolves to "/static-<hash>/logo.png" at runtime
  const logoUrl = staticFile('logo.png');

  return (
    <div style={{flexDirection: 'row', alignItems: 'center'}}>
      <Img src={logoUrl} width={200} height={200} />
      <p>My brand logo</p>
    </div>
  );
};

```

### Loading Custom Fonts

You can also use `staticFile()` with the browser's FontFace API to load custom typefaces:

```tsx
import {staticFile} from 'remotion';

const myFont = new FontFace(
  'MyFont',
  `url(${staticFile('fonts/MyFont.woff2')}) format('woff2')`,
);

await myFont.load();
document.fonts.add(myFont);

```

## Enumerating Assets with getStaticFiles()

When you need to build dynamic galleries or iterate over available resources, the `getStaticFiles()` function returns metadata for every file in the `public/` directory. As implemented in [[`packages/core/src/get-static-files.ts`](https://github.com/remotion-dev/remotion/blob/main/packages/core/src/get-static-files.ts)](https://github.com/remotion-dev/remotion/blob/main/packages/core/src/get-static-files.ts), it returns an array of objects containing:

- `src`: The resolved URL path
- `name`: The filename
- `sizeInBytes`: File size
- `lastModified`: Timestamp

This API only works in the browser or Studio environment, not during server-side rendering.

```tsx
import {getStaticFiles, Img, staticFile} from 'remotion';

export const Gallery = () => {
  const files = getStaticFiles().filter((f) => f.name.endsWith('.png'));

  return (
    <div style={{display: 'flex', flexWrap: 'wrap'}}>
      {files.map((file) => (
        <Img key={file.name} src={file.src} width={150} height={150} />
      ))}
    </div>
  );
};

```

## Live Reloading with watchStaticFile()

During development in the Remotion Studio, you can monitor static files for changes using `watchStaticFile()`. This utility, found in [[`packages/core/src/watch-static-file.ts`](https://github.com/remotion-dev/remotion/blob/main/packages/core/src/watch-static-file.ts)](https://github.com/remotion-dev/remotion/blob/main/packages/core/src/watch-static-file.ts), sets up a listener that triggers when a file is added, modified, or removed.

The function returns a `cancel` method to clean up the listener. Note that in Remotion v5, this functionality moved to the `@remotion/studio` package.

```tsx
import {staticFile, watchStaticFile, Img} from 'remotion';
import {useEffect, useState} from 'react';

export const LiveImage = () => {
  const [src, setSrc] = useState(() => staticFile('dynamic.png'));

  useEffect(() => {
    const {cancel} = watchStaticFile('dynamic.png', (newData) => {
      if (newData) {
        // Force reload by appending timestamp
        setSrc(`${newData.src}?t=${Date.now()}`);
      }
    });
    return cancel;
  }, []);

  return <Img src={src} width={400} height={300} />;
};

```

## Summary

- Place all static assets in a `public/` folder at the project root to make them available to Remotion compositions.
- Use **`staticFile()`** to resolve paths into runtime URLs, letting the function handle validation, encoding, and base-path prefixing automatically.
- Enumerate available assets with **`getStaticFiles()`** when building dynamic galleries or processing multiple files.
- Enable live reloading during development with **`watchStaticFile()`** to react to asset changes in real time.
- Reference the source implementations in [`packages/core/src/static-file.ts`](https://github.com/remotion-dev/remotion/blob/main/packages/core/src/static-file.ts), [`get-static-files.ts`](https://github.com/remotion-dev/remotion/blob/main/get-static-files.ts), and [`watch-static-file.ts`](https://github.com/remotion-dev/remotion/blob/main/watch-static-file.ts) for advanced customization.

## Frequently Asked Questions

### What is the difference between staticFile() and a regular import?

A regular ES Module import bundles the asset into your JavaScript build, increasing bundle size and requiring rebuilds when the file changes. The **`staticFile()`** function keeps assets separate in the `public/` folder, references them by URL at runtime, and allows instant updates without recompiling your Remotion code.

### Can I use staticFile() with remote URLs or absolute paths?

No. The implementation in [`packages/core/src/static-file.ts`](https://github.com/remotion-dev/remotion/blob/main/packages/core/src/static-file.ts) explicitly throws errors for remote URLs (starting with `http://` or `https://`), absolute system paths (starting with `/` on Unix or `C:\` on Windows), and relative paths (starting with `./` or `../`). You must pass a plain filename or path relative to the `public/` folder without the `public/` prefix.

### How do I handle filenames with spaces or special characters?

Since Remotion v4.0, **`staticFile()`** automatically applies `encodeURIComponent` to each path segment. You should pass the filename exactly as it appears in your `public/` folder (e.g., `staticFile('my file.png')`) without pre-encoding spaces or special characters. The function handles the encoding to ensure valid URLs.

### Why does watchStaticFile() not work in my production render?

The **`watchStaticFile()`** utility relies on the Remotion Studio's development server to monitor file system changes. It is designed for the browser/Studio environment only and does not function during server-side rendering or production video renders. For production, ensure all assets exist in `public/` before starting the render, or use `getStaticFiles()` to validate availability at runtime.