EmailForm

<allegro-email-form> is a web component that renders an email subscription form. On success it transitions to a confirmation state. Both states are fully customizable via attributes, slots, CSS variables, and shadow parts.

See every state of <allegro-email-form> in Storybook.

Usage

<allegro-email-form></allegro-email-form>

With custom attributes:

<allegro-email-form
    form-label-text="Enter your email address"
    show-form-label="false"
    placeholder-text="Your email address"
    submit-text="Subscribe"
    show-disclaimer="true"
    disclaimer-text="We'll never share your email."
    confirmation-heading="You're in!"
    confirmation-text="Thanks for subscribing."
    continue-text="Continue"
></allegro-email-form>

Attributes

Attribute	Type	Default	Description
show-form-label	boolean	true	Whether to show the email field's label. When false, the label is still rendered for screen readers but visually hidden. If placeholder-text is empty, the label text is used as the placeholder so the field still has visible text.
form-label-text	text	Email Address	Label text for the email input field.
placeholder-text	text	Enter your email	Placeholder text for the email input field.
submit-text	text	Submit	Label for the submit button.
show-disclaimer	boolean	false	Whether to show the disclaimer paragraph below the form.
disclaimer-text	text	(empty)	HTML for the disclaimer paragraph. Links and inline formatting are kept; other markup is stripped.
confirmation-heading	text	Thank you!	Heading shown in the confirmation state.
confirmation-text	text	Thanks for providing your email.	Body text shown in the confirmation state.
continue-text	text	Continue	Label for the continue button in the confirmation state.
user-attributes	text	(empty)	JSON object of user attribute values stored against the reader on submit, e.g. "{'wants-newsletter': true}".
custom-request-data	text	(empty)	JSON object of extra data sent with the email, e.g. \"{'campaign': 'sidebar'}\". Named inputs in the slots override matching keys.
tracking-data	text	(empty)	JSON object of custom data merged into every tracked event, e.g. "{'campaign': 'footer'}".

Storing user attributes

user-attributes sets user attribute values on the reader when they submit their email, keyed by attribute slug. A value is only stored when the reader doesn't already have one for that attribute, so existing values are never overwritten. Every slug must be an attribute readers can edit; if one isn't, or a value fails the attribute's rules, the form shows the error and nothing is saved.

<allegro-email-form
    user-attributes="{'signup-source': 'footer', 'wants-newsletter': true}"
></allegro-email-form>

States

State	Trigger	Description
email	Initial render	The default state showing the email input form.
confirmation	Successful form submission	Shown after the email is successfully submitted.

Slots

Slot	Appears in	Description
header	email	Rendered above the email input. Use for a title or description. Hidden once the form transitions to the confirmation state.
after-form	email	Rendered below the email input and above the disclaimer. Use for supplementary inputs such as newsletter opt-in checkboxes.
footer	email	Rendered below the disclaimer. Use for supplementary links. Hidden once the form transitions to the confirmation state.
success	confirmation	Replaces the default confirmation state UI. When present, the default content is not rendered.
confirmation	confirmation	Same as success, kept for existing pages. If both are present, success is used.

<allegro-email-form submit-text="Subscribe">
    <div slot="header">
        <h2>Get the morning newsletter</h2>
    </div>
    <label slot="after-form">
        <input type="checkbox" name="wants-weekly" value="yes" />
        Also send me the weekly roundup
    </label>
    <p slot="footer"><a href="/privacy">Privacy policy</a></p>
    <div slot="success">
        <h2>You're on the list</h2>
        <p>Check your inbox.</p>
    </div>
</allegro-email-form>

Submitting slotted inputs

Named <input>, <select>, and <textarea> elements inside the header, after-form, and footer slots are sent with the email as request data, keyed by name. A checkbox sends its value when checked (or true when it has no value) and false when unchecked. Inputs without a name are ignored. Slotted values are merged over any request data the form already sends, so a slotted input wins when the names match.

Slotted inputs are part of your page, not the component, so give each one its own label. The component does not validate them before submitting.

When the confirmation slot has a heading, focus moves to it after a successful submit; otherwise its text is announced to screen readers.

Shadow Parts

For styling beyond what the CSS variables make available, elements can be targeted directly with the CSS ::part() selector.

allegro-email-form::part(email-field-input) {
    margin-bottom: 2rem;
}

Part	Appears in	Description
email-form	email	The email input + submit button <form>.
email-field	email	Wrapper around the email label and input.
email-field-label	email	The email input's <label> element.
email-field-input	email	The email <input> element.
email-form-submit	email	The submit button.
disclaimer	email	The disclaimer paragraph.
confirmation	confirmation	Wrapper around the confirmation elements.
confirmation-icon	confirmation	The confirmation icon.
confirmation-heading	confirmation	The confirmation heading.
confirmation-body	confirmation	The confirmation body text.
confirmation-continue	confirmation	The continue button.

Events

Dispatched

Event	Bubbles	Detail	Description
allegro:email-form:success	yes	{ email: string }	Fired when the form is successfully submitted.
allegro:email-form:error	yes	{ email: string, error: string }	Fired when there is an error during form submission.
allegro:content-gate:close	yes	(none)	Fired when the reader clicks Continue on the confirmation screen, just before the form removes itself. Closes a surrounding content gate.

Tracked Events

The component records the following events via the Allegro SDK.

Event	When	Data
email_form_submitted	Fired after a successful form submission.	(none)

CSS Variables

All visual properties are exposed as CSS custom properties so the component can be themed from the host page without piercing the shadow DOM.

allegro-email-form {
    --emailForm--button--background: #1a1a1a;
    --emailForm--input--border: 1px solid #ccc;
}

Defaults written below as u(n) mean n times --emailForm--base-font-size, the component's sizing unit. The unit defaults to the page's rem. If the host page sets a root font-size other than the usual 16px, pin it so the form sizes the same either way:

allegro-email-form {
    --emailForm--base-font-size: 16px;
}

General

Variable	Default	Description
--emailForm--font-family	var(--allegro--font-family, system-ui, sans-serif)	Font family for the component.
--emailForm--color	var(--allegro--color-text, black)	Text color for the component.
--emailForm--base-font-size	var(--allegro--font-size, 1rem)	Base sizing unit for the component.

Form Layout

Variable	Default	Description
--emailForm--form--gap	u(0.8)	Gap between the field and submit button.
--emailForm--label--margin	0 0 u(0.4)	Margin around the email field's label.

Input

Variable	Default	Description
--emailForm--input--background	var(--allegro--color-background, #fff)	Input background color.
--emailForm--input--border	1px solid var(--allegro--color-border, #8c8c8c)	Input border.
--emailForm--input--border-radius	var(--allegro--radius, u(0.375))	Input border radius.
--emailForm--input--font-size	u(1)	Input font size.
--emailForm--input--padding	u(0.75) u(1)	Input padding.
--emailForm--input--focus-border-color	var(--allegro--color-primary, #555)	Border color on input focus.

Submit Button

Variable	Default	Description
--emailForm--button--background	var(--allegro--color-primary, #000)	Button background color.
--emailForm--button--color	var(--allegro--color-primary-contrast, #fff)	Button text color.
--emailForm--button--border-radius	var(--allegro--radius, u(0.375))	Button border radius.
--emailForm--button--font-size	u(0.875)	Button font size.
--emailForm--button--font-weight	700	Button font weight.
--emailForm--button--padding	u(0.75) u(1.25)	Button padding. The Continue button on the confirmation screen uses u(0.75) u(1.5).
--emailForm--button--text-transform	uppercase	Button text transform.
--emailForm--button--font-family	inherit	Button font family.
--emailForm--button--letter-spacing	0.06em	Button letter spacing.

Error Message

Variable	Default	Description
--emailForm--error--background	#fef2f2	Error background color.
--emailForm--error--border	1px solid #fecaca	Error border.
--emailForm--error--accent-color	var(--allegro--color-error, #dc2626)	Error left accent border color.
--emailForm--error--border-radius	var(--allegro--radius, u(0.375))	Error border radius.
--emailForm--error--color	var(--allegro--color-error, #b91c1c)	Error text color.
--emailForm--error--icon-color	currentColor	Error icon color.
--emailForm--error--padding	u(0.625) u(0.875)	Error padding.
--emailForm--error--font-size	u(0.875)	Error message font size.

Confirmation State

Variable	Default	Description
--emailForm--state-icon--background	var(--allegro--color-primary, #111)	Confirmation icon circle background.
--emailForm--state-heading--color	var(--allegro--color-text, #111)	Confirmation heading color.
--emailForm--state-heading--font-size	u(1.25)	Confirmation heading font size.
--emailForm--state-heading--font-weight	700	Confirmation heading font weight.
--emailForm--state-body--color	var(--allegro--color-muted, #555)	Confirmation body text color.
--emailForm--state-body--font-size	u(0.9375)	Confirmation body font size.
--emailForm--state-icon--size	u(3.5)	Width and height of the confirmation icon.

Disclaimer

Variable	Default	Description
--emailForm--disclaimer--color	var(--allegro--color-muted, #555)	Disclaimer text color.
--emailForm--disclaimer--font-size	u(0.8125)	Disclaimer text size.
--emailForm--disclaimer--link--color	inherit	Color of links inside the disclaimer HTML. Links are underlined.

Example: Dark Background

allegro-email-form {
    --emailForm--input--background: #1a1a1a;
    --emailForm--input--border: 1px solid #444;
    --emailForm--input--focus-border-color: #888;
    --emailForm--button--background: #fff;
    --emailForm--button--color: #000;
    --emailForm--state-icon--background: #fff;
    --emailForm--state-heading--color: #fff;
    --emailForm--state-body--color: #aaa;
}