Customization

This page is the consumer guide for host applications that need to customize the embedded consent screen. Customization is optional.

When to enable host configuration

Use the default integration when the host only needs to display and submit consents. Add enableCustomConfig=true only when the host needs to send JSON configuration before the component renders.

enableCustomConfig does not select between Legacy and Custom components. The runtime always uses the current Custom UI path.

Configuration handshake

Host loads iframe/WebView with ?enableCustomConfig=true
  -> mas-consents initializes the bridge
  -> mas-consents sends CONSENTS_CONFIG_REQUIRED
  -> host replies with SET_CONFIG { payload: ... }
  -> mas-consents sanitizes invalid design overrides
  -> mas-consents builds the theme and renders
  -> mas-consents fetches consents
  -> mas-consents emits CONSENTS_LOADED
  -> customer submits
  -> mas-consents emits CONSENTS_COMPLETED or CONSENTS_ERROR

If enableCustomConfig=true is present and the host never sends SET_CONFIG, the component intentionally renders nothing.

SET_CONFIG payload

The host sends configuration in the payload key of the SET_CONFIG message. These are the supported top-level keys inside payload; all of them are optional.

{
  "type": "SET_CONFIG",
  "payload": {
    "theme": "light",
    "design": {},
    "uiOptions": {},
    "useMockData": false,
    "consentIds": ["C01", "C02"]
  }
}

Minimal example:

{
  "type": "SET_CONFIG",
  "payload": {
    "theme": "light"
  }
}

Fuller example:

{
  "type": "SET_CONFIG",
  "payload": {
    "theme": "light",
    "consentIds": ["C01", "C02"],
    "design": {
      "tokens": {
        "container-background-color": "base.primary",
        "footer-button-background-color": "#3466F5",
        "footer-button-radius": "md",
        "title-typography": {
          "style": "h4",
          "mobile": {
            "style": "h5",
            "family": "Menlo"
          }
        }
      }
    },
    "uiOptions": {
      "groupDisplay": "flat",
      "collapsible": true,
      "showDescription": true
    }
  }
}

design options

Put visual overrides under payload.design.tokens. Each key is a public domain token that represents one concrete use in Consents.

{
  "type": "SET_CONFIG",
  "payload": {
    "design": {
      "tokens": {
        "component-background-color": "primary",
        "global-padding-x": "base",
        "statement-help-icon-size": "500"
      }
    }
  }
}

The canonical resolver accepts these values:

Prefer the short references shown by the editor, such as primary, red.700, sm, 400, thin, md or 2. Compatible fully qualified DS paths remain accepted.

Semantic color and shadow paths are normalized to the active light or dark mode. Typography semantic paths are normalized to the active desktop or mobile breakpoint. Unsupported paths and unknown domain token names are ignored, and the default remains in use.

See Domain tokens for the public catalog.

Responsive typography

A typography domain token can select a complete DS style in one value:

{
  "design": {
    "tokens": {
      "footer-button-typography": "md"
    }
  }
}

Use the object form to change the family or specialize desktop and mobile. Global values apply to both breakpoints, and desktop or mobile takes precedence for its mode.

{
  "design": {
    "tokens": {
      "title-typography": {
        "style": "h4",
        "family": "Inter",
        "desktop": {
          "style": "h3"
        },
        "mobile": {
          "style": "h5",
          "family": "Menlo"
        }
      }
    }
  }
}

The canonical API only allows family to be overridden. Size, weight, line height and letter spacing are always resolved from the complete style. The title accepts h1 through h6; the footer button accepts base, md and xs; all other typography tokens accept complete body styles.

Validation and fallback behavior

When the host sends SET_CONFIG, the runtime sanitizes token overrides before building the theme. Validation rules, limits and fallback values are documented in Token validations.

uiOptions

uiOptions adjusts presentation and selected interface behaviors without changing the consents or their business rules. Every option is optional.

Example using every option:

{
  "type": "SET_CONFIG",
  "payload": {
    "uiOptions": {
      "collapsible": true,
      "languageSelector": true,
      "showDescription": true,
      "descriptionsAlwaysVisible": false,
      "groupDisplay": "boxed",
      "title": "Consent management",
      "description": "Review and confirm your consent preferences."
    }
  }
}

Considerations:

• showDescription controls only the header description; descriptionsAlwaysVisible controls the consent descriptions.
• collapsible adds the expansion control only to parent consents that have children. If validation finds an incomplete required child consent, its group expands automatically to make it visible.
• With descriptionsAlwaysVisible=false, expanding a collapsible group also displays the parent consent description inline.
• The language selector offers only the languages enabled by the runtime configuration.
• Custom title and description values are literal text and are not translated automatically when the language changes.
• groupDisplay changes only visual composition; it does not alter consent hierarchy, ordering or editability.

consentIds

consentIds lets a host request a specific subset of consents.

{
  "type": "SET_CONFIG",
  "payload": {
    "consentIds": ["C01", "C02", "C03"]
  }
}

Behavior:

• the host sends consentIds in SET_CONFIG
• the frontend forwards it as consent_ids=C01,C02,C03 on the GET consents request
• the backend decides which returned consents are editable and which are returned as read_only=true
• read-only statements remain visible but cannot be changed by the customer

useMockData

useMockData is intended for local and STA validation only.

{
  "type": "SET_CONFIG",
  "payload": {
    "useMockData": true
  }
}

Behavior:

• the runtime uses mock consent data instead of calling the backend
• this is honored only when runtime ENV is LOCAL or STA
• in PRO, the flag is ignored

Minimal browser host example

const iframe = document.querySelector<HTMLIFrameElement>('#mas-consents')
const consentsOrigin = new URL(iframe?.src ?? 'https://consents.masstack.com').origin

window.addEventListener('message', (event) => {
  if (event.origin !== consentsOrigin) return

  const msg = event.data
  if (msg?.source !== 'consents') return

  if (msg.type === 'CONSENTS_CONFIG_REQUIRED') {
    iframe?.contentWindow?.postMessage(
      {
        type: 'SET_CONFIG',
        payload: {
          theme: 'light',
          consentIds: ['C01', 'C02'],
          design: {
            tokens: {
              'footer-button-background-color': '#3466F5',
            },
          },
          uiOptions: {
            groupDisplay: 'flat',
            collapsible: true,
          },
        },
      },
      '*',
    )
  }
})

Legacy customization system

Consents has adopted a domain token system to align its public customization API with the current MasStack Design System. All new configurations and migrations must use design.tokens.

Values from the former category-based contract are deprecated. The runtime continues to resolve them only to preserve backwards compatibility and avoid breaking existing integrations; this support does not mean they should be used in new implementations.