> For the complete documentation index, see [llms.txt](https://docs.usegravity.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.usegravity.app/gravity-native/components/form.md).

# Form

Forms are simple and require almost no work to set up. Simply create an object with the form fields you need and pass it to the `<Form>` component. You can render any input type you need – from text boxes to pickers and sliders.

## Preview

<div align="left"><figure><img src="/files/9isnmzt4FTymtbT0PevF" alt="" width="375"><figcaption></figcaption></figure></div>

## Code

```javascript
 <Form 
  data={ formObject }
  url='/api/demo'
  method='POST'
  buttonText='Save' 
  callback={ this.onSuccess }
/>
```

## Props

| Prop           | Description                          | Required | Value        |
| -------------- | ------------------------------------ | -------- | ------------ |
| buttonText     | submit button label                  | optional | string       |
| callback       | executed after a successful submit   | optional | function     |
| data           | form object (see below)              | required | object       |
| method         | HTTP request type                    | optional | string       |
| style          | custom style                         | optional | style object |
| submitOnChange | submit the form on each input change | optional | boolean      |
| url            | url to send the form to              | optional | string       |

## Form Object

When constructing a form object, the outer key is the input name which is assigned an object with any combination of input props.

```javascript
formData = {
  name: {
    label: 'Your name',
    type: 'text',
    required: true,
    placeholder: 'Jon Smith',
    errorMessage: 'Please enter your name',
  },
  email: {
    label: 'Email address',
    type: 'email',
    required: true,
  },
 age: {
    label: 'Age',
    type: 'number',
    min: 18,
    max: 65,
  },
  dob: {
    label: 'Date of birth',
    type: 'date',
  },
  hungry: {
    label: 'Feeling hungry?',
    type: 'switch',
   },
  happiness: {
    label: 'Happiness level',
    type: 'slider',
  },
  phone: {
    label: 'Phone Number',
    type: 'phone',
    required: false
  },
  website: {
    label: 'Website',
    type: 'url',
    required: false,
  },
  gender: {
    label: 'Gender',
    type: 'picker',
    options: ['male', 'female'],
    required: true,
  }
}
```

## Input Props

| Prop         | Description                         | Required | Value                                                                                 |
| ------------ | ----------------------------------- | -------- | ------------------------------------------------------------------------------------- |
| default      | default value                       | optional | string                                                                                |
| errorMessage | overrides the default error message | optional | string                                                                                |
| label        | input label                         | optional | string                                                                                |
| max          | maximum value on number input       | optional | integer                                                                               |
| min          | minimum value on number input       | optional | integer                                                                               |
| name         | input name                          | required | string                                                                                |
| options      | array of strings for a picker       | required | array                                                                                 |
| placeholder  | placeholder text                    | optional | string                                                                                |
| required     | determines if a value is required   | optional | boolean                                                                               |
| step         | increment step amount for slider    | optional | number                                                                                |
| type         | input type                          | required | text, email, password, number, url, phone, hidden, picker, date, time, switch, slider |
| value        | initial value                       | optional | string                                                                                |

## Form Submission

When your form is submitted to the server, Gravity will optimise the request and only send the name/value pairs, so on the server you can access a value using:

```javascript
req.body.email
```

## Form Errors

To show an error on a specific form input, throw an error on the server with an `inputError` key and the input name.

```javascript
throw ({ inputError: 'email', message: 'You\'re already registered' });
```