# 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, and CSS variables.

## Usage[​](#usage "Direct link to Usage")

```html
<allegro-email-form></allegro-email-form>

```

With custom attributes:

```html
<allegro-email-form
    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[​](#attributes "Direct link to Attributes")

| Attribute              | Type      | Default                            | Description                                                                                  |
| ---------------------- | --------- | ---------------------------------- | -------------------------------------------------------------------------------------------- |
| `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 content for the disclaimer paragraph.                                                   |
| `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.                                     |
| `tracking-data`        | `text`    | *(empty)*                          | JSON object of custom data merged into every tracked event, e.g. `"{'campaign': 'footer'}"`. |

## States[​](#states "Direct link to 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[​](#slots "Direct link to Slots")

| Slot           | Appears in     | Description                                                                                    |
| -------------- | -------------- | ---------------------------------------------------------------------------------------------- |
| `confirmation` | `confirmation` | Replaces the default confirmation state UI. When present, the default content is not rendered. |

```html
<allegro-email-form>
    <div slot="confirmation">
        <p>Thanks! Check your inbox.</p>
    </div>
</allegro-email-form>

```

## Events[​](#events "Direct link to Events")

### Dispatched[​](#dispatched "Direct link to 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. |

## Tracked Events[​](#tracked-events "Direct link to 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[​](#css-variables "Direct link to 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.

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

```

### General[​](#general "Direct link to General")

| Variable                   | Default                 | Description                    |
| -------------------------- | ----------------------- | ------------------------------ |
| `--emailForm--font-family` | `system-ui, sans-serif` | Font family for the component. |

### Input[​](#input "Direct link to Input")

| Variable                                 | Default          | Description                  |
| ---------------------------------------- | ---------------- | ---------------------------- |
| `--emailForm--input--background`         | `#fff`           | Input background color.      |
| `--emailForm--input--border`             | `1px solid #ccc` | Input border.                |
| `--emailForm--input--border-radius`      | `0.375rem`       | Input border radius.         |
| `--emailForm--input--font-size`          | `1rem`           | Input font size.             |
| `--emailForm--input--padding`            | `0.75rem 1rem`   | Input padding.               |
| `--emailForm--input--focus-border-color` | `#555`           | Border color on input focus. |

### Submit Button[​](#submit-button "Direct link to Submit Button")

| Variable                              | Default           | Description              |
| ------------------------------------- | ----------------- | ------------------------ |
| `--emailForm--button--background`     | `#000`            | Button background color. |
| `--emailForm--button--color`          | `#fff`            | Button text color.       |
| `--emailForm--button--border-radius`  | `0.375rem`        | Button border radius.    |
| `--emailForm--button--font-size`      | `0.875rem`        | Button font size.        |
| `--emailForm--button--font-weight`    | `700`             | Button font weight.      |
| `--emailForm--button--padding`        | `0.75rem 1.25rem` | Button padding.          |
| `--emailForm--button--text-transform` | `uppercase`       | Button text transform.   |

### Error Message[​](#error-message "Direct link to Error Message")

| Variable                            | Default             | Description                     |
| ----------------------------------- | ------------------- | ------------------------------- |
| `--emailForm--error--background`    | `#fef2f2`           | Error background color.         |
| `--emailForm--error--border`        | `1px solid #fecaca` | Error border.                   |
| `--emailForm--error--accent-color`  | `#dc2626`           | Error left accent border color. |
| `--emailForm--error--border-radius` | `0.375rem`          | Error border radius.            |
| `--emailForm--error--color`         | `#b91c1c`           | Error text color.               |
| `--emailForm--error--icon-color`    | `currentColor`      | Error icon color.               |
| `--emailForm--error--padding`       | `0.625rem 0.875rem` | Error padding.                  |

### Confirmation State[​](#confirmation-state "Direct link to Confirmation State")

| Variable                                  | Default     | Description                          |
| ----------------------------------------- | ----------- | ------------------------------------ |
| `--emailForm--state-icon--background`     | `#111`      | Confirmation icon circle background. |
| `--emailForm--state-heading--color`       | `#111`      | Confirmation heading color.          |
| `--emailForm--state-heading--font-size`   | `1.25rem`   | Confirmation heading font size.      |
| `--emailForm--state-heading--font-weight` | `700`       | Confirmation heading font weight.    |
| `--emailForm--state-body--color`          | `#555`      | Confirmation body text color.        |
| `--emailForm--state-body--font-size`      | `0.9375rem` | Confirmation body font size.         |

## Example: Dark Background[​](#example-dark-background "Direct link to Example: Dark Background")

```css
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;
}

```