# Form `` is a [HTML custom element](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements) designed to serve as the base logic for all auro-constructed forms. It automatically "scrapes" its inner content for any auro form elements, and surfaces them (along with events) to the parent form element as a JSON object. ## Form Value Generation Auro form exists to make a developer's life easier through surfacing all Auro form elements in a given form as a single JSON object. The most common use case the Auro team identified when building Form was the need to collect form data in a structured way. The following is required on each Auro form element in a form for it to be collected automatically: 1. It **must** have a `name` attribute. This is required if vanilla HTML forms, and we follow the same pattern. 2. It **must** be an Auro form element. See the section on custom elements for more information. That being said, we do _not_ require form elements to be direct children of `auro-form`. They can be nested within other elements for styling, such as a `div`, `span` or `fieldset`. ### Form Data Structure In a correctly registered scenario, `auro-form` will automatically recognize the auro form elements and collect data from each on the form's `value` key as a JSON object. Each element will be added using the element's `name` attribute as the key, and the element's `value` as the value. A real-world example of this might be: ```json { "hotelCity": "New York", "dates": ["2022-01-01", "2022-01-15"], "numberOfGuests": 2 } ``` If your project uses TypeScript, consider using a type like this to represent the form data: ```typescript // Generic type for form values type AuroFormValue = T | null; // Example types type AuroInputValue = AuroFormValue; type AuroDatePickerValue = AuroFormValue; // This is the type returned from the `AuroForm.value` getter interface AuroFormState { // value varies based on form element hotelCity: AuroInputValue; dates: AuroDatePickerValue; numberOfGuests: AuroInputValue; } ``` ## Accessing Form Data As Auro components are designed to be framework-agnostic, data can be retrieved using simple vanilla JavaScript patterns. If you have ever worked with a standard HTML5 form, you are already equipped to work with Auro forms! Once you have a reference to the form element (React ref, querySelector, etc.), you can access the form data using the following methods: **Data Keys + Get Methods**: - `.value` - Getter which returns the current form data as a JSON object. - `.validity` - Returns the current validity state of the form (`valid` or `invalid`). **Extra Information**: - `.isInitialState` - Returns a boolean indicating if the form is in its initial state. **Events** - `input` - Fires when the form state changes. - `reset` - Fires when the form is reset. - `submit` - Fires when the form is submitted. **Advanced Features**: - `.formState` - This is the internal form state. It includes extra `required` and `validity` information for each form element. This key is not required for normal form usage, but can add additional context for more complex forms. ### Basic Form Example The most basic form implementation requires an `auro-input` and an optional auro button with `type="submit"`. By default, Auro Form connects a `submit` event to all `type="submit"` buttons within the form.

Submit

See code ```html

Submit

```