---
description: Learn more about the Basic components
---

# Basic  Components

Basic components are found at the top of the component groupings within the Form Builder. These components are more commonly used on traditional web forms and should be familiar components if you have ever used a Form Builder in the past. You can find information for each of the Basic Components like unique settings, JSON code, and field examples.

{% embed url="https://www.loom.com/share/c53492d23f6146f192fdf62e53db2790" %}

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Text Field</strong></td><td>Used for short and general text input</td><td></td><td><a href="#text-field">#text-field</a></td></tr><tr><td><strong>Text Area</strong></td><td>A multi-line input field that allows for longer text </td><td></td><td><a href="#text-area">#text-area</a></td></tr><tr><td><strong>Number</strong></td><td>Input field limited to number type values</td><td></td><td><a href="#number">#number</a></td></tr><tr><td><strong>Password</strong></td><td>An input field with HTML type set to Password</td><td></td><td><a href="#password">#password</a></td></tr><tr><td><strong>Checkbox</strong></td><td>A boolean checkbox</td><td></td><td><a href="#check-box">#check-box</a></td></tr><tr><td><strong>Select Box</strong></td><td>A multi-option checkbox</td><td></td><td><a href="#select-box">#select-box</a></td></tr><tr><td><strong>Select</strong></td><td>Selectable values presented in a dropdown</td><td></td><td><a href="#select">#select</a></td></tr><tr><td><strong>Radio</strong></td><td>Select a single option from a list of options </td><td></td><td><a href="#radio">#radio</a></td></tr><tr><td><strong>Button</strong></td><td>Buttons perform various actions within the form</td><td></td><td><a href="#button">#button</a></td></tr></tbody></table>



### Text Field

A Text Field can be used for short and general text input. There are options to define input masks and validations, allowing users to structure information into desired formats. Additionally, this component can be converted into a string-based date/time picker.

{% tabs %}
{% tab title="Unique Settings" %}
**Widget:**\
The widget is the display UI used to input the value of the field. By default, the widget will be set to a traditional Input Field, however, you can change the widget to turn the text field into a calendar picker.&#x20;

![](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MPHoF2HwOA0s5HV_AIB%2F-MdH2O2dv9SmsMsYSl1K%2F-MdH90sm-iqc0TYmfuDp%2Fchrome_mZa4gfuOMo.png?alt=media\&token=fd8323b2-a517-4f44-a440-8b92f95199ff)

When set, the Textfield is converted to a string-based Calendar Widget. This component stores dates as plain strings, meaning the saved values remain fixed and do **not** adjust based on the user's location or timezone.&#x20;

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FfOCTmX5uo7xMEuotJsqy%2Fcalendarwidget.jpg?alt=media&#x26;token=b2c9f021-a8c4-4958-8b5b-4b704706abff" alt=""><figcaption></figcaption></figure>

**Widget Settings:**\
When the Calendar Picker setting is selected, a new code block appears within the component settings that allows the user to customize the widget by editing its JSON configuration.

<pre><code>{
  "<a data-footnote-ref href="#user-content-fn-1">type</a>": "calendar",
  "altInput": true,
  "<a data-footnote-ref href="#user-content-fn-2">allowInput</a>": true,
  "<a data-footnote-ref href="#user-content-fn-3">clickOpens</a>": true,
  "<a data-footnote-ref href="#user-content-fn-4">enableDate</a>": true,
  "<a data-footnote-ref href="#user-content-fn-5">enableTime</a>": true,
  "mode": "single",
  "<a data-footnote-ref href="#user-content-fn-6">noCalendar</a>": false,
  "<a data-footnote-ref href="#user-content-fn-7">format</a>": "yyyy-MM-dd hh:mm a",
  "<a data-footnote-ref href="#user-content-fn-8">dateFormat</a>": "yyyy-MM-ddTHH:mm:ssZ",
  "useLocaleSettings": false,
  "<a data-footnote-ref href="#user-content-fn-9">hourIncrement</a>": 1,
  "<a data-footnote-ref href="#user-content-fn-10">minuteIncrement</a>": 5,
  "<a data-footnote-ref href="#user-content-fn-11">time_24hr</a>": false,
  "saveAs": "date",
  "displayInTimezone": "",
  "timezone": "",
  "disable": [],
  "<a data-footnote-ref href="#user-content-fn-12">minDate</a>": "",
  "<a data-footnote-ref href="#user-content-fn-12">maxDate</a>": ""
}
</code></pre>

