Theme data

Read this when you need the merchant's brand colours, font or theme settings in a component, and you want to know exactly what the object holds.

The theme object is what the store's store/settings response calls theme. The engine loads it once, puts it in the provider at the root of the app, and hands it to your components in two ways.

The text direction of the current language is a separate thing: see useTranslation.

Read a setting and a colourCopy Anchor Link

import { useTheme } from '@salla.sa/twilight-theme-engine/hooks/useTheme';

export function PromoBar({ children }: { children: React.ReactNode }) {
  const { color, settings } = useTheme();

  // `!== false`: a store that never saved the setting has no value, and that should mean "on".
  if (settings.header_is_sticky === false) return null;

  return <div style={{ background: color.primary, color: color.reverse_text }}>{children}</div>;
}

The same values through the provider:

import { useTwilight } from '@salla.sa/twilight-theme-engine/providers';

const { theme } = useTwilight();
theme.mode; // 'live'
theme.settings.header_is_sticky; // true

The full objectCopy Anchor Link

This is the real theme of the public demo store (1510890315), trimmed. Search it, or click a key to copy its path.

FieldsCopy Anchor Link

The tables are generated from Theme in @salla.sa/twilight-theme-engine/types. color, font and settings get their own tables.

profileCopy Anchor Link

colorCopy Anchor Link

settingsCopy Anchor Link

settings.fontCopy Anchor Link

customizationCopy Anchor Link

twilightCopy Anchor Link

fontCopy Anchor Link

Same fields as settings.font.

settings holds every merchant-editable value, flat, keyed by the id you declared in twilight.json. The engine types only the keys the reference theme uses. A store's settings can hold more keys than the type lists, so read only the keys you declared.

Settings the engine reads itself (footer_is_dark, footer_layout, topnav_is_dark, sticky_add_to_cart, slider_background_size, header_is_sticky) work even when your theme never reads them.

Features and home blocksCopy Anchor Link

• features (such as "mega-menu", "fonts") are declared in twilight.json for the dashboard. They are not part of the runtime theme object: you cannot read them from useTheme.
• Home blocks are loaded by the home route, not read from the theme. A block's values reach your component as a data prop. See Add a home block.

How CSS gets its valuesCopy Anchor Link

When the page mounts in the browser, the engine copies the theme onto the root element as CSS variables, so styles need no JavaScript:

See Styling.

From twilight.json to a valueCopy Anchor Link

You declare a setting once in twilight.json (Settings guide). The merchant picks a value in the dashboard, and the key appears in theme.settings under the same id.

{ "id": "header_is_sticky", "type": "boolean", "format": "switch", "value": true }

settings.header_is_sticky; // true  (a plain boolean)

static entries (titles, lines, descriptions) only decorate the dashboard and have no runtime value. Entries typed collection and variable-list belong to home block fields.

Common tasksCopy Anchor Link

A boolean that defaults to on:

const sticky = useTheme().settings.header_is_sticky !== false;

A dropdown value, from a string or [{ value }]:

function dropdownValue(raw: unknown): string | undefined {
  const first = Array.isArray(raw) ? raw[0] : raw;
  return typeof first === 'string' ? first : (first as { value?: string } | undefined)?.value;
}
const fit = dropdownValue(settings.slider_background_size) ?? 'cover';

A colour in an inline style, with readable text on top:

const { color } = useTheme();
<button style={{ background: color.primary, color: color.reverse_text }}>Buy</button>;

The font name, safely:

const { font } = useTheme();
const family = font?.name ?? 'inherit';

Direction:

const { isRTL } = useTheme();
<div dir={isRTL ? 'rtl' : 'ltr'} />;

GotchasCopy Anchor Link

• Value shapes differ per widget. A switch is a boolean, a dropdown is the chosen value. Check the shape before using it.
• A dropdown can be a string or [{ value }]. product_card_img_ratio is typed to allow both. Normalise with a helper like the one above.
• Settings can be undefined. Until the merchant saves, a key may be missing. Test !== false for "on by default".
• font is optional, and settings.font is a different object (with family_name). useTheme().font is the font field.
• CSS variables are set in the browser. The engine writes them when the page mounts, so on the server render they are not there yet. The theme object itself is available on the server and the client.
• --color-text is #222222, not color.text. Read color.text from the hook when you need it.
• isRTL is the theme's direction. Use useTranslation for the direction of the current language.

NextCopy Anchor Link

• Settings guide: declare settings in twilight.json.
• useTheme: the hook's API.
• Store data: the store object next to the theme.
• Styling: use the colours and fonts in CSS.