> For the complete documentation index, see [llms.txt](https://docs.fortifiedid.se/common/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fortifiedid.se/common/overlay.md).

# Overlay

How an overlay directory is configured and how the files in it take effect

All applications providing UI implement the same pattern regarding styling. An overlay directory supplies organisation-specific files that are served instead of the built-in ones.

## Configure the overlay directories

An overlay directory is read before the built-in files. A resource that exists in both is served from the overlay.

Two configuration parameters control this:

* `overlay_dir` — a single directory. In Fortified ID Access this defaults to `${system.customer_home}/overlay`, so in a standard installation you can place the files there without changing any configuration.
* `overlay_dirs` — a list of directories, searched in the order they are defined. The first directory that contains the requested resource wins.

Example from a Forms config, using two directories.

```json
{
  "name": "Forms",
  "config": {
    "http_context": "/forms",
    "logout_endpoint_url": "/forms/logout",
    "overlay_dirs": ["config/locale_overlay", "config/ui_overlay"],
    "flows": "@include:../flows/*/flow.json"
  }
}
```

Inside the overlay directory, create a folder named `assets`. The application requests its resources below `assets/`, so that is where the overlay files must sit.

## How a file takes effect

Overlay files fall into two groups, and confusing them is the most common reason a change appears to do nothing.

{% hint style="warning" %}
Placing a file in the overlay is only enough when it replaces a built-in file of the same name. Any other file is inert until something points at it.
{% endhint %}

### Files that take effect on their own

These replace a built-in file of the same name and are picked up as soon as they exist.

<table data-full-width="true"><thead><tr><th>File</th><th>What it controls</th></tr></thead><tbody><tr><td><code>css_overrides.css</code></td><td>Colors, buttons, links, progress bar, header, loader, and background image. Empty by default. See <a href="/common/css.md">CSS</a>.</td></tr><tr><td><code>ui_config_overrides.json</code></td><td>Names, titles, logo files, logo sizes, footer link, and per-application logo visibility. Empty by default. See <a href="/common/ui-configuration-overrides.md">UI Configuration Overrides</a>.</td></tr><tr><td><code>favicon.ico</code></td><td>Site icon shown in the browser tab. Applications link <code>assets/favicon.ico</code> directly.</td></tr><tr><td><code>logo.svg</code></td><td>Primary logo. Most authentication applications ship an <code>assets/logo.svg</code> and use it as the header logo, so a file with this name replaces it. Applications that do not use that slot are unaffected.</td></tr><tr><td><code>locales/&#x3C;code>.json</code></td><td>Replaces a built-in language file wholesale. To extend rather than replace, see <a href="/common/language-translations.md">Language translations</a>.</td></tr></tbody></table>

### Files that need a reference

These are naming conventions, not slots. The file name has no meaning to the application until you point at it.

<table data-full-width="true"><thead><tr><th>File</th><th>How to activate it</th></tr></thead><tbody><tr><td>Background image, by convention <code>background.svg</code></td><td>Set <code>--background-image</code> in <code>css_overrides.css</code>. The built-in default is <code>bg_login.svg</code>, so a file named <code>background.svg</code> has no effect on its own. The image may be <code>svg</code>, <code>png</code>, <code>jpg</code>, or <code>jpeg</code>.</td></tr><tr><td>Negative logo, by convention <code>logo_vit.svg</code></td><td>Reference it from <code>ui_config_overrides.json</code>, normally as <code>app_logo</code> for Portal, Forms, and Password Reset. No built-in file uses this name.</td></tr><tr><td>Any additional logo or image</td><td>Reference it from <code>ui_config_overrides.json</code> or <code>css_overrides.css</code>. Paths are relative to the application, so a file in the overlay <code>assets</code> folder is addressed as <code>assets/&#x3C;name></code>.</td></tr><tr><td>Custom locale files</td><td>Set <code>localesMergePath</code> in <code>ui_config_overrides.json</code>. See <a href="/common/language-translations.md">Language translations</a>.</td></tr></tbody></table>

{% hint style="info" %}
Relative `url()` references in `css_overrides.css` are resolved against the directory the stylesheet was loaded from, so `url('background.svg')` finds a file next to it in the `assets` folder.
{% endhint %}

## A typical organisation overlay

A complete organisation overlay usually contains these six files. The first three take effect on their own, the last three are referenced from them.

```
<overlay directory>/assets/
├── css_overrides.css
├── ui_config_overrides.json
├── favicon.ico
├── logo.svg
├── logo_vit.svg
└── background.svg
```

Add locale files when texts need changing. For guidance on sourcing the image files themselves, see [Brand assets](/common/brand-assets.md).