Background effects

A background effect is an animation under the text of the hero: a starry sky, a grid, waves and others. The effect replaces a background image, so nothing needs to be redrawn for the site’s other languages. The text over the effect stays ordinary page text: it can be selected, translated and found by search.

SIMAI Framework draws the effects and takes them from the SIMAI effect catalogue. Docara only records in the Hero which effect is needed and checks the settings at build time.

How to add an effect

1. Connect the catalogue

The catalogue is set once for the whole site in docara.json:

{
  "effects": {
    "catalogue": "https://cdn.jsdelivr.net/gh/simai/ui-effects@264cb2efc182fd7af6bc273bdcc3006f1588af18/"
  }
}

catalogue is the catalogue address. Pin it to a specific commit, not to a branch (@main): otherwise the effects on your site may change without your knowledge. This site connects the catalogue at the address above.

Two more fields are optional:

2. Choose an effect

All the catalogue’s effects, how they look and their settings are collected on effects.simai.io. You can also tune the settings there and copy them. Docara does not download the catalogue during the build, so the full list of effects is kept on that site, not here.

Note the effect’s identifier: lowercase Latin letters, digits and hyphens, for example constellation-net or aurora-curtain.

3. Set the effect in the Hero

:::hero {layout=centered effect=constellation-net}
# Documentation that is easy to read

The effect is drawn under the text and does not get in the way of reading.
:::

The home page of this site opens with another effect, “Chladni figures” (chladni), and its Hero has a large padding=2xl. An effect works with any Hero variant, but not with a background image: set either effect or media=background.

Parameters

:::hero {layout=centered effect=aurora-curtain effect_theme=dark effect_settings='{"speed": 80}'}
# A dark hero

The effect is always drawn in its dark version, and the text becomes light.
:::

Effect theme

With effect_theme=auto the effect follows the page theme: when the reader switches the theme, the effect switches too. With dark or light the effect always stays in one version, and the Hero text adapts to it. While the effect loads, the Hero already has the background and text colour of that theme, so the text is readable at once.

If the effect lacks the needed version, for example it only has a dark one and the page is light, the effect is not shown, and the Hero looks as it would without an effect.

More effects

Below are three more effects from this site’s catalogue. Each has a light and a dark version: switch the site theme and the effect changes with it. An effect moves only while it is visible on the screen and is not drawn at all in a hidden tab.

:::hero {layout=compact effect=hex-conduits}
# Light conduits

Light pulses run across a hexagonal grid.
:::

:::hero {layout=compact effect=glyph-tide effect_settings='{"charset": "binary"}'}
# Glyph tide

A wave of characters. The `charset` setting picks binary characters instead
of hexadecimal ones.
:::

:::hero {layout=compact effect=contour-map}
# Contour lines

Elevation lines, as on a topographic map.
:::

All the catalogue’s effects and their settings are shown on effects.simai.io.

Pause and reduced motion

While the effect moves, the bottom right corner of the Hero (the left one in right-to-left languages) has a “Pause background animation” button. It does not cover the text or the image, even on a phone. Pressing it again starts the effect again. The choice is remembered in the reader’s browser for the whole site.

The button fits into the Hero’s bottom padding. With padding=2xl the Hero height does not change. With lg and xl the bottom padding of a Hero with an effect becomes slightly larger: 52 px on a narrow screen and 56 px from 960 px.

If the reader’s system has reduced motion turned on, the effect shows a single still frame, and the button does not appear.

The button labels come from the effects.pause and effects.play strings of the lang.json file. They are built in for English and Russian; for another language set them as described in the lang.json interface labels reference.

Where the effect will not be drawn

A site with an effect stays static, but the effect loads from the catalogue in the reader’s browser. The effect does not appear, and the Hero looks as it would without it, if:

• the browser cannot download the catalogue files, for example the reader is offline;
• the effect file does not match the checksum in the catalogue list;
• the effect has no version for the needed theme;
• the site is built with a SIMAI Framework version without effect support (earlier than ui-08c07b3e938a). Docara ships with a suitable version.

Why the effect was not drawn is visible in the browser’s developer tools: the Hero section’s data-sf-effect-state attribute is refused or failed, and data-sf-effect-reason holds the reason, for example fetch-failed or integrity.

Content-Security-Policy

Docara does not set a Content-Security-Policy header. If your hosting adds one, allow in it what the effect needs:

Without these permissions the browser blocks the effect, and the Hero stays without it.

Build errors

The build stops if an effect is set incorrectly. The cause and the fix for each error are in the reference: page errors and site settings errors.