Styling individual guidance messages

Every guidance message the SDK renders carries a data-guidance-code attribute naming which message it is. That gives you a CSS hook to restyle one specific message — colour it, add an icon, change its weight — without the SDK having to ship an opinion about which messages count as “errors” and which are routine status.

<div class="idm-pill" data-guidance-code="GLARE">
  Please reduce glare on the document
</div>

Your theme’s guidanceMessages colours still apply exactly as before. This attribute is purely additive: it changes nothing until you write a rule against it.

Making your rules win

The guidance pill’s background comes from a styled-components class, which has the same CSS specificity as a bare attribute selector. Because those styles are injected at runtime, they land after your stylesheet in the cascade. So this looks correct and does nothing at all:

/* Same specificity as the SDK's own rule, and loses on source order. */
[data-guidance-code="GLARE"] {
  background: #b26b00;
}

Pair the attribute with a class name you already pass to the SDK. Two selectors beat one, so your rule wins cleanly and you do not need !important:

<IdValidation classNames={{ guidanceMessage: "idm-pill" }} />

/* Specificity 0,2,0 — outranks the SDK's class. */
.idm-pill[data-guidance-code="GLARE"] {
  background: #b26b00;
  color: white;
}

The exact path to the class name prop differs per flow and per stage — check the Class names table for the flow you are using. The guidance pill is guidanceMessage.

Grouping messages by severity

There is deliberately no severity attribute. If the SDK shipped its own grouping, then changing our mind about a bucket later would silently restyle your integration. CSS already groups things perfectly well, and in your stylesheet the categorisation stays under your control.

/* Warnings: the shot is being spoiled — change your grip or your environment. */
.idm-pill[data-guidance-code="FINGER_OCCLUSION"],
.idm-pill[data-guidance-code="GLARE"],
.idm-pill[data-guidance-code="HOLOGRAM_REFLECTION"],
.idm-pill[data-guidance-code="OUT_OF_FOCUS"] {
  background: var(--idm-color-warning-400);
  color: white;
}
 
/* Errors: you cannot proceed with what you are currently holding. */
.idm-pill[data-guidance-code="ID_CARD_NOT_ALLOWED"],
.idm-pill[data-guidance-code="PASSPORT_NOT_ALLOWED"] {
  background: var(--idm-color-negative-600);
  color: white;
}
 
/* Face capture: poor lighting is a warning, not a status update. */
.idm-pill[data-guidance-code="VISIBILITY_TOO_LOW"] {
  background: var(--idm-color-warning-400);
  color: white;
}

Stability guarantee

The code vocabulary is append-only. We will add codes as we add messages, but we will never rename, remove, or repurpose an existing one. Your selectors are not type-checked against our source, so a rename would fail silently in your production integration rather than loudly at build time. This guarantee is enforced by a test in the SDK’s own build.

The text a code maps to is not frozen. Messages get reworded, and they are translated into nine locales. Never key styling off the message text itself.

Reference

The code always names the message actually on screen, not the internal state that produced it. Where no message is displayed, no attribute is emitted.

ID capture

HOLD_STILL covers all four detected-document variants (ID front, ID back, passport, and single page) — the document type is interpolated into the text, so one code serves them all.

The two BARCODE_* codes only appear during barcode re-capture, which runs after an ID card back capture and only when enableBarcodeRecapture is switched on. They never appear during an ID front or passport scan. They also render in the guide box header rather than in the pill, so pair them with the guides’ instruction class name rather than guidanceMessage.

Face capture — guidance

Face capture — liveness and challenge

The challenge prompts render with your theme’s positive colours by default, because the challenge is only ever entered from an already-satisfied face. If you would rather they read as neutral status, restyle them by code.

Signature capture

Video ID capture