# Form

`<allegro-form>` renders a form composed in the Allegro admin (under **Forms**) from your organization's user attributes. The authenticated member's current values are prefilled, submissions are validated against each attribute's validation rules, and the member's profile is updated in place.

The component only renders for authenticated members. If no member is signed in, the element stays empty — pair it with [`<allegro-content-gate>`](/developer/components/content-gate.md) or [`<allegro-login-form>`](/developer/components/login-form.md) to prompt visitors to sign in first.

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

```html
<allegro-form slug="profile-basics"></allegro-form>

```

Customized, with a custom success state:

```html
<allegro-form slug="profile-basics" submit-text="Update profile">
    <div slot="success">
        <h2>All set!</h2>
        <p>Your profile has been updated.</p>
    </div>
</allegro-form>

```

## Attributes[​](#attributes "Direct link to Attributes")

| Attribute         | Type      | Default                           | Description                                                                                       |
| ----------------- | --------- | --------------------------------- | ------------------------------------------------------------------------------------------------- |
| `slug`            | `text`    | *(none)*                          | Slug of the form to render, as defined under **Forms**.                                           |
| `submit-text`     | `text`    | `Save`                            | Label for the submit button.                                                                      |
| `success-heading` | `text`    | `Thank you!`                      | Heading shown in the default success state.                                                       |
| `success-text`    | `text`    | `Your responses have been saved.` | Body text shown in the default success state.                                                     |
| `preview`         | `boolean` | `false`                           | Render a static sample form and success state for style previews instead of fetching a real form. |
| `tracking-data`   | `text`    | *(none)*                          | JSON object of custom data merged into every tracked event.                                       |

## States[​](#states "Direct link to States")

| State     | Trigger                                     | Description                                                         |
| --------- | ------------------------------------------- | ------------------------------------------------------------------- |
| `form`    | Successful load for an authenticated member | The form's fields, prefilled with the member's current values.      |
| `success` | Successful submission                       | The `success` slot when provided, otherwise a default confirmation. |

Fields with display conditions show and hide live as the member fills out the form: a field configured to appear only when another field is checked, unchecked, has a value, or equals a specific value is re-evaluated on every change. Hidden fields are not submitted.

## Slots[​](#slots "Direct link to Slots")

| Slot      | Appears in | Description                                           |
| --------- | ---------- | ----------------------------------------------------- |
| `success` | `success`  | Replaces the default confirmation after a submission. |

```html
<allegro-form slug="profile-basics">
    <div slot="success">
        <h2>Saved!</h2>
        <a href="/account">Back to your account</a>
    </div>
</allegro-form>

```

## Shadow Parts[​](#shadow-parts "Direct link to Shadow Parts")