***

**Input Mask:** Use an Input Mask when a specific input format is needed. This is useful for enforcing formats like phone numbers, postal codes, SSN, etc.&#x20;

**Display Mask:** A display mask helps to display the input in a readable way, this won't affect the value which will be saved (to affect both view and saved value, delete Display Mask and use Input Mask).

_Mask Examples_

9: numeric\
a: alphabetical\
\*: alphanumeric\
\
Example a Phone Number mask: (999) 999-9999\
\
See the [**jquery.inputmask documentation**](https://github.com/RobinHerbots/jquery.inputmask) for more information.

**Apply Mask On:** Determines when this component should trigger the configured mask. Defaults to _Change._&#x20;

_Change_ - Validation will actively trigger any time there is a change in the field. This is the default option for every field.

_Blur_ - Validation will only trigger when the field is no longer focused.

**Input Mask Placeholder Char:** Specify a character to be used as a placeholder in the field.\
\
E.g., ˍ&#x20;

Placeholder char will be replaced by a space if it is used inside the mask

**Allow Multiple Masks:** Check this setting if the field should allow the end-user to select a mask from a dropdown menu.&#x20;

Once selected, a grid will appear where you can add a label and corresponding input mask. Click the '+ Add Another' button to add a new Input Mask.
{% endtab %}

{% tab title="Field Examples" %}
{% embed url="https://codepen.io/JeriahFormio/pen/eYjrpeL" %}
{% endtab %}

{% tab title="Guidance" %}
**When should I use the Text Field component?**

* **Unpredictable or freeform responses.** If you can’t reasonably predict a user’s answer to a prompt and there might be wide variability in users’ answers.
* **Input simplicity.** When using another type of input will make answering more difficult. For example, birthdays and other known dates are easier to type in than they are to select from a [**date picker**](https://designsystem.digital.gov/components/date-picker)**.**
* **Pasted content.** When users want to be able to paste in a response.
{% endtab %}

{% tab title="JSON" %}
{% code overflow="wrap" %}
```
{
  "label": "Text Field",
  "disableSortingAndFiltering": false,
  "tableView": true,
  "key": "textField",
  "type": "textfield",
  "input": true
}
```
{% endcode %}

[**Click here for a full list of JSON Schema definitions**](https://github.com/formio/formio.js/wiki/Components-JSON-Schema#common-parameters)
{% endtab %}
{% endtabs %}

### Text Area

A Text Area is a multi-line input field that allows for longer text. The Text Area can also be converted to WYSIWYG content editor. &#x20;

{% tabs %}
{% tab title="Unique Settings" %}
**Rows**: Controls how many default rows are set in the Text Area

**Editor:** This option will convert the text area into one of the following WYSIWYG Editors:\
&#xNAN;_&#x4E;ote: Rich text editors may affect the accessibility of forms that use them._

* [**Ace**](https://ace.c9.io/)
* [**CKEditor**](https://ckeditor.com/)
* [**Quill**](https://quilljs.com/)

_Enable Image Upload_ - Check this setting to allow image uploads to the WYSIWYG editor.&#x20;

_Image Upload Storage_ - Select the Storage provided integrated within the Project.&#x20;

**Save As** - This setting determines how the value should be entered and stored in the database:

* _String_
* _JSON_
* _HTML_

**Auto Expand:** The Text Area will automatically expand vertically as the user types into the field.

**Enable Image Upload:** Allows the user to upload an image to the WYSIWG Editor&#x20;

**Editor Settings:** The following documenation will allow you tooverride the code base of the WYSIWYG Editor, customizing the UI and functionality specific to your needs.

[**Override CKEditor**](../../../faq/tutorials-and-workflows/override-ckeditor)
{% endtab %}

{% tab title="Field Examples" %}
{% embed url="https://codepen.io/JeriahFormio/pen/YzOrBmR" %}
{% endtab %}

{% tab title="Guidance" %}
-Use the Text Area when larger text input is required

-Switch the Text Area to a WYSWIG to give the user the ability to format and customize the text input.
{% endtab %}

{% tab title="JSON" %}
```
{
  "label": "Text Area",
  "autoExpand": false,
  "tableView": true,
  "key": "textArea",
  "type": "textarea",
  "input": true
}
```

#### Specific Properties

| Property | Description                                                  | Value                                                                               | Required | Default |
| -------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------- | -------- | ------- |
| rows     | How many rows this text area should contain.                 | Any `integer`                                                                       | `true`   | 3       |
| wysiwyg  | Determines if this text area should attach a wysiwyg editor. | `true` for default wysiwyg configuration, or a JSON object of the wysiwyg settings. | `false`  | false   |

[**Click here for a full list of JSON Schema definitions**](https://github.com/formio/formio.js/wiki/Components-JSON-Schema#common-parameters)
{% endtab %}
{% endtabs %}

### Number

Use a Number field whenever a field should be limited to a number value type. You can configure options for thousands separators, decimal places, and decimal requirements.

{% tabs %}
{% tab title="Unique Settings" %}
**Use Thousands Separator:** Check this setting if you would like the value in this component to separate thousands by a local delimiter.

**Decimal Places:** The maximum number of decimal places for the values in this field.

**Require Decimals:** Always show decimals for this field, even if trailing zeros.

[**Decimal Symbol**: Change the default Decimal Symbol for the Number component.](#user-content-fn-13)[^13]&#x20;
{% endtab %}

{% tab title="Field Examples" %}
{% embed url="https://codepen.io/JeriahFormio/pen/qByJoBq" %}
{% endtab %}

{% tab title="Guidance" %}
* Use the Number component when dealing with input types that will be specific to numeric input
* Use the decimal places settings for numeric requirements like a percentage that may need specific decimal places included in the submission
{% endtab %}

{% tab title="JSON" %}
```
{
  "label": "Number",
  "mask": false,
  "tableView": false,
  "delimiter": false,
  "requireDecimal": false,
  "inputFormat": "plain",
  "truncateMultipleSpaces": false,
  "key": "number1",
  "type": "number",
  "input": true
}
```

#### Specific Properties

\


<table><thead><tr><th>Property</th><th width="196">Description</th><th>Value</th><th width="116">Required</th><th>Default</th></tr></thead><tbody><tr><td>validate.min</td><td>The minimum value this number could be</td><td>Any number</td><td><code>false</code></td><td></td></tr><tr><td>validate.max</td><td>The maximum value this number could be</td><td>Any number</td><td><code>false</code></td><td></td></tr><tr><td>validate.step</td><td>The granularity of this number input</td><td>Any number</td><td><code>false</code></td><td><code>any</code></td></tr><tr><td>validate.integer</td><td>If this number should be an integer</td><td>boolean</td><td><code>false</code></td><td></td></tr></tbody></table>

[**Click here for a full list of JSON Schema definitions**](https://github.com/formio/formio.js/wiki/Components-JSON-Schema#common-parameters)
{% endtab %}
{% endtabs %}

### Password

The password field has the same options as a text field component. It differs from a text field in that its HTML `<input>` type will be password instead of text. This will cause the field to display hidden input symbols instead of the entered value.

{% tabs %}
{% tab title="Unique Settings" %}
There are no unique settings for the Password component.
{% endtab %}

{% tab title="Field Examples" %}
{% embed url="https://codepen.io/JeriahFormio/pen/rNrqdMx" %}
{% endtab %}

{% tab title="JSON" %}
```
{
  "label": "Password",
  "tableView": false,
  "key": "password1",
  "type": "password",
  "input": true,
  "protected": true
}
```

[**Click here for a full list of JSON Schema definitions**](https://github.com/formio/formio.js/wiki/Components-JSON-Schema#common-parameters)
{% endtab %}
{% endtabs %}

### Check Box

A check box can be used for boolean value input field. It can either be checked (true) or unchecked (false). There are options to set Shortcut and Input Type.

{% tabs %}
{% tab title="Unique Settings" %}
**Shortcut:**  Add a keyboard shortcut to check/uncheck the component.

**Input Type:** The input type can be changed from a single input value checkbox or a multi-valued radio component.&#x20;

The Radio type option is used when [**setting up dynamic Radio values**](https://help.form.io/userguide/pdf#checkboxes-and-radios) for a PDF First form.
{% endtab %}

{% tab title="Field Examples" %}
{% embed url="https://codepen.io/JeriahFormio/pen/WNKazLN" %}
{% endtab %}

{% tab title="Guidance" %}
* Use [**Custom CSS Classes**](../../../forms/pdf#radio-and-checkbox-styles) to change the UI of the Checkbox.
{% endtab %}

{% tab title="JSON" %}
```
{
  "label": "Checkbox",
  "tableView": false,
  "key": "checkbox",
  "type": "checkbox",
  "input": true
}
```

[**Click here for a full list of JSON Schema definitions**](https://github.com/formio/formio.js/wiki/Components-JSON-Schema#common-parameters)
{% endtab %}
{% endtabs %}

### Select Box

This multi-valued component allows users to select one or more options in checkbox style format. Set your values within the Data tab of the settings. Apply unique settings such as value shortcuts and min/max value validation.

{% tabs %}
{% tab title="Unique Settings" %}
**Data Source Type:** The source to use for the Select Box options:&#x20;

**Values:** Create your own list of static values for the Select Box options. The Label is the front-end identifier for the end user. The value is the back-end identifier for the option and is what is saved to the Database.

{% hint style="warning" %}
When setting the option _**value**,_ use only Strings or Numeric values.&#x20;
{% endhint %}

#### **Data Source URL:**&#x20;

Designate a URL that will provide the option values for the Select Dropdown. Use the Item Template to determine what part of the URL's object will be used as.&#x20;

{% hint style="info" %}
When the Data Source URL provides an **array** of JSON objects, you must specify a **Value** **Property** that corresponds to the desired property within each object which is set in the Item Template.

\
When the Data Source URL is a **string**, the **Value Property** setting can be left **empty**.&#x20;
{% endhint %}

For instance, if you want to populate a Select Box with a list of U.S. states, you can achieve this by using an external JSON URL to supply the component's values.

1. Edit the Select Box settings and click the **Data** tab
2. Input the **Data Source URL** endpoint\
   &#xNAN;_&#x54;his example is using a U.S. state endpoint_ \
   &#xNAN;_`https://cdn.rawgit.com/mshafrir/2646763/raw/states_titlecase.json`_
3.  &#x20;Configure the **Value Property** to match a specific property of the JSON object. This Value Property will be stored in the metadata to represent the option in the back end.

    ```
    abbreviation
    ```

{% hint style="info" %}
In this example, the **Data Source URL** endpoint is an **array,** so a  proprety Value Property&#x20;
{% endhint %}

4. Set the **Item Template** to configure the displayed value. \
   `{{ item.name }}`

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FzZFjmmDQyprZRMkCrE1b%2Fcomp.jpg?alt=media&#x26;token=903bd168-d6bf-470c-b0f5-7f74763fa05a" alt=""><figcaption></figcaption></figure>

This example is utilizing the follow URL endpoint containing the following JSON object structure:

```
[
    {
        "name": "Alabama",
        "abbreviation": "AL"
    },
    {
        "name": "Alaska",
        "abbreviation": "AK"
```

**Shortcut:** Add a keyboard shortcut for the designated option.

**Options Label Position:** Determines the position of the option label relative to it's checkbox

**Inline Layout:** Displays the option values horizontally

**Min/Max Checked Number:** Validation that determines the minimum and maximum amount of options to check. Checked options below the minimum will trigger front-end validation. When the maximum amount of options is checked, the remaining options will become disabled.&#x20;

**Min/Max Checked Error Message:** Determines the validation message displayed to the user for the minimum or maximum option amount.
{% endtab %}

{% tab title="Field Examples" %}
{% embed url="https://codepen.io/JeriahFormio/pen/MWBzmmB" %}
{% endtab %}

{% tab title="Guidance" %}
* Use the **hamburger** icon to rearrange your options.
{% endtab %}

{% tab title="JSON" %}
```
{
  "label": "Select Boxes",
  "optionsLabelPosition": "right",
  "tableView": false,
  "defaultValue": {
    "a": false,
    "b": false,
    "c": false
  },
  "values": [
    {
      "label": "A",
      "value": "a",
      "shortcut": ""
    },
    {
      "label": "B",
      "value": "b",
      "shortcut": ""
    },
    {
      "label": "C",
      "value": "c",
      "shortcut": ""
    }
  ],
  "key": "selectBoxes",
  "type": "selectboxes",
  "input": true,
  "inputType": "checkbox"
}

```

#### Specific Properties

| Property      | Description                                                                                  | Value                     | Required | Default |
| ------------- | -------------------------------------------------------------------------------------------- | ------------------------- | -------- | ------- |
| hideLabel     | Whether to hide the checkbox label or not when showing it in the form.                       | `true` or `false`         | `false`  | `true`  |
| datagridLabel | The label to show as the column name when this element is placed within a data grid element. | Any `string`              | `false`  |         |
| name          | The HTML name to provide to this checkbox input                                              | Any valid HTML name value | `false`  |         |
| value         | The HTML value to provide to this checkbox input                                             | Any valid HTML value      | `false`  |         |

[**Click here for a full list of JSON Schema definitions**](https://github.com/formio/formio.js/wiki/Components-JSON-Schema#common-parameters)
{% endtab %}
{% endtabs %}

### Select

The Select component displays a list of values in a dropdown list where users can select one of the values. This component has flexibility on where the data source originates from. There is also a large offering of settings providing different ways of filtering, querying, and loading data values. &#x20;

{% tabs %}
{% tab title="Unique Settings" %}
**Widget Type:** Change the Select dropdown widget type:

[**Choices.js**](https://choices-js.github.io/Choices/)

[**HTML 5**](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select)

**Unique Options:** Display only unique dropdown options removing repeated values.

**Multiple Values:** Allows the user to select more than one option. Options are saved like tags on the field when the setting is enabled.

**Data Source Type:** The source to use for the Select component options:&#x20;

**Value**, **URL**, **Resource**, **Raw** **JSON**, and **Custom.**&#x20;

_(More information in the next tab Data Souce Types)_&#x20;

**Storage Type:** Select how you want the field data to be stored. Defaults to 'Autotype' if an option is not selected:

String, Number, Boolean, Object

**ID Path:** Designate the path to select the option ID

**Item Template:** HTML template that determines how the Select options are displayed within the dropdown. You can use the **item** variable to access the current object in the array.&#x20;

EG embed the value by using `{{ item.value }}` in a template.

**Lazy Load Data:** When set, a request will not be fired to the URL until this control is within focus. This can improve performance if you have many Select dropdowns on your form where the APIs will only fire when the field is activated.

**Request Headers**: Set any headers that should be sent along with the request to the url, useful for authentication.

**Data Path:** The property within the source data, where iterable items reside.&#x20;

For example: results.items or results\[0].items

**Value Property:** The property of each item in the data source to use as the select value. If not specified, the item itself will be used.

**Disable Limiting Response:** When enabled, the request will not include the limit and skip options within the query string. This can help with unnecessary requests and performance.&#x20;

**Search Query Name:** The name of the search query string parameter used when sending a request to filter results with. The server at the URL must handle this query parameter. If URL or Resource is selected as Data Source Type, enter the name of the search query parameter to filter requests with.&#x20;

For example, if your URL is `http://api.dogs.com/dogs`, and Search Query Name is set to `type`, and then the user types `nice` in the Select field, then this component will send a request to `http://api.dogs.com/dogs?type=nice` and update the Select items with the results. If this option is omitted, no new requests will be made when a user enters text in the select field.

**Search Delay Request:** The delay in seconds before the search request is sent, measured from the last character input in the search field. The default is set to 0.3

**Filter Query:** Provide additional filtering within the dropdown using query parameters.

**Sort Query:** Provide additional sorting within the dropdown using query parameters.&#x20;

|                     |                                                                                   |
| ------------------- | --------------------------------------------------------------------------------- |
| created             | Returns results based on created date of submissions values in ascending order    |
| -created            | Returns results based on created date of submissions values in desecending order  |
| data.propertyname   | Returns results based on alpha order of the submission values in ascending order  |
| -data.propertyname  | Returns results based on alpha order of the submission values in descending order |
| skip=10sort=created | skips the first 10 results based on creation date in ascending order              |
| skip=5sort=-created | skips the first 10 results based on creation date in ascending order              |

**Limit:** Use this to limit the number of items to request or view within the select field dropdown.

|    |                                                                                                                                    |
| -- | ---------------------------------------------------------------------------------------------------------------------------------- |
| 10 | Returns only 10 values. When user scrolls to the bottom of the dropdown list, an API call is made returning the remaining results. |

**Formio Authenticate**: Check this if you would like to use Formio Authentication with the request.

**Disables Storing Request Result in the Cache:** Check it if you don't want the requests and their results to be stored in the cache. By default, it is stored and if the Select tries to request the same URL with the same parameters, the cached data will be returned. It allows to increase performance, but if the remote source's data is changing quite often and you always need to keep it up-to-date, uncheck this option.

**Refresh Options On:** Refresh the field options based on a change from another field on the form, or any change on the form. This is helpful when dealing with dynamic values, such as the [**Cascading Select Dropdowns**](../../../faq/tutorials-and-workflows/cascading-select-dropdowns)

**Refresh Options On Blur:** Refresh the field options when a specific field or any field on the form is blurred[^14].&#x20;

**Clear Value Option On Refresh:** Clears any selected value if the field is reset by the Refresh Options On setting.

**Enable Static Search:** When checked, the select dropdown will allow for searching within the static list of items provided.

**Search Threshold:** Determines when the select component match algorithm gives up. A threshold of 0.0 requires a perfect match, a threshold of 1.0 would match anything. This setting is set to 0.3 by default.

**Read Only Value:** Check this if you would like to only display the value when in Read Only mode.

**Choices.js options:** A raw JSON object to use as options for the Select component. Refer to the [**Choices.js documentation**](https://github.com/Choices-js/Choices#readme) for more information.

**Use Exact Search:** Disables the Search Algorithm and only allows exact searches to return an option.
{% endtab %}

{% tab title="Data Source Types" %}
### **Values**

Create your own list of static values for the select dropdown. The default source type for the Select component. The Label is the front-end identifier for the end user. The value is the back-end identifier for the option and is what is saved to the Database.

{% hint style="warning" %}
When setting the option _**value**,_ use only Strings or Numeric values.&#x20;
{% endhint %}

### **URL**

&#x20;Designate a URL that will provide the option values for the Select Dropdown. Use the Item Template to determine what part of the URL's object will be used as the option values.&#x20;

For example, suppose you wish to populate your Select dropdown with a list of all States of the U.S. You can use an external JSON URL like the following.

```
https://cdn.rawgit.com/mshafrir/2646763/raw/states_titlecase.json
```

Place the URL within the **Data Source URL**. Provide a **Value Property** to represent the option which is what will save within the meta-data. When the value is left blank, the entire object will be saved for the option. Modify the **Item Template** to determine what part of the object the end user will see when choosing an option.&#x20;

In the image below, the abbreviation, which is set by the **Value Property**, will be saved in the meta-data to represent the option within the back end. The end user will see the State name, set by the **Item Template**, for the option on the front end.

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FQgDR3SKcLOGN7E5rh5aB%2Furl.png?alt=media&#x26;token=62d90b1c-b833-4f48-ae1a-5edba3ef03b1" alt=""><figcaption></figcaption></figure>

**Data Source URL:** The URL that will return the JSON array



### **Resource**

Source of data is mapped to a Resource within your project to populate the entire Resource Object or underlying field data within the selected Resource as the Select component options.&#x20;

**Resource:** Select which Resource within your project the Select component will map to. For additional information and design consideration, refer to the document "[Resource as Select Component Data Source](form-components/resource-as-select-component-data-source)."

**Value Property:** Select which field within the chosen Resource the Select component will pull data from. Leave this empty to reference the entire Resource object.

\*When a value property is selected, the Item Template will automatically be set based on your selection.

**Select Fields:** The properties on the resource to return as part of the options. Separate property names by commas. If left blank, all properties will be returned.

**Add Resource:** Dynamically adds a new record to the connected Resource&#x20;



### **Raw JSON:**

Provide raw JSON data as the select field value.&#x20;

**Data Source Raw JSON:** This is where you will save your JSON data

```
[{"name": "John", "email": "john.doe@test.com"}, {"name": "Jane", "email": "jane.doe@test.com"}].
```

###

### **Custom:**

Write custom code to provide value options for the Select component.

**Custom Values:** Write custom code to return the value options or a promise with value options. The form data object is available.

```
values = data['myKey'];
```
{% endtab %}

{% tab title="Field Examples" %}
{% embed url="https://codepen.io/JeriahFormio/pen/KKBrBWY" %}
{% endtab %}

{% tab title="Guidance" %}
**Organize your values**

Use the hamburger icon to rearrange your option values within the Select settings.

**Dynamic Select Filtering**

A very common use case that many people have in forms is to dynamically filter a Select dropdown based on the selection of another Select dropdown. The most typical use case is a form that provides the Make, Model and Year of vehicles where when you select the Make dropdown, it filters the Model dropdown for those that are inside that Make. This functionality is covered in detail in our [**user guide resources section**](https://form-io.gitbook.io/help/userguide/resources#dynamic-select-filtering).
{% endtab %}

{% tab title="JSON" %}
```json
{
  "label": "Select",
  "widget": "choicesjs",
  "tableView": true,
  "data": {
    "values": [
      {
        "label": "A",
        "value": "a"
      },
      {
        "label": "B",
        "value": "b"
      },
      {
        "label": "C",
        "value": "c"
      }
    ]
  },
  "key": "select1",
  "type": "select",
  "input": true
}
```

The Select component has many unique properties. [**Follow the link**](https://github.com/formio/formio.js/wiki/Select-Component) for more details
{% endtab %}
{% endtabs %}

### Radio

The radio component is a field that allows users to select a single option from a list of options displayed in radio-style format. Users can click a selected option to deselect it, returning the field back to its original state. allows

{% tabs %}
{% tab title="Unique Settings" %}
**Data Source Type:** The source to use for the Select Box options:&#x20;

**Values:** Create your own list of static values for the Select Box options. The Label is the front-end identifier for the end user. The value is the back-end identifier for the option and is what is saved to the Database.

{% hint style="warning" %}
When setting the option _**value**,_ use only Strings or Numeric values.&#x20;
{% endhint %}

**Data Source URL:** Designate a URL that will provide the option values for the Select Dropdown. Use the Item Template to determine what part of the URL's object will be used as the option values.&#x20;

_For example_, suppose you wish to populate your Select Box with a list of all U.S. States of You can use an external JSON URL like the following.

```
https://cdn.rawgit.com/mshafrir/2646763/raw/states_titlecase.json
```

Place the URL within the **Data Source URL**. Provide a **Value Property** to represent the option which is what will save within the meta-data. When the value is left blank, the entire object will be saved for the option. Modify the **Item Template** to determine what part of the object the end user will see when choosing an option.&#x20;

In the image below, the abbreviation, set by the **Value Property**, will be saved in the meta-data to represent the option within the back end. The end user will see the State name, set by the **Item Template**, for the option on the front end.

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FDY2ecYm1MOBcithE6LxL%2FURL%20Select%20Box.jpg?alt=media&#x26;token=2aae5aa6-d299-4800-9c49-4d29cc6b5c05" alt="" width="495"><figcaption></figcaption></figure>

**Shortcut:** Add a keyboard shortcut for the designated option.

**Options Label Position:** Determines the position of the option label relative to the option bubble

**Inline Layout:** Displays the option values horizontally
{% endtab %}

{% tab title="Field Examples" %}
{% embed url="https://codepen.io/JeriahFormio/pen/QWBJVpj" %}
{% endtab %}

{% tab title="Guidance" %}
* Use the hamburger icon to rearrange your option values.&#x20;
{% endtab %}

{% tab title="JSON" %}
```
{
  "label": "Radio",
  "optionsLabelPosition": "right",
  "customClass": "pl-3",
  "inline": false,
  "tableView": false,
  "values": [
    {
      "label": "A",
      "value": "a",
      "shortcut": ""
    },
    {
      "label": "B",
      "value": "b",
      "shortcut": ""
    },
    {
      "label": "C",
      "value": "c",
      "shortcut": ""
    }
  ],
  "key": "radio",
  "type": "radio",
  "input": true
}
```

#### Specific Properties

| Property | Description               | Value                                                                                                                                                                                                                               | Required | Default |
| -------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- |
| values   | An array of value objects | <p>Array of value objects, where each item in the array has the following properties.</p><ul><li><strong>label</strong> - The label to show for this value</li><li><strong>value</strong> - The value of this radio input</li></ul> | `true`   | \[]     |

[**Click here for a full list of JSON Schema definitions**](https://github.com/formio/formio.js/wiki/Components-JSON-Schema#common-parameters)
{% endtab %}
{% endtabs %}

### Button

Buttons can be added to perform various actions within the form. The most obvious function of the Button component is the Submission action. However, you can also utilize the Button component to trigger events associated with workflow logic, reset field data, authenticate to an OAuth provider, and more.&#x20;

In addition to functionality, the button component offers many settings to change the style and theme of the component.

{% tabs %}
{% tab title="Unique Settings" %}
**Action:** The functionality that executes when the button is clicked. Click the event to show additional settings related to the selected action:

_Submit_ - Submits the form to the back-end server

[_Save In State_](#user-content-fn-15)[^15] - This button action works alongside the Save In State workflow and facilitates a 'Save as Draft' workflow.&#x20;

Inheritently the action will bypass validation giving the submission a different state.

_Reset -_ Reset all fields on the form back to their pristine state

[_Event_](#user-content-fn-16)[^16] - Triggers an 'event' on the form which is usually correlated to application logic or form workflow logic

[_Oauth_](#user-content-fn-17)[^17] - Opens an OAuth authentication popup. This will only work after it has been assigned to an [**OAuth Action**](../../actions#oauth)**.**&#x20;

See the [**OAuth guide**](../../../developers/auth/oauth) for more information on how to set up OAuth in your project.

_Post to URL_ -&#x20;

[_Custom_](#user-content-fn-18)[^18] _-_ Write custom code to fire&#x20;

**Save On Enter:** Use the Enter key to submit the form

**Theme:** Set a theme (color) for the button mapped to [**Bootstrap**](https://getbootstrap.com/docs/4.6/components/buttons/) classes&#x20;

**Size:** Determines the position of the option label relative to the option bubble

**Block Button:** Spans the button horizontally across the form

**Left/Right Icon:** Set an icon to the left or right side of the button label using [**Font Awesome**](https://fontawesome.com/search) icon classes.

**Disable on Form Invalid:** If any field on the form is invalid, disable the button.
{% endtab %}

{% tab title="Field Examples" %}
{% embed url="https://codepen.io/JeriahFormio/pen/MWBzPJG" %}
{% endtab %}

{% tab title="Guidance" %}
* Use the button component to Reset the fields on a form, clearing any data
* Fire off events using the button to initiate complex workflows in conjunction with other components like the [**Data Source**](../premium-components#data-source)
{% endtab %}

{% tab title="JSON" %}
```
{
  "label": "Submit",
  "block": true,
  "leftIcon": "fa fa-send",
  "disableOnInvalid": true,
  "tableView": false,
  "key": "submit",
  "type": "button",
  "input": true,
  "saveOnEnter": false
}
```

The button component has many unique properties. [**Follow the link**](https://github.com/formio/formio.js/wiki/Button-Component) for more details.

[**Click here for a full list of JSON Schema definitions**](https://github.com/formio/formio.js/wiki/Components-JSON-Schema#common-parameters)
{% endtab %}
{% endtabs %}



[^1]: The type of widget

[^2]: Allows the user to manually input the Date/Time values. When set to 'false', the component will disable, forcing the end user to utilize the Calendar UI to select the date and time.

[^3]: When any part of the field is clicked, the Calendar picker will open and display for the end user. When set to 'false', the Calendar widget will only display when the calendar icon is clicked located at the suffix of the field.

[^4]: Enables the user to select or enter a date. When disabled, the widget displays only a time picker, date input won't be available to pick or input.&#x20;

[^5]: Enables the user to select or enter a time. When disabled, the widget displays only a calendar picker, time input won't be available to pick or input.&#x20;

[^6]: Removes the calenar picker from the field

[^7]: The date/time format that will display for the end user.&#x20;

[^8]: The format that it saved in the database. This setting can be different than the 'format' setting'&#x20;

[^9]: The amount the hour will increase or decrease when using the time picker UI. &#x20;

[^10]: The amount the minute value will increase or decrease when using the time picker UI.&#x20;

[^11]: Sets the time format to 24 hours

[^12]: Sets the minimum date that can be entered or selected from the calendar widget

[^13]: This is a hidden setting that can be configured by editing the Number component JSON. Add the following to the schema:

    ```
    "decimalSymbol": ","
    ```

    After saving your changes, the Number component will change the default decimal to the designated symbol. Use this in conjunction with the local delimiter to achieve different kinds of numbering systems.

[^14]: The onblur attribute fires the moment that the element loses focus (when a user leaves the field)

[^15]: **Show Validation** - Show any current Validations on the form

[^16]: **Button Event:** Name the event this button will output to the form.

[^17]: **Oauth Provider** - The OAuth provider to use to log in. Provider integration settings must be implemented within the Stage Settings

[^18]: **Custom Button Logic**: The custom logic to evaluate when the button is clicked.
