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.__THEME__ = {
  "dark": true,
  "force": true,
  "title": "Custom",
  "name": "custom",
  "colors": {
    "application": "#353535",
    "form": "#eeeeee",
    "card": "#424242",
    "primary": "#48c1f0",
    "primary-button": "#3a5f6d",
    "secondary-dark": "#48c1f0",
    "secondary": "#272727",
    "secondary-light": "#424242",
    "accent": "#333",
    "error": "#e57373",
    "info": "#00acc1",
    "success": "#4db6ac",
    "warning": "#ffd740",
    "remove": "#e57373",
    "restore": "#64b5f6",
    "album": "#ffab00",
    "download": "#00bfa5",
    "private": "#00b8d4",
    "edit": "#00b8d4",
    "share": "#9575cd",
    "love": "#ef5350",
    "terminal": "#4A464F",
    "navigation": "#141417",
    "navigation-home": "#0e0f10"

You can now change the theme title and colors 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 default themes.

When testing how the changes look, make sure to clear the browser cache and try the UI with different window sizes, as our UI styles are responsive. If you add custom styles, you should also ensure that they work with different resolutions and screen aspect ratios.

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 and then accessed via /_theme/[filename] in the frontend.

Customizing the Login Screen

The login form can optionally be customized with a welcome message by adding an HTML file with the filename config/theme/welcome.html to your theme. Note, however, that we take no responsibility for any layout or security issues this may cause.

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.

We generally do not take responsibility for performance or layout issues resulting from the use of custom fonts and styles.

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:

Environment CLI Flag Default Description
PHOTOPRISM_REGISTER_URI --register-uri user registration URI
PHOTOPRISM_PASSWORD_RESET_URI --password-reset-uri forgot password URI
PHOTOPRISM_DEFAULT_LOCALE --default-locale en standard user interface language CODE
PHOTOPRISM_DEFAULT_THEME --default-theme standard user interface theme NAME
PHOTOPRISM_APP_MODE --app-mode standalone progressive web app MODE (fullscreen, standalone, minimal-ui, browser)
PHOTOPRISM_APP_ICON --app-icon progressive web app ICON (logo, app, crisp, mint, bold) 
PHOTOPRISM_APP_NAME --app-name progressive web app NAME when installed on a device
PHOTOPRISM_LEGAL_INFO --legal-info legal information TEXT, displayed in the page footer 
PHOTOPRISM_LEGAL_URL --legal-url legal information URL
PHOTOPRISM_WALLPAPER_URI --wallpaper-uri login screen background image URI
PHOTOPRISM_SITE_AUTHOR --site-author site OWNER, copyright, or artist
PHOTOPRISM_SITE_CAPTION --site-caption AI-Powered Digital Asset Management site CAPTION
PHOTOPRISM_SITE_PREVIEW --site-preview sharing preview image URL

If you change global configuration values in your compose.yaml or docker-compose.yml file or in the Advanced Settings UI, a restart is required for these changes to take effect.

PhotoPrism® Documentation

For detailed information on specific product features, services, and related resources, see our Knowledge Base, or read the User Guide for help using the web user interface: