---
title: Form Input Events & API
slug: wip/form-input-events-and-api
createdAt: 2023-07-21T06:22:23.149Z
---

# Form Input Events & API

:::hint{type="info"}
**🏃‍♂️ TL;DR**

Cosmos form input components use custom events and APIs to bridge the Shadow DOM boundary and allow the integration and syncing of a native form input state with an application.
:::

Cosmos form input components like the [Radio Group](https://cosmos.redbull.design/wip/radio-group) or [Checkbox](https://cosmos.redbull.design/wip/checkbox) are wrappers around native form controls rendered inside the web component's Shadow DOM. By design, the Shadow DOM isolates the native form inputs so that one can not listen to some native input events directly or operate on their native API.

Cosmos form input components provide custom events and APIs to bridge the Shadow DOM boundary to allow the integration and syncing of a native form input state with an application.

## Listening to Custom Events

Updating an application's state on behalf of events that are emitted when users interact with an input – usually the `change` or `input` event – is essential when integrating a form input into an application.

Unfortunately, it's especially those kinds of events that cannot pass the Shadow DOM of a web component when bubbling up through the DOM.

:::hint{type="info"}
**💡 Good to know**

If an event can traverse the Shadow DOM boundary depends on if the native event is `composed`or not. Find a detailed description and interactive demos [here](https://pm.dartus.fr/blog/a-complete-guide-on-shadow-dom-and-event-propagation/#escaping-the-shadow-trees-using-composed).
:::

Cosmos provides a set of custom events to replace native events commonly used when integrating form inputs into rich applications and cannot pass the Shadow DOM root of a web component. They share the name with the native event they represent but are prefixed with `input`– the `change` event becomes the `inputchange` event.

The API documentation of Cosmos form input components provides a full list of available custom events.

:::Iframe{code="<iframe title=&#x22;Embeded content from codepen.io&#x22; class=&#x22;no-border max-full-width full-height flex-grow&#x22; src=&#x22;https://codepen.io/redbulldesign/embed/gOemKOe/3348c2991f8587be8788e2ff1601116a?default-tab=html%2Cresult&#x26;amp;editable=true&#x26;amp;theme-id=39623&#x22; height=&#x22;199px&#x22;></iframe>"}

:::

## Custom API

Like events, there are certain APIs that are isolated by the Shadow DOM rendered by Cosmos web components but are inevitable when integrating a form input into an application.

Cosmos form input components expose a set of commonly used methods and prefix them with `input` to mimic a native HTML input's API – `checkValidity()` becomes `inputCheckValidity()`

:::hint{type="warning"}
**☝️ Watch out**

The methods of the custom API return a Promise that resolves the results you'd expect from calling the native's input method.
:::

The API documentation of Cosmos form input components provides a full list of available methods.

:::Iframe{code="<iframe title=&#x22;Embeded content from codepen.io&#x22; class=&#x22;no-border max-full-width full-height flex-grow&#x22; src=&#x22;https://codepen.io/redbulldesign/embed/yLvVBbm/6cfd43f790129540be4eac1a9f8b1263?default-tab=html%2Cresult&#x26;amp;editable=true&#x26;amp;theme-id=39623&#x22; height=&#x22;306px&#x22;></iframe>"}

:::

