thumbsup logo thumbsup

A theme is simply a folder following a given structure.

  |__ album.hbs    # main view
  |__ theme.less   # stylesheets
  |__ partials     # optional Handlebars partials
  |__ helpers      # optional JS helpers
  |__ public       # optional static files

It can be loaded using:

--theme-path file://path/to/theme

To submit a theme to be built-in, please raise an issue on Github here.

About build processes

Thumbsup doesn’t install any dependencies (or run any build steps) when loading a theme from disk. If your theme has a build process, you can either:

For example, your Git repo might look like:

|__ package.json
|__ src   # raw files
|__ dist  # result of the build process, typically git-ignored

Because npm publish will publish files relative to the root folder, you must include the following entry in package.json:

  "name": "my-thumbsup-theme",
  "thumbsup": {
    "themeRoot": "dist"


This Handlebars template will be called for every album in the gallery, including the root album. It should typically render thumbnails for every entry in the album, as well as links to nested albums if applicable.

{{#with album}}

  <h2>Nested albums</h2>
  {{#each albums}}
    <a href="{{relative url}}">{{title}}</a>

  <h2>Photos and videos</h2>
  {{#each files}}
    <a href="{{relative urls.large}}">{{filename}}</a>


The data available to render is described on the data-model page. It’s also a good idea to read the thumbsup source-code to get familiar with any subtleties.

Like in the example above, make sure to use the built-in relative helper when using URLs.


This is the entry point for all your theme’s styles.

h1 {
  color: #2070ee;

Some notes:

To make your theme configurable, you should use LESS variables for key elements like colors or sizes. For example:

@highlight: #17baef;

h1 {
  color: @highlight;

This will allow users to specify their own highlight color using:

thumbsup --theme-path ./your-theme --theme-style custom.less
// custom.less
@highlight: #ed124d;


Just like you can expose LESS variables for customising styles, you can expose HBS variables for customising behaviour. The user will have to create a JSON file and specify --theme-settings file.json.

  "notify": true,
  "message": "hello"

You can then use these attributes like this:

<!-- At the root of your HBS template -->
{{#if settings.notify}} {{settings.message}} {{/if}}

<!-- Or somewhere within a loop -->
{{#each albums}}
   {{#if @root.settings.notify}}

Don’t forget to document these settings in the theme’s README.


Thumbsup automatically loads any .hbs partials in the partials folder. These are available in your view as {% raw %}{{>filename}}. You can pass data to a partial using the {{>filename arg1, arg2}} syntax.

  |__ caption.hbs
<!-- caption.hbs -->
<div>Photo caption</div>
<!-- album.hbs -->
{{> caption}}


Thumbsup automatically loads JavaScript helpers from the helpers folder. Each helper is available in the views using {{name}} for inline helpers, or {{#name}} for block helpers. You can pass data to a helper using the {{name arg1, arg2}} syntax.

  |__ hello.js
// hello.js
module.exports = name => {
  return `hello ${name}`
<!-- album.hbs -->
  {{hello world}}


Every theme typically depends on extra static assets such as JavaScript files or images. The content of the public folder is copied as-is to the final gallery, on top of defaults assets bundled by thumbsup.

  |__ album.hbs
  |__ public
     |__ cool.js
     |__ dragon.jpg