For styling beyond what the CSS variables make available, elements can be targeted directly with the CSS [`::part()`](https://developer.mozilla.org/en-US/docs/Web/CSS/::part) selector.

```css
allegro-form::part(submit) {
    margin-bottom: 2rem;
}

```

| Part           | Appears in | Description                                                                            |
| -------------- | ---------- | -------------------------------------------------------------------------------------- |
| `form`         | `form`     | The rendered `<form>` element.                                                         |
| `submit`       | `form`     | The submit button.                                                                     |
| `success`      | `success`  | Wrapper around the success elements. Not rendered when the `success` slot is provided. |
| `success-icon` | `success`  | The success icon.                                                                      |

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

### Dispatched[​](#dispatched "Direct link to Dispatched")

| Event                  | Bubbles | Detail                                              | Description                                                 |
| ---------------------- | ------- | --------------------------------------------------- | ----------------------------------------------------------- |
| `allegro:form:success` | Yes     | `{ slug: string; values: Record<string, unknown> }` | Fired after a successful submission.                        |
| `allegro:form:error`   | Yes     | `{ slug: string; error: string }`                   | Fired when a submission fails, including validation errors. |

Both events are `composed`, so they cross shadow DOM boundaries.

```js
document.addEventListener('allegro:form:success', (event) => {
    console.log('Form saved:', event.detail.slug, event.detail.values);
});

```

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

The component records the following events via the Allegro SDK.

| Event            | When                          | Data                    |
| ---------------- | ----------------------------- | ----------------------- |
| `form_submitted` | After a successful submission | `{ form_slug: string }` |

## Validation[​](#validation "Direct link to Validation")

Values are validated server-side on submission:

* Fields marked **required** in the form builder must be filled in (when visible).
* Each value must pass the attribute's type check and any validation rules configured on the attribute (length, regex, contains, email, numeric bounds).
* Error messages configured on the form field or on the attribute's validation rules are shown next to the failing field.

A `max_length` rule also sets a `maxlength` hint on the rendered input.

## CSS Variables[​](#css-variables "Direct link to CSS Variables")

Style the form through CSS custom properties on the element.

```css
allegro-form {
    --form--button--background: #0f766e;
    --form--input--border-radius: 0;
}

```

Defaults written below as `u(n)` mean `n` times `--form--base-font-size`, the component's sizing unit: `u(0.5)` is half that unit, `u(1.25)` is one and a quarter. 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:

```css
allegro-form {
    --form--base-font-size: 16px;
}

```

### Layout & Typography[​](#layout--typography "Direct link to Layout & Typography")

| Variable                 | Default                                              | Description                         |
| ------------------------ | ---------------------------------------------------- | ----------------------------------- |
| `--form--base-font-size` | `var(--allegro--font-size, 1rem)`                    | Base sizing unit for the component. |
| `--form--font-family`    | `var(--allegro--font-family, system-ui, sans-serif)` | Font family.                        |
| `--form--color`          | `var(--allegro--color-text, black)`                  | Text color.                         |
| `--form--gap`            | `u(1)`                                               | Vertical gap between fields.        |

### Labels & Inputs[​](#labels--inputs "Direct link to Labels & Inputs")

| Variable                            | Default                                  | Description                      |
| ----------------------------------- | ---------------------------------------- | -------------------------------- |
| `--form--label--font-size`          | `u(0.875)`                               | Label font size.                 |
| `--form--label--font-weight`        | `600`                                    | Label font weight.               |
| `--form--required--color`           | `var(--allegro--color-error, #b91c1c)`   | Color of the required asterisk.  |
| `--form--input--background`         | `white`                                  | Input background.                |
| `--form--input--border`             | `1px solid #d4d4d4`                      | Input border.                    |
| `--form--input--border-radius`      | `var(--allegro--radius, u(0.375))`       | Input border radius.             |
| `--form--input--font-size`          | `u(1)`                                   | Input font size.                 |
| `--form--input--padding`            | `u(0.5) u(0.75)`                         | Input padding.                   |
| `--form--input--focus-border-color` | `var(--allegro--color-primary, #171717)` | Border color of a focused input. |
| `--form--checkbox--accent-color`    | `var(--allegro--color-primary, #171717)` | Checkbox accent color.           |
| `--form--tooltip--color`            | `#737373`                                | Tooltip text color.              |
| `--form--tooltip--font-size`        | `u(0.75)`                                | Tooltip font size.               |

### Errors[​](#errors "Direct link to Errors")

| Variable                   | Default                                | Description              |
| -------------------------- | -------------------------------------- | ------------------------ |
| `--form--error--color`     | `var(--allegro--color-error, #b91c1c)` | Error message color.     |
| `--form--error--font-size` | `u(0.875)`                             | Error message font size. |

### Button & Success State[​](#button--success-state "Direct link to Button & Success State")

| Variable                             | Default                                  | Description                     |
| ------------------------------------ | ---------------------------------------- | ------------------------------- |
| `--form--button--background`         | `var(--allegro--color-primary, #171717)` | Submit button background.       |
| `--form--button--color`              | `white`                                  | Submit button text color.       |
| `--form--button--border-radius`      | `var(--allegro--radius, u(0.375))`       | Submit button border radius.    |
| `--form--button--font-size`          | `u(1)`                                   | Submit button font size.        |
| `--form--button--padding`            | `u(0.5) u(1.25)`                         | Submit button padding.          |
| `--form--success--padding`           | `u(1.5) 0`                               | Default success state padding.  |
| `--form--success--icon-background`   | `var(--allegro--color-success, #16a34a)` | Success icon circle background. |
| `--form--success--heading-font-size` | `u(1.25)`                                | Success heading font size.      |
| `--form--success--body-color`        | `#525252`                                | Success body text color.        |
| `--form--success--body-font-size`    | `u(0.9375)`                              | Success body font size.         |

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

```css
.dark-section allegro-form {
    --form--color: #f5f5f5;
    --form--input--background: #262626;
    --form--input--border: 1px solid #404040;
    --form--tooltip--color: #a3a3a3;
    --form--button--background: #f5f5f5;
    --form--button--color: #171717;
}

```