Options and styling

Every setting for the script tag, the form element and init(), your own wording and error messages, and how to style the form.

Options#

On the script tag#

These apply to every form on the page.

Attribute Type Default What it does
data-key text none The form's key, lfk_..., from the Install tab. Used by every form and every createLead call on the page that doesn't give its own key.
data-base-url address https://subcontext.com The Subcontext address to talk to. You don't normally need this.
data-debug "true" off Writes extra lines to the browser console (the version, and each send's result). Errors are always written.
nonce text none Your content security policy nonce (see Content security policy). The script copies it to the styles it adds and to any script it loads.
id leadform-embed-script none Optional. Helps the script find its own tag. Without it, it uses the last script whose address contains leadform.

On a <div data-subcontext-leadform>#

Each such <div> is a drawn form. Anything you don't set comes from the Design tab, and then from the defaults below.

Attribute Type Default What it does
data-subcontext-leadform marker Marks the element where a form is drawn.
data-key text the script tag's key A different form's key, for a second form (or campaign) on the same page.
data-fields comma list the designed pages The fields to ask, on one page, in this order, for example "first_name, email, phone". Replaces the designed pages.
data-title text the design's The heading above the form.
data-intro text the design's The paragraph under the heading.
data-submit-label text the design's, else Send The send button's label.
data-success-title text the design's, else Thank you The thank-you heading. Can include answers, like Thanks, {first_name}.
data-success-message text the design's, else "We've got your details and we'll be in touch soon." The thank-you text. Can include answers, like {email}.
data-success-url address none Send the visitor to this page (your own thank-you page) after a successful send, instead of thanking them in place. Must start with http: or https:; anything else is ignored with a console error.
data-privacy-url address the design's The "How we use your details" link after the consent notice. Same rule as above.
data-accent colour the design's, else #2563eb Button and focus colour. Use a 6-digit hex like #0a7f3b, so the button text colour can be chosen for good contrast.
data-radius none, small, medium, large medium Corner rounding: 0, 4px, 8px or 14px.
data-layout stacked, inline stacked inline puts fields side by side in a row that wraps. Good for one-line forms.
data-font inherit, system inherit inherit uses your page's font. system uses the device's own font.
data-theme JSON, or light or dark none The theme object every Subcontext embed takes, written as JSON. See The shared theme keys. data-accent, data-font and the other settings above win over it.
data-heading-level 2 to 6 2 The heading level (h2 to h6) of the title and thank-you. Page titles and the error summary go one level below.
data-styles "false" styled "false" adds none of our styles, so you can style it yourself.
data-analytics "false" on "false" stops this form counting views, starts and sends for the Results tab.
data-utm-source, data-utm-medium, data-utm-campaign, data-utm-term, data-utm-content, data-utm-id text from the page address Campaign tags, sent with every lead from this form. They win over tags in the page address.
data-gclid, data-gbraid, data-wbraid, data-fbclid, data-msclkid, data-ttclid, data-li-fat-id text from the page address Ad click ids, same rules.
data-remember-click-ids "true" or "false" the script tag's, else 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 form on a later page. Also works on the script tag, for every form on the page and for pages with no form. See Ad clicks across pages.
data-value-<key> text none A value for field <key>. Dashes become underscores, so data-value-product-page is the field product_page. If that field is on the form, it is filled in; if not, it is sent hidden with every lead.

Your own wording (texts), error messages (messages), callbacks and detailed field settings can only be set from JavaScript, with init().

Subcontext.leadform.init(options)#

Option Type Default What it does
key text the script tag's data-key The form's key.
baseUrl text https://subcontext.com The Subcontext address. You don't normally need this.
mode 'head', 'headed' or 'headless' 'head' with a target, otherwise 'headless' 'head' (or 'headed') draws the form in target. 'headless' draws nothing, and you send leads from your own code.
target element or CSS selector none Where to draw the form. Needed to draw. Without it, nothing is drawn, ready gives false, onError gets code: 'no_target', and the console says why.
fields list of keys or field settings drawn: the designed pages; headless: none Drawn: the fields to show, on one page, replacing the design. Headless: the fields to check before sending (see What the script does).
title text the design's The heading.
intro text the design's The paragraph under the heading.
submitLabel text the design's, else Send The send button's label.
successTitle text the design's, else Thank you The thank-you heading. {field_key} is replaced with that answer.
successMessage text the design's, else the default The thank-you text. {field_key} is replaced with that answer.
successUrl text none Drawn forms: go to this page after a successful send (after your callbacks and events have run).
privacyUrl text the design's The privacy link in the consent block.
theme object, or 'light' or 'dark' the design's accent, radius, layout and font (the same as the data- settings above), plus the shared theme keys. Anything you set here replaces the design's.
headingLevel number 2 to 6 2 The same as data-heading-level.
styles true or false true false: add none of our styles.
analytics true or false true false: don't count this form on the Results tab. Headless forms are never counted.
provenance object none Where the visitor came from, sent with every lead from this form. See Where the visitor came from.
rememberClickIds true or false the script tag's data-remember-click-ids, else Google Consent Mode true: you have the visitor's consent to keep ad click ids for a form on a later page. false: you don't, and anything kept is deleted. See Ad clicks across pages.
values object of text, numbers, true/false or lists of text none Sent with every lead from this form, drawn or headless. Each lead's own answers win (what the visitor types, or what you pass to submit). On a drawn form these also fill in matching fields.
texts object see Wording Your own wording on a drawn form, for another language or tone.
messages object see Error messages Your own check and error messages, in both modes.
onReady function none Called once the form is drawn (drawn) or its settings are loaded (headless). If loading failed, onError is called instead.
onSuccess function none Called after each successful send, with the result.
onError function none Called after each failed send (including one that failed the checks before sending), with the result. Also called once if the form couldn't load, with that problem's code and message (for example no_key, invalid_key, origin_not_allowed, campaign_paused, no_target). Not called for a form you remove with destroy() before it loads.
debug true or false the script tag's data-debug Extra console lines.

Field settings#

A field is either a key ('email') or an object with these settings. Known keys come with a label, type and autofill hint. A key that isn't known becomes a text box with a label made from the key (for example product_page becomes "Product page").

Setting Type What it is
key text The field key: lowercase letters, digits and underscores, starting with a letter.
label text The label (or the heading of a group of choices).
type text, email, tel, textarea, number, date, datetime, checkbox, select, radio, checkboxes, hidden, content The kind of input. Unknown types become text. hidden sends its value without showing anything. content shows text and sends nothing.
required true or false Must be answered. If only one of email and phone is on the form, that one is always required. If both are, either will do.
placeholder text Example text inside the box.
hint text Help text under the field.
options list of text The choices for select, radio and checkboxes.
autocomplete text The browser autofill hint (the autocomplete attribute).
width 'full' or 'half' Half width on wide forms.
validation { min_length, max_length, min, max, pattern, message } (each optional) Extra checks. pattern is a regular expression that must match the whole answer. message replaces the standard error message.
value text For hidden fields: what it sends.
text text For content fields: the text it shows. Leave a blank line between paragraphs.
show_if { field, op, values } Show this field only when an earlier answer says so. op is is (one of values), is_not (none of values), filled or empty. A hidden field isn't sent, and a field that depends on a hidden field is hidden too.

Known keys: first_name, last_name, name, email, phone, message, plus your firm's own fields that are on the designed form. You can send any of your firm's other fields by key too; the drawn form shows them as plain text boxes.

Wording (texts)#

For drawn forms. Use these to change the wording or translate the form.

Key Default
submitLabel Send
nextLabel Next
backLabel Back
progress Step {step} of {steps}
sendingLabel Sending…
successTitle Thank you
successMessage We've got your details and we'll be in touch soon.
requiredNote Fields marked * are required.
errorTitle There's a problem
privacyLabel How we use your details
loadFailed This form isn't available right now. Please try again later.
notAccepting This form isn't taking enquiries at the moment.
choose Choose… (the empty choice in a drop-down)
consentLegend About contacting you (used when your marketing consent wording has no title)
botCheck Please complete the check that you're not a robot. (Cloudflare Turnstile only)

Where the same thing can be set in more than one place, this order wins: for submitLabel, successTitle and successMessage, the top-level option, then texts, then the design, then the default. For nextLabel and backLabel: texts, then the design, then the default.

Error messages (messages)#

For both modes. {label}, {min} and {max} are filled in.

Key Default
required Enter your {label}.
choose Choose an answer for {label}.
tick Tick this box to continue.
email Enter a valid email address, like name@example.com.
phone Enter a valid phone number. (7 to 15 digits)
contact Enter an email address or a phone number so we can get back to you.
tooLong Must be {max} characters or fewer.
tooShort Must be at least {min} characters.
number Enter a number.
tooSmall Must be at least {min}.
tooBig Must be no more than {max}.
date Enter a date.
option Choose from the options given.
pattern Isn't in the expected format.
any error code Replaces that error's message, for example network, timeout, rate_limited, server, campaign_paused, origin_not_allowed. See Troubleshooting for every code.

Styling#

The drawn form uses your page's font and text colour, so it works on light and dark backgrounds. It is at most 40rem wide, and half-width fields stack once the form is narrower than 30rem.

There are three ways to change the look, from easiest to most control.

1. Settings on the <div> or in theme#

data-accent, data-radius, data-layout, data-font, and the shared theme keys in data-theme or theme. See Options.

The shared theme keys#

The lead form takes the theme object every Subcontext embed takes, so one theme can brand them all (see Theming the embeds). Put these keys in theme beside accent, radius, layout and font:

Key What it changes
accentColor The accent: the button, ticked boxes and focus outlines. Sets --sclf-accent.
primaryColor Your main brand colour, for the headings (the title, page titles and the thank-you heading). Sets --sclf-heading, except in dark mode, where the headings stay in the light text so a dark brand colour can't make them hard to read. It is also the accent when there's no accentColor.
backgroundColor A background behind the form, with 1.25rem of padding and rounded corners. Sets --sclf-bg.
fontFamily The form's font, as a CSS font list, when there's no font. It also replaces the design's font. Load the font on your page yourself.
fontSize The form's text size in pixels: labels, answers and buttons. Headings, hints and notes keep their size.
mode 'dark': light text on a dark background (#1f1d1a, or your backgroundColor). 'light': dark text, for a light form on a dark page. Without it, the form takes your page's text colour.

The lead form's own keys win over the shared ones: accent over accentColor over primaryColor for the accent, and font over fontFamily. Your own CSS wins over all of them.

html 
<div data-subcontext-leadform data-theme='{"primaryColor":"#0F3D3E","accentColor":"#E07A5F","fontFamily":"Figtree, sans-serif","mode":"dark"}'></div>

2. CSS custom properties#

Set these on the form's element, or on .sclf for every form on the page:

css 
.sclf { --sclf-accent: #0a7f3b; --sclf-radius: 0; --sclf-font: Georgia, serif; --sclf-gap: .75rem; }
Property Default
--sclf-accent #2563eb
--sclf-accent-text #fff (worked out from a hex accent for good contrast)
--sclf-heading none: headings take the text colour (set by primaryColor, except in dark mode). Set it yourself to colour the headings in dark mode too.
--sclf-radius 8px
--sclf-gap 1rem
--sclf-font inherit
--sclf-text inherit
--sclf-muted, --sclf-border mixed from the text colour
--sclf-input-bg transparent
--sclf-bg none (set by backgroundColor, or by dark mode)
--sclf-error, --sclf-success red and green, mixed with the text colour
--sclf-focus the accent, at 45% strength

Your CSS always wins over an accent set in the design, theme.accent, theme.accentColor, theme.primaryColor or data-accent. So .sclf { --sclf-accent: ... } changes every form's accent, and #my-form { --sclf-accent: ... } changes one. An accent or primaryColor must look like a colour (a hex code, a colour name, or rgb(...)); anything else is ignored with a console error. A backgroundColor or fontFamily with characters CSS could break out on (such as ; or {) is ignored the same way.

3. Your own CSS on our classes#

All our styles have zero specificity (they use CSS :where()), so any rule you write overrides them without !important.

css 
.site-form .sclf-label { text-transform: uppercase; }
.site-form .sclf-button { width: 100%; }

Classes you can style: sclf, sclf-title, sclf-intro, sclf-note, sclf-form, sclf-progress, sclf-page, sclf-page-title, sclf-page-intro, sclf-field, sclf-field--<key>, sclf-field--<type>, sclf-field--half, sclf-group, sclf-label, sclf-req, sclf-input, sclf-hint, sclf-error-text, sclf-consent, sclf-check, sclf-privacy, sclf-actions, sclf-button, sclf-button--back, sclf-spinner, sclf-alert, sclf-summary, sclf-success, sclf-chat, sclf-turnstile.

The form's element also has data-radius, data-layout and data-font attributes from the theme, data-sclf-theme when its theme sets anything (an accent, heading colour, background, font, text size or mode), and the class sclf-styled when it has our styles.

No styles at all#

data-styles="false" (or init({ styles: false })) adds none of our styles to that form (or consent block). It stays unstyled even if other forms on the same page are styled. The hidden spam trap field stays hidden either way.

Stuck, or something missing?

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

Contact us