---
name: "up:form:switch"
area: "API"
kind: "DOM event"
parent: "up.form module"
url: "https://unpoly.com/api/up:form:switch"
---
<nav aria-label="Unpoly docs">[All docs](https://unpoly.com/index.md) · [up.form module](https://unpoly.com/api/up.form.md)</nav>

# up:form:switch

When an [`[up-switch]`](https://unpoly.com/api/up-switch.md) field changes, this event is emitted on all dependent elements.

You can listen to `up:form:switch` to implement [custom switching effects](https://unpoly.com/learn/switching-form-state.md#custom-effects).

<nav aria-label="Guides">

- [Learn: Switching form state](https://unpoly.com/learn/switching-form-state.md#custom-effects)

</nav>

<nav aria-label="Contents">

#### Contents

- [Event targets](#event-targets)
- [Timing](#timing)
- [Event properties](#properties)

</nav>

## Event targets {#event-targets}

This event is _not_ emitted on the switching field. Instead each element matching the switch selector will receive an `up:form:switch` event:

```html
<!-- Switching field won't receive an event on change -->
<select name="role" up-switch=".role-dependent">
  <option value="trainee">Trainee</option>
  <option value="manager">Manager</option>
</select>

<!-- Dependent field will receive up:form:switch -->
<input class="role-dependent" name="department">

<!-- Dependent field will receive up:form:switch -->
<input class="role-dependent" name="budget">
```

## Timing {#timing}

The `up:form:switch` is emitted at the following times:

- when the switching field is initially rendered.
- after a switching field has changed its value.
- after a switching checkbox was checked or unchecked.
- when a new selector match enters the form.
- when a [kept](https://unpoly.com/api/up-keep.md) [`[up-switch]`](https://unpoly.com/api/up-switch.md) field is transported to a new form.

---

## Event properties {#properties}

### event.target {#event.target}

(required)

The dependent element matching the [`[up-switch]`](https://unpoly.com/api/up-switch.md) selector.

If multiple elements match the selector, this event is emitted once for each match.

Type: [Element](https://developer.mozilla.org/en-US/docs/Web/API/Element)

### event.field {#event.field}

(required)

The controlling [`[up-switch]`](https://unpoly.com/api/up-switch.md) field.

Type: [Element](https://developer.mozilla.org/en-US/docs/Web/API/Element)

### event.fieldTokens (Experimental) {#event.fieldTokens}

(required)

An array describing the state of the controlling [`[up-switch]`](https://unpoly.com/api/up-switch.md) field.

The array contains:

- The field's value.
- A pseudo-value [`:blank` or `:present`](https://unpoly.com/learn/switching-form-state.md#presence), depending on the field's value.
- For [checkboxes](https://unpoly.com/learn/switching-form-state.md#checkboxes), a pseudo-value `:checked` or `:unchecked`.

Type: [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<string>