UI Customization

Specifying a Custom Theme

The easiest way to change the look of the user interface is to add a custom theme. To do this, create the file config/theme/app.js in the storage folder and insert the following with a text editor:

window.__THEMES__ = [
  {
    "dark": true,
    "force": true,
    "title": "Custom",
    "name": "custom",
    "colors": {
      "background": "#2c2d2f",
      "surface": "#161718",
      "on-surface": "#ffffff",
      "surface-bright": "#333333",
      "surface-variant": "#7E4FE3",
      "on-surface-variant": "#f6f7e8",
      "card": "#171718",
      "table": "#1F2022",
      "button": "#1D1E1F",
      "switch": "#101112",
      "primary": "#9E7BEA",
      "highlight": "#5F1DB7",
      "selected": "#4d4d4e",
      "secondary": "#191A1C",
      "secondary-light": "#1E2022",
      "accent": "#2D2E2E",
      "error": "#e57373",
      "info": "#00acc1",
      "success": "#4db6ac",
      "warning": "#ffd740",
      "favorite": "#FFD600",
      "remove": "#da4e4c",
      "restore": "#00d48a",
      "album": "#ed9e00",
      "download": "#00bfa5",
      "private": "#00b8d4",
      "edit": "#2196F3",
      "share": "#3F51B5",
      "love": "#ef5350",
      "terminal": "#4A464F",
      "navigation": "#141417",
      "navigation-home": "#0e0f10"
    },
    variables: {
      "btn-height": "34px",
      "table-row-height": "44px",
      "table-header-height": "44px",
      "border-color": "#FFFFFF",
      "border-opacity": 0.05,
      "high-emphasis-opacity": 0.96,
      "medium-emphasis-opacity": 0.88,
      "label-opacity": 0.67,
      "disabled-opacity": 0.75,
      "idle-opacity": 0.1,
      "fill-opacity": 0.04,
      "hover-opacity": 0.019,
      "focus-opacity": 0.022,
      "selected-opacity": 0.08,
      "activated-opacity": 0,
      "pressed-opacity": 0.16,
      "dragged-opacity": 0.08,
      "overlay-color": "#131313",
      "overlay-opacity": 0.54,
      "theme-kbd": "#212529",
      "theme-on-kbd": "#FFFFFF",
      "theme-code": "#343434",
      "theme-on-code": "#CCCCCC",
      "icon": "logo.svg"
    }
  }
];

This allows you to change the title and colors of the theme according to your preferences. For light theme colors, set the “dark” property to false. You can also set “force” to false to let the user decide whether to use the custom theme or one of the built-in themes. The login screen theme can be overridden by additionally specifying a theme named “login” in the __THEMES__ array.

The icon field sets the logo shown in the app and on the login screen. Specify the file name of an image placed in your theme folder, for example logo.svg for config/theme/logo.svg; PhotoPrism resolves it relative to the theme directory and automatically prefixes it with the site’s base URL, so the logo also loads when the app is served under a sub-path, such as in a multi-instance cluster. A root-relative /_theme/... path or an absolute URL, for example a link to an external CDN, can be used as well.

Adding a Favicon

To set a custom favicon, you can simply add a suitable PNG image with the filename config/theme/favicon.png to your theme in the storage folder. It will be automatically detected and included in the generated page headers and web application manifest.

Changing UI Styles

In addition to customizing the basic theme colors and setting a favicon image, you can further customize the look of the user interface by setting custom CSS styles in a config/theme/app.css file located in the storage folder. Examples can be found in our public project repository.

This allows you to customize almost every detail of the app’s appearance. We just ask that you do not remove, obscure, or alter any copyright notices or PhotoPrism’s names, trademarks, hyperlinks, or other designations displayed in the Software as set forth in the license agreement.

Any additional assets you need for your styles can also be placed in the theme folder. Since app.css is served from this folder, reference them with a relative URL, for example url(logo.svg) or url(./background.jpg), so that they resolve correctly whether PhotoPrism is hosted at the site root or under a sub-path, as in a multi-instance cluster.

Customizing the Login Screen

The login screen theme can be overridden by specifying a theme named “login” in the __THEMES__ array shown above. Its colors style the login page, and its icon field sets the logo shown there independently of the in-app logo. To change the login screen background, set the PHOTOPRISM_WALLPAPER_URI config option to the file name of an image in your theme folder or to an external image URL.

Using Custom Fonts

By default, the PhotoPrism UI is optimized for rendering performance and thus uses the operating system font, so the browser does not need to wait for fonts to download. This approach also provides the best integration with native apps that typically use the default Windows, Android, iOS, or macOS font.

If you want to set a custom font for all users, we recommend testing the application for side effects, as we have observed alignment issues with some fonts in the past.

Getting a Branded Theme

Our team will be happy to create a branded theme for you based on the colors of a style guide or an existing website. In order for us to create the theme, we ask that you provide us with all assets and materials to be used. If you would like additional changes, such as a custom font or layout changes, please contact us for a custom quote.

Config Options

The following is a list of config options that can affect the user interface, for example by changing background images, icons, and links:

PhotoPrism® Documentation

For more information on specific features, services and related resources, please refer to the other documentation available in our Knowledge Base and User Guide:

• PhotoPrism® User Guide
• PhotoPrism® Knowledge Base
• PhotoPrism® Pro Knowledge Base