Advanced UI

The sheet ships styled, responsive, and accessible, and most integrations never change it. Reach for appearance when the sheet has to sit inside your brand: your palette on the surfaces, your typography on the headline, or your own element where the SDK’s button was. Every field is optional, and omitting appearance entirely renders exactly the default sheet. Nothing on this page is required for a working integration. appearance is a per-presentation option on PlacementOptions:

import Encore from '@encorekit/web-sdk';

const result = await Encore.placement('milestone_reached', {
  useCase: 'rewardUsers',
  appearance: { accentColor: '#0A6' },
}).show();

The two tiers

The config has two tiers, and they compose. Theme colors set the SDK’s CSS custom properties, so one value repaints everything derived from it: muted text, secondary surfaces, focus rings.

Field	What it moves
`backgroundColor`	The sheet’s canvas, and every surface derived from it.
`textColor`	The primary ink, from which muted and secondary text are derived.
`accentColor`	Focus rings, links, and the Reduce Churn CTA.
`modalBackgroundColor`	The modal container only. Narrower than `backgroundColor`: use it to repaint the sheet and nothing else.

Reward sheet overrides replace or restyle one element each. They are read by the 'rewardUsers' composition, the one with a headline block, a CTA pair, and page dots. 'reduceChurn' renders the bare carousel and honors the theme colors and modalBackgroundColor only.

Field	Kind	What it fills
`headline`	slot	The reward sheet’s primary heading.
`subheadline`	slot	The line under it.
`claimButton`	slot	The “Claim gift” CTA. The SDK keeps the action.
`declineButton`	slot	The “No thanks” button. The SDK keeps the action.
`dotColor`	color	The page indicator’s inactive dots.
`dotActiveColor`	color	The page indicator’s active dot.

The three slot forms

Each slot (headline, subheadline, claimButton, declineButton) takes one of three forms. Pick the cheapest one that does the job.

type TextSlot   = TextAppearance   | HTMLElement | AppearanceRenderer;
type ButtonSlot = ButtonAppearance | HTMLElement | AppearanceRenderer;
type AppearanceRenderer = (context: AppearanceSlotContext) => HTMLElement | null | undefined;

All of these are exported from @encorekit/web-sdk, so a TypeScript integration can type against them directly.

A styled config object

The most common case: custom copy, font, and color, with no DOM knowledge required. The SDK keeps its own element, and with it every default style and accessibility attribute, and applies your values on top.

import Encore from '@encorekit/web-sdk';

await Encore.placement('milestone_reached', {
  useCase: 'rewardUsers',
  appearance: {
    modalBackgroundColor: '#101014',
    dotColor: '#3A3A44',
    dotActiveColor: '#FFD166',
    headline: {
      text: 'Nice work, Sam!',
      color: '#FFD166',
      fontFamily: '"Helvetica Neue", Arial, sans-serif',
      fontSize: '28px',
      fontWeight: 700,
    },
    claimButton: {
      backgroundColor: '#FFD166',
      color: '#101014',
      borderRadius: '999px',
    },
  },
}).show();

Text slots accept text, color, fontFamily, fontSize, fontWeight, letterSpacing, and textAlign. Button slots accept the same fields plus backgroundColor, borderColor, and borderRadius. A text value that is blank or whitespace-only falls through to the copy Encore resolved rather than blanking the slot, the same rule PlacementOptions.headline follows; a non-blank text beats it.

A ready element

Hand the slot an HTMLElement to render something that is not text at all. The SDK mounts your element inside its own semantic element, which keeps the heading’s id and the sheet’s accessible name intact.

import Encore from '@encorekit/web-sdk';

const badge = document.createElement('div');
badge.className = 'streak-badge';
badge.append('🔥 5-week streak');

await Encore.placement('milestone_reached', {
  useCase: 'rewardUsers',
  appearance: { subheadline: badge },
}).show();

Build a fresh element per slot and per presentation. One element can fill only one slot: supplying the same element twice keeps the SDK’s default for the second one.

A renderer

A (context) => HTMLElement function runs per presentation with the SDK’s context in hand:

Context field	What it carries
`text`	The copy the SDK resolved for this slot, after its full fallback chain.
`useCase`	Why the sheet is presenting.
`defaultElement`	The element the SDK would have rendered.

Return an element to replace the default, return defaultElement (mutated) to decorate it, or return null to keep the default as is.

import Encore from '@encorekit/web-sdk';

await Encore.placement('milestone_reached', {
  useCase: 'rewardUsers',
  appearance: {
    // Replace: build your own CTA around the copy the SDK resolved.
    claimButton: ({ text }) => {
      const el = document.createElement('span');
      el.className = 'my-cta';
      el.textContent = text;
      return el;
    },
    // Decorate: keep the SDK's element, styles, and accessibility wiring.
    declineButton: ({ defaultElement }) => {
      defaultElement.classList.add('my-ghost-button');
      return defaultElement;
    },
  },
}).show();

What you can rely on

Omitting appearance changes nothing. The sheet renders exactly what it rendered before this config existed, byte for byte.
The SDK keeps the action. On claimButton and declineButton you supply appearance only. Your element is mounted inside an SDK-owned control that carries the role, the tab stop, and the listener; the listener runs in the capture phase, so the SDK’s claim or decline behavior runs first and a handler you attached to your own element does not run at all. React to the outcome through show()’s resolved ShowResult, never through your own click handlers.
The SDK also keeps the gate. Because the claim is the SDK’s, so is whether it is available: turning Encore.isClaimEnabled off makes your claim button unavailable along with everything else. Your element’s host carries aria-disabled="true" rather than the native disabled attribute, which means nothing outside a <button>. Target both forms if you style the unavailable state yourself.
A bad override costs you the override, never the sheet. Every renderer runs inside a guard, and every color, font, and size goes through an allow-list. A throw, a non-element return, or a malformed value falls back to the SDK’s default element. Nothing you pass can take down the modal or the host page.
'reduceChurn' is theme-only. The bare carousel honors backgroundColor, textColor, accentColor, and modalBackgroundColor; the slot fields and dot colors are read by the 'rewardUsers' composition.
Accessibility survives your override. The SDK keeps its semantic elements, so the sheet’s accessible name and single tab stop per control are preserved. A custom element with no text content is announced with the copy the SDK resolved for that slot.

Troubleshooting

A color, font, or size is not applying. Values go through an allow-list, and a rejected value is dropped whole rather than half-applied: the sheet keeps its default and nothing breaks. Accepted colors are hex values, the CSS color functions (including wide-gamut ones such as oklch(), with no nested functions), named colors, and var(--your-property) with a simple fallback. Font stacks accept unaccented family names, quotes, and commas, so a family name with accented characters is rejected; to use one, take the element or renderer form and style your own element with your own CSS; the allow-list applies only to config values. Lengths need an explicit unit (28px, 1.75rem, 100%); a number with no unit is rejected, except 0. The rejection is logged as [Encore SDK] Ignoring unsupported … appearance value, but SDK logging is off by default: pass logLevel: 'debug' to configure() while integrating, or a dropped value looks like a silent no-op. A renderer throws. The sheet still presents, with the SDK’s default element in that slot, and a warning is logged at the same debug-gated level. A render bug costs you the custom styling for one slot, never the presentation. A slot override shows no effect. Check the placement’s use case: the slot fields and dot colors render only on 'rewardUsers'. On 'reduceChurn', use the theme colors.

placement(): the full PlacementOptions contract this config sits in.
Post-Purchase Placements: the reward placement pattern end to end.
show(): the result statuses, including how to react to a claim.
configure(): logLevel: 'debug' for the appearance warnings on this page.
isClaimEnabled: turning the claim off, which applies to a custom claim button too.

iOS

Android

Web

Bridges

The two tiers

The three slot forms

A styled config object

A ready element

A renderer

What you can rely on

Troubleshooting

​The two tiers

​The three slot forms

​A styled config object

​A ready element

​A renderer

​What you can rely on

​Troubleshooting

​Related

The two tiers

The three slot forms

A styled config object

A ready element

A renderer

What you can rely on

Troubleshooting

Related