How it works

• The theme is a block like any other: it has instances, translations, segment targeting, a schedule and A/B tests (see Blocks: types, instances, collections). The first eligible instance for the device is the theme.
• Colours are values, not a field type. The dashboard has no colour field type: use text fields. A field declared with any other type is stored and delivered, but the Dynamic Blocks editor shows it as an unsupported field that can't be edited.
• The JavaScript helpers parse #rgb, #rgba, #rrggbb, #rrggbbaa, and rgb() / rgba() in comma or space form, with channels as 0–255 or percentages. Anything else reads as "no colour" and the fallback is used; they never throw.
• Reading a theme records no impression: it isn't the same as showing the block's content.

Define the theme block

Register the block type once from a server or CI job with the write key (never from the app); see Blocks and fields: register one block type. Marketers then edit its instance in Dynamic Blocks and publish it like any other content.

curl -X POST https://api.contentflow.click/sdk/v1/cards/register \
  -H "X-CF-Write-Key: $CF_WRITE_KEY" -H 'Content-Type: application/json' \
  -d '{
    "key": "brand_theme",
    "name": "Brand theme",
    "screen": "App-wide",
    "fields": [
      { "id": "primary", "tag": "#brand_primary", "type": "text", "label": "Primary colour (#rrggbb)" },
      { "id": "accent",  "tag": "#brand_accent",  "type": "text", "label": "Accent colour (#rrggbb)" }
    ],
    "blank": { "primary": "#5b57e0", "accent": "#f0654a" }
  }'

Tags ending in _color or _colour, or starting with #color_, are also picked up by getBlockColors (see API reference). Any tag works with getBlockColor, themeFromBlock and useCFTheme.

Read the theme

import { themeFromBlock } from '@contentflow/sdk/web';

// 1. Map each theme slot to the tag that carries it, with a bundled fallback per slot.
const MAPPING = { primary: '#brand_primary', accent: '#brand_accent' };
const FALLBACK = { primary: '#5b57e0', accent: '#f0654a' };

// 2. Read the brand_theme block (undefined until it is delivered) and resolve the colours.
function applyTheme() {
  const theme = themeFromBlock(client.getBlock('brand_theme'), MAPPING, FALLBACK);
  const root = document.documentElement.style;
  root.setProperty('--brand-primary', theme.colors.primary?.hex ?? FALLBACK.primary);
  root.setProperty('--brand-accent', theme.colors.accent?.hex ?? FALLBACK.accent);
}

// 3. Apply it now, and again whenever content changes.
applyTheme();
client.subscribe(applyTheme);

import { useCFTheme } from '@contentflow/sdk/react';

function AppShell({ children }: { children: React.ReactNode }) {
  // 1-2. Map slots to tags, with a fallback per slot. Re-renders when the block changes (step 3).
  const { theme } = useCFTheme(
    'brand_theme',
    { primary: '#brand_primary', accent: '#brand_accent' },
    { fallback: { primary: '#5b57e0', accent: '#f0654a' } },
  );
  // theme.colors.* has a value even before the block arrives, thanks to the fallback.
  const style = { '--brand-primary': theme.colors.primary?.hex, '--brand-accent': theme.colors.accent?.hex } as React.CSSProperties;
  return <div style={style}>{children}</div>;
}

import { View } from 'react-native';
import { useCFTheme } from '@contentflow/sdk/react-native';

function Header() {
  // 1-2. Map slots to tags, with a fallback per slot. Re-renders when the block changes (step 3).
  const { theme } = useCFTheme('brand_theme', { primary: '#brand_primary' }, {
    fallback: { primary: '#5b57e0' },
  });
  return <View style={{ backgroundColor: theme.colors.primary?.hex ?? '#5b57e0', height: 56 }} />;
}

// 1. A bundled fallback per slot.
let fallbackPrimary = "#5b57e0"

// 2. Read the brand_theme block (nil until delivered) and its colour field as text.
let block = try await client.fetchBlock(key: "brand_theme")
let primaryHex = (try? block?.value(for: FieldKey<String>.text("#brand_primary"))) ?? fallbackPrimary

// 3. Parse it with your own hex helper (SwiftUI and UIKit have no hex initialiser),
//    and read again when the block changes (client.blockState(for: "brand_theme")).
let primary = Color(hex: primaryHex) ?? Color(hex: fallbackPrimary)!

// 1. A bundled fallback per slot.
const val FALLBACK_PRIMARY = "#5b57e0"

// 2. Read the brand_theme block (null until delivered) and its colour field as text. From a coroutine.
val block = client.fetchBlock("brand_theme")
val primaryHex = block?.value(FieldKeys.text("#brand_primary")) ?: FALLBACK_PRIMARY

// 3. Parse it (Android reads 8 digits as #aarrggbb), and read again when the block
//    changes (client.observeBlock("brand_theme")).
val primary = runCatching { android.graphics.Color.parseColor(primaryHex) }
    .getOrDefault(android.graphics.Color.parseColor(FALLBACK_PRIMARY))

final cf = ContentFlow.instance;

// 1. A bundled fallback per slot.
const fallbackPrimary = Color(0xFF5B57E0);

// 2. Read the brand_theme block (null until delivered) and its colour field as text.
final hex = cf.getBlock('brand_theme')?.field<String>('#brand_primary');

// 3. Parse #rrggbb yourself, and read again when the block changes
//    (cf.observeBlock('brand_theme', (block) => ...)).
final rgb = (hex != null && hex.length == 7) ? int.tryParse(hex.substring(1), radix: 16) : null;
final primary = rgb != null ? Color(0xFF000000 | rgb) : fallbackPrimary;

The JavaScript helpers are exported from @contentflow/sdk/web, /react, /react-native and /advanced; useCFTheme from /react and /react-native. They are not exported from the root @contentflow/sdk entry.

API reference (JavaScript)

Fallbacks and live updates

• First launch: until the first sync delivers the block, only your fallbacks apply. Paint with them; don't wait for the network.
• Later launches: the cached block paints first (see Blocks: refresh and offline).
• Changes: a published change reaches connected apps within about a second; useCFTheme re-renders, and plain JavaScript re-runs your subscribe callback.
• Per segment or season: target an instance to a segment, or schedule it (see Blocks: schedules). A hidden instance (#block_enabled false) is skipped by getBlock in JavaScript, so the fallbacks apply.

When it doesn't work

Next

• Dynamic blocks: publishing, targeting and scheduling the theme instance.
• Blocks and fields: field types: the field types the dashboard edits.