Form guide options

The snippet's attributes and attach() options, panel styles, icons, theme and wording.

Snippet attributes#

Add these to the paste-in <script> tag. They're read once, when the script starts. Attribute values are always text, so JSON values go in single quotes (see the examples).

Attribute What to put Default What it does
id="formguide-embed-script" exactly this (required) Tells the script to start by itself.
data-agent-id your agent id (required) The agent that answers. If it's missing, nothing happens and the console says so.
data-base-url https://subcontext.com https://subcontext.com Where Subcontext is. You can leave it out.
data-mode popover or inline popover How the help panel opens. See Panel styles.
data-primary-color a CSS colour, e.g. #0f766e #2563EB The icon's hover colour. In popover panels, also the send and Done buttons.
data-exclude a CSS selector, e.g. [name=newsletter] none Fields that match get no icon. A selector the browser can't read is ignored.
data-field-icon an icon name help-circle The icon shown beside each field. See Icons.
data-field-rules JSON none Which fields get icons. Same as fieldRules below, written as JSON, e.g. '{"mode":"blocklist","entries":[{"type":"field_name","pattern":"newsletter"}]}'
data-theme JSON, or light or dark none Colours, font, borders and heading for the panel. See Theme.
data-strings JSON English Replace the panel's wording, e.g. to translate it. See Wording.
data-enabled false on Start switched off. Nothing loads or shows until you call SubcontextFormGuide.enable().
data-remember-click-ids true or false Google Consent Mode Whether ad click ids from the page a visitor lands on may be kept in your website's browser storage for a later chat or form. See Ad clicks across pages.
data-debug true off Writes more detail to the browser console, for troubleshooting.

If the JSON in data-theme, data-strings or data-field-rules isn't valid, that attribute is ignored and the console shows a warning. The rest of the snippet still works.

attach() options#

Option What to put Default What it does
container an element on your page (required) The guide only looks at fields inside this element, including fields added to it later.
agentId your agent id (required) The agent that answers.
baseUrl 'https://subcontext.com' https://subcontext.com Where Subcontext is. You can leave it out.
mode 'popover' or 'inline' 'popover' How the help panel opens. See Panel styles.
primaryColor a CSS colour '#2563EB' Same as data-primary-color.
exclude a CSS selector none Same as data-exclude.
fieldIcon an icon name 'help-circle' Same as data-field-icon.
fieldRules an object none Which fields get icons. See Field rules.
theme an object, or 'light' or 'dark' none Colours, font, borders and heading. See Theme.
strings an object English Replace the panel's wording. See Wording.
enabled false true Load the agent but show nothing until you call enable() on the returned guide.
rememberClickIds true or false Google Consent Mode Same as data-remember-click-ids.
debug true false Writes more detail to the browser console.
applicationContext { id, share_token } none Links the chats to a Subcontext insurance application. See Linking to a quote.

All the settings are on your page. The dashboard has no form guide settings for look, mode, icon or which fields to include.

Panel styles: popover or inline#

Mode What the visitor sees How it closes
popover (default) A small floating panel next to the icon. Press Escape, or click anywhere outside it.
inline A panel that opens in the page, just below the question, pushing the content below it down. Press Escape, or click its close button.

Only one panel is open at a time.

Icons#

Choose the icon beside each field with fieldIcon or data-field-icon:

help-circle (default), info, sparkles, message-circle, lightbulb, bot, wand, zap, ai, cloud.

An unknown name falls back to help-circle. The same icon appears in the panel's header. If you don't choose one, the header shows sparkles.

Theme#

Pass theme to attach(), or put the same thing as JSON in data-theme. It takes the theme object every Subcontext embed shares (see Theming the embeds) and the panel keys below, in one object. Every key is optional. Values are ordinary CSS, applied only inside the help panel.

Shared keys#

Key Works in What it changes
primaryColor both The main colour: the field icons' hover colour, and in popover panels the header icon, the visitor's messages and the buttons. Wins over primaryColor and data-primary-color.
accentColor both Send and Done button background, unless you set buttonBackground.
backgroundColor both Panel background, unless you set background.
fontFamily both The panel's font. Load the font on your page yourself. Default: the visitor's system font.
fontSize both Size of the messages, the typing box and the Done button, in pixels. Default 13 (12 for the typing box and button in inline panels).
mode both 'dark' gives a dark panel with light text: dark background #1f1d1a (or your backgroundColor), dark typing box and light Done button in inline panels. Panel keys you set stay as you set them.

theme: 'dark' (or data-theme="dark") is short for { "mode": "dark" }. theme.mode (light or dark) is not the same as the form guide's own mode option (popover or inline).

Panel keys#

These win over the shared keys they overlap with (background over backgroundColor, buttonBackground over accentColor).

Key Works in What it changes
heading inline The panel's title (normally "Subcontext Form Guide"). Write {field} to include the question, e.g. Explain "{field}" to me. Long questions are cut to 30 characters. Popover panels always show the question as their title.
background both Panel background.
border both Panel border, e.g. 1px solid #cfe6fb.
margin inline Space around the panel. Default 2px 0 20px. Your page's CSS can't override it.
inputBackground both Background of the box where the visitor types.
inputBorder both Border of that box.
inputPadding both Padding inside that box.
buttonBackground both Send and Done button background.
buttonColor both Send and Done button text and icon colour.

The order of precedence is the panel keys, then the shared keys, then primaryColor (or data-primary-color), then the defaults. For the main colour that is theme.primaryColor, then primaryColor, then #2563EB.

Example as a snippet attribute:

html 
<script
  id="formguide-embed-script"
  src="https://js.subcontext.com/formguide-latest.js"
  data-agent-id="YOUR_AGENT_ID"
  data-base-url="https://subcontext.com"
  data-mode="inline"
  data-theme='{"heading":"Explain \"{field}\" to me","background":"#f6fbff","border":"1px solid #cfe6fb"}'></script>

Example with the shared keys, from JavaScript:

js 
SubcontextFormGuide.attach({
  container: document.getElementById('quote-form'),
  agentId: 'YOUR_AGENT_ID',
  theme: { primaryColor: '#0F3D3E', accentColor: '#E07A5F', fontFamily: 'Figtree, sans-serif', mode: 'dark' }
})

Wording and translation#

Pass strings to attach(), or put the same thing as JSON in data-strings. Only include the ones you want to change. The rest stay in English. Each guide keeps its own wording, so two forms on one page can use different text (or languages).

Key Default text
askFollowUp Ask a follow-up... (placeholder in the typing box)
typeAnswer Type your answer... (placeholder when the agent can fill in the field)
done Done
generating Generating... (on the Done button while the answer is worked out)
savedToForm Response saved to form.
couldNotFill We couldn't fill this in automatically: the suggested answer was: {answer}
messageBlocked Message blocked.
escalated This conversation has been escalated for review.
rateLimited Please slow down.
genericError Something went wrong.
helpWith Help with: {label} (read out by screen readers for the icon and panel)
closePanel Close help panel (read out by screen readers for the close button)
agentUnavailable Agent not available
conversationFailed Could not start conversation

Example:

html 
data-strings='{"askFollowUp":"Posez une autre question...","done":"Terminé","helpWith":"Aide pour : {label}"}'

The agent's own explanations and replies come from the agent, in the agent's language. Two pieces of text can't be changed here: the inline title "Subcontext Form Guide" (change it with theme.heading) and the "Powered by Subcontext" line at the bottom of the panel.

Stuck, or something missing?

Get in touch and a person on the team will help.

Contact us