# Widgets

{% hint style="success" %}
This is the official documentation of Forest Admin Cloud.
{% endhint %}

Widgets improve your Forms by offering a range of input display options:

* `null` *<mark style="color:green;">any</mark>*: Use the default widget.
* [`AddressAutocomplete`](#address-autocomplete) *<mark style="color:green;">String:</mark>* Enables quick address input.
* [`Checkbox`](#checkbox) *<mark style="color:green;">Boolean</mark>*: Display a checkbox with `false`, `true` or `null` values.
* [`CheckboxGroup`](#checkbox-group) *<mark style="color:green;">StringList, NumberList</mark>*: Display a group of checkboxes to select multiple values.
* [`ColorPicker`](#color-picker)*<mark style="color:green;">String</mark>*: Select a color from the color picker.
* [`CurrencyInput`](#currency) *<mark style="color:green;">Number</mark>*: Display a field to enter money amount.
* [`DatePicker`](#date-picker) *<mark style="color:green;">Date, Dateonly, String</mark>*: Select a date from the date picker.
* [`Dropdown`](#dropdown): *<mark style="color:green;">Date, Dateonly, Number, String, StringList</mark>*: Select from a limited set of values.
* [`FilePicker`](#file-picker) *<mark style="color:green;">File, FileList</mark>*: Display a file uploader to upload files.
* [`JsonEditor`](#json-editor)*<mark style="color:green;">Json</mark>*: Display a JSON editor with syntax highlighting.
* [`NumberInput`](#number)*<mark style="color:green;">Number</mark>*: Display a standard number input.
* [`NumberInputList`](#numbers) *<mark style="color:green;">NumberList</mark>*: Display a group of number inputs to select multiple values.
* [`RadioGroup`](#radio-button) *<mark style="color:green;">Date, Dateonly, Number, String</mark>*: Display a set of radio buttons.
* [`RichText`](#rich-text) *<mark style="color:green;">String</mark>*: Display a rich text area allowing to input formatted text.
* [`TextArea`](#textarea) *<mark style="color:green;">String</mark>*: Display a text area allowing the input of multiple lines of text.
* [`TextInput`](#textinput) *<mark style="color:green;">String</mark>*: Display a text box allowing the input of a single line of text.
* [`TextInputList`](#textinput-list) *<mark style="color:green;">StringList</mark>*: Display a group of text inputs to enter multiple values.
* [`UserDropdown`](#user) *<mark style="color:green;">String, StringList</mark>*: Display a dropdown with users in the ForestAdmin project.

To make the code easier to read, all the code snippets below should be wrapped in the following code. Ensure you update the collection and action names as needed.

<pre class="language-typescript"><code class="lang-typescript">import type { Agent } from '@forestadmin/forest-cloud';
import { Schema } from '../typings';

export default function customizeAgent(agent: Agent&#x3C;Schema>) {
<strong>  agent.customizeCollection('customers', collection => {
</strong>    collection.addAction('My action', {
    scope: 'Single',
    // Insert the code snippet here.
    execute: async context => {
    },
  });
  });
}
</code></pre>

***

### Address Autocomplete

The `AddressAutocomplete` facilitates quick input of addresses by offering suggestions from the Google Maps API.

Options:

* `placeholder`*<mark style="color:green;">String</mark>*: Shows a hint within the widget when no content is present.

```typescript
form: [{
  label: 'Address',
  type: 'String',
  widget: 'AddressAutocomplete',
  placeholder: 'Type the address here',
}],
```

<figure><img src="/files/dM5AxMFhaiv4xElVipxw" alt=""><figcaption></figcaption></figure>

### Checkbox

The `Checkbox` widget enables users to toggle a boolean value. The default behavior allows three states: `false`, `true`, and `null`.

Options:

* `defaultValue`*<mark style="color:green;">Boolean</mark>*: Specify the default value.
* `isRequired`*<mark style="color:green;">Boolean</mark>*: Activate this option to only supports two states `false` and `true`.

```typescript
form: [{
  label: 'Send a notification',
  type: 'Boolean',
  widget: 'Checkbox',
  isRequired: true,
  defaultValue: true,
}],
```

<figure><img src="/files/7dxOTrA2seV6m9JJhL48" alt=""><figcaption></figcaption></figure>

### Checkbox group

The `CheckboxGroup` allows to select multiple values from a list of options.

Options:

* `options`<mark style="color:red;">\*</mark> *<mark style="color:green;">\[String</mark>* <mark style="color:green;">or</mark> *<mark style="color:green;">Object]</mark>* <mark style="color:green;">or</mark> *<mark style="color:green;">Function</mark>*: Specify the list of options available. The supported formats are:
  * `['Good', 'Very good']`
  * `[{value: 2, label: 'Good'}, {value: 3, label: 'Very good'}]`
  * `(context) => ['Good', 'Very good']`
  * `(context) => [{value: 2, label: 'Good'}, {value: 3, label: 'Very good'}]`

```typescript
form: [{
  label: 'Why do you like this product?',
  type: 'StringList',
  widget: 'CheckboxGroup',
  options: [
    { value: 'price', label: 'Good price' },
    { value: 'quality', label: 'Build quality' },
    { value: 'look', label: 'It looks good' },
  ],
}],
```

<figure><img src="/files/iWfdU988LEq9LcM0KYqV" alt=""><figcaption></figcaption></figure>

### Color picker

The `ColorPicker` widget enables color selection.

Options:

* `enableOpacity`*<mark style="color:green;">Boolean</mark>*: Enables the option to select colors with adjustable opacity levels.
* `placeholder`*<mark style="color:green;">String</mark>*: Shows a hint within the widget when no content is present.
* `quickPalette`*<mark style="color:green;">\[String]</mark>*: Provides a selection of pre-defined Hex or RGBA colors for expedited color choices.

```typescript
form: [{
  label: 'Background color',
  type: 'String',
  widget: 'ColorPicker',
  placeholder: 'Select a color',
  isRequired: true,
  enableOpacity: false,
  quickPalette: [
    '#6002ee',
    '#90ee02',
    '#021aee',
    '#d602ee',
    '#ee0290',
    '#ee6002',
  ]},
],
```

<figure><img src="/files/Emjy1upmlsHtHOUm0UUh" alt=""><figcaption></figcaption></figure>

### Currency

The `CurrencyInput` widget enables users to input a currency value.

Options:

* `base` *<mark style="color:green;">String</mark>:* When specifying currency, use `Unit` for whole units and `Cent` for cents.
* `currency`<mark style="color:red;">\*</mark> *<mark style="color:green;">String</mark>*: Currency code to display in the component. Valid currency [ISO codes ↗](https://en.wikipedia.org/wiki/ISO_4217) is required.
* `max` *<mark style="color:green;">Number</mark>*: Maximum value allowed.
* `min` *<mark style="color:green;">Number</mark>*: Minimum value allowed.
* `placeholder`*<mark style="color:green;">String</mark>*: Shows a hint within the widget when no content is present.
* `step` *<mark style="color:green;">Number</mark>*: The interval between two values.

```typescript
form: [{
  label: 'Price',
  type: 'Number',
  widget: 'CurrencyInput',
  placeholder: 'Enter the new price',
  isRequired: true,
  min: 0,
  max: 1000,
  step: 1,
  currency: 'USD',
  base: 'Unit',
}],
```

<figure><img src="/files/BaSXXKPfdKSQGT5kax5u" alt=""><figcaption></figcaption></figure>

### Date picker

The `DatePicker` widget helps you choose a date. If set to `Date`, you can select a date and time. If set to `Dateonly`, you can only pick a date.

{% hint style="info" %}
To convert ISO 8601 date strings to `Date` objects, you can directly parse them as follows:

```typescript
const shippingDate = new Date(context.formValues['Shipping date']));
```

{% endhint %}

Options:

* `format` *<mark style="color:green;">String</mark>*: The date picker uses `moment.js` library under the hood. You can refer to [this documentation ↗](https://momentjs.com/docs/#/displaying/format/) to specify your date display `format.`
* `max` *<mark style="color:green;">Date</mark>*: The maximum date allowed.
* `min` *<mark style="color:green;">Date</mark>*: The minimum date allowed.
* `placeholder`*<mark style="color:green;">String</mark>*: Shows a hint within the widget when no content is present.

```typescript
form: [{
  label: 'Shipping date',
  type: 'Date',
  widget: 'DatePicker',
  format: 'DD-MM-YYYY',
  min: new Date(Date.now() - 10 * 24 * 60 * 60 * 1000),
  max: new Date(),
  placeholder: 'please indicate when you shipped the item',
}],
```

<figure><img src="/files/Jo4KgXgKih1X6O9bwS05" alt=""><figcaption></figcaption></figure>

### Dropdown

The `Dropdown` widget allows to select a value from a list of options.

Options:

Specify the list of options available. The supported formats are:

* `options`<mark style="color:red;">\*</mark> *<mark style="color:green;">\[String</mark>* <mark style="color:green;">or</mark> *<mark style="color:green;">Object]</mark>* <mark style="color:green;">or</mark> *<mark style="color:green;">Function</mark>*: Specify the list of options available. The supported formats are:
  * `['Good', 'Very good']`
  * `[{value: 2, label: 'Good'}, {value: 3, label: 'Very good'}]`
  * `(context, searchValue) => [{value: 2, label: 'Good'}, {value: 3, label: 'Very good'}]`
* `placeholder`*<mark style="color:green;">String</mark>*: Shows a hint within the widget when no content is present.
* `search` *<mark style="color:green;">String</mark>*: Enable users to input text to refine options shown in the dropdown.
  * `disabled`: Users need to scroll to select their desired option.
  * `static`: Users can search for a value by typing terms. The search will be conducted in the browser, based on the labels.
  * `dynamic` The search happens on the backend, using custom code to get the needed options.

```typescript
form: [{
  label: 'Rating',
  type: 'Number',
  widget: 'Dropdown',
  options: [
    { value: 0, label: 'Poor' },
    { value: 1, label: 'Fair' },
    { value: 2, label: 'Good' },
    { value: 3, label: 'Very good' },
    { value: 4, label: 'Excellent' },
  ],
  search: 'disabled',
  placeholder: 'Select a rating',
  isRequired: true,
}],
```

<figure><img src="/files/CDsUOWP7t1iRjfcJESVM" alt=""><figcaption></figcaption></figure>

### File picker

The `FilePicker` widget allows to upload a file.

Options:

* `extensions`*<mark style="color:green;">\[String]</mark>* <mark style="color:green;">or</mark> *<mark style="color:green;">Function</mark>*: The whitelist of file extensions allowed. If not specified, any file extension will be accepted. The value can be either a list of strings or a function that returns a list of strings.
* `maxSizeMb` *<mark style="color:green;">Number</mark>* <mark style="color:green;">or</mark> *<mark style="color:green;">Function</mark>*: The maximum file size for uploads. If not specified, there is no limit. Ensure your server can support the file sizes being uploaded. The value can be either a number or a function that returns a number.
* `maxCount`*<mark style="color:green;">Number</mark>* <mark style="color:green;">or</mark> *<mark style="color:green;">Function</mark>:* The maximum number of files allowed to be uploaded. If not specified, any number of files is allowed. The value can be either a number or a function that returns a number.

```typescript
form: [{
  label: 'Avatar picture',
  type: 'File',
  widget: 'FilePicker',
  description: 'Upload a profile picture or leave it to use the default one',
  extensions: ['png', 'jpg'],
  maxSizeMb: 20
}, {
  label: 'Legal documents',
  type: 'FileList',
  widget: 'FilePicker',
  description: 'Upload up to 4 documents to identify the user',
  extensions: ['png', 'jpg', 'bmp', 'pdf', 'gif'],
  maxSizeMb: 2,
  maxCount: 4,
  isRequired: true,
}],
```

<figure><img src="/files/JP2RsqVvKVvMbYbG1uJU" alt=""><figcaption></figcaption></figure>

### JSON Editor

The `JsonEditor` widget provides an interface focused on JSON syntax highlighting.

```typescript
form: [{
  label: 'Properties',
  type: 'Json',
  widget: 'JsonEditor',
  defaultValue: {
    name: '',
    age: 0,
    city: '',
    country: '',
    is_student: false
  }
}],
```

<figure><img src="/files/8vF4xPiwmTmJwD4jWjnx" alt=""><figcaption></figcaption></figure>

### Number

The `NumberInput` widget enables users to input numerical values.

```typescript
form: [{
  label: 'Quantity',
  type: 'Number',
  widget: 'NumberInput',
  placeholder: 'Enter a quantity',
  isRequired: true,
  min: 0,
  max: 1000,
  step: 1,
}],
```

<figure><img src="/files/QSmM0QofuADhJrqOheGR" alt=""><figcaption></figcaption></figure>

### Number (List)

The `NumberInputList` widget allows to input a list of numberical values.

Options:

* `allowDuplicates` *<mark style="color:green;">Boolean</mark>*: Enable/disable duplicate value entry.
* `allowEmptyValues` *<mark style="color:green;">Boolean</mark>*: Enable/disable empty value entry.
* `allowReorder` *<mark style="color:green;">Boolean</mark>*: Enable/disable to reorder values.
* `max` *<mark style="color:green;">Number</mark>*: Maximum value allowed.
* `min` *<mark style="color:green;">Number</mark>*: Minimum value allowed.
* `placeholder`*<mark style="color:green;">String</mark>*: Shows a hint within the widget when no content is present.
* `step` *<mark style="color:green;">Number</mark>*: The interval between two values.

```typescript
form: [{
  label: 'Step values',
  type: 'NumberList',
  widget: 'NumberInputList',
  placeholder: 'Enter the new step value',
  isRequired: true,
  min: 0,
  max: 1000,
  step: 1,
}],
```

<figure><img src="/files/6fAwaZhdYaHuJZSiZRT1" alt=""><figcaption></figcaption></figure>

### Radio button

A `RadioButton` lets you choose one option from a list.

Options:

* `options`<mark style="color:red;">\*</mark> *<mark style="color:green;">\[String</mark>* <mark style="color:green;">or</mark> *<mark style="color:green;">Object]</mark>* <mark style="color:green;">or</mark> *<mark style="color:green;">Function</mark>*: Specify the list of options available. The supported formats are:
  * `['Good', 'Very good']`
  * `[{value: 2, label: 'Good'}, {value: 3, label: 'Very good'}]`
  * `(context) => ['Good', 'Very good']`
  * `(context) => [{value: 2, label: 'Good'}, {value: 3, label: 'Very good'}]`

```typescript
form: [{
  label: 'Rating',
  type: 'Number',
  widget: 'RadioGroup',
  options: [
    { value: 1, label: 'Good' },
    { value: 0, label: 'Average' },
    { value: -1, label: 'Bad' },
  ]},
],
```

<figure><img src="/files/lrsYnnNrcKng8M16lgh2" alt=""><figcaption></figcaption></figure>

### Rich text

The rich text widget enables formatted text input.

Options:

* `placeholder`*<mark style="color:green;">String</mark>*: Shows a hint within the widget when no content is present.

```typescript
form: [{
  label: 'Comment',
  type: 'String',
  widget: 'RichText',
  isRequired: true,
  placeholder: 'Type your comment here',
}],
```

<figure><img src="/files/Fjwj0Pye3tOrVNfnlHxe" alt=""><figcaption></figcaption></figure>

### TextArea

The `TextArea` widget lets you type in more than one line of text.

Options:

* `rows` *<mark style="color:green;">Number</mark>*: Display the desired number of rows.
* `placeholder`*<mark style="color:green;">String</mark>*: Shows a hint within the widget when no content is present.

```typescript
form: [{
  label: 'Comment',
  type: 'String',
  widget: 'TextArea',
  isRequired: true,
  placeholder: 'Type your comment here...',
  rows: 10,
}],
```

<figure><img src="/files/BswH58Knp7Ix08fqaxIh" alt=""><figcaption></figcaption></figure>

### TextInput

The `TextInput` widget lets you type one line of text.

Options:

* `placeholder`*<mark style="color:green;">String</mark>*: Shows a hint within the widget when no content is present.

```typescript
form: [{
  label: 'Message',
  type: 'String',
  widget: 'TextInput',
  placeholder: 'Enter your message here',
}],
```

<figure><img src="/files/g3tx3ahsn0OCAu4D49wH" alt=""><figcaption></figcaption></figure>

### TextInput (List)

The `TextInputList` widget lets you enter multiple text values.

Options:

* `allowDuplicates` *<mark style="color:green;">Boolean</mark>*: Enable/disable duplicate value entry.
* `allowEmptyValues` *<mark style="color:green;">Boolean</mark>*: Enable/disable empty value entry.
* `allowReorder` *<mark style="color:green;">Boolean</mark>*: Enable/disable to reorder values.
* `placeholder`*<mark style="color:green;">String</mark>*: Shows a hint within the widget when no content is present.

```typescript
form: [{
  label: 'Tag',
  type: 'StringList',
  widget: 'TextInputList',
  isRequired: true,
  placeholder: 'Enter a tag',
}],
```

<figure><img src="/files/VK0EcR80LwqwMGS804br" alt=""><figcaption></figcaption></figure>

### Time picker

The `TimePicker` widget helps you choose a time.

```typescript
form: [{
  label: 'Opening time',
  type: 'Time',
  widget: 'TimePicker',
}],
```

<figure><img src="/files/w3tvxX80srpJV6pXfB4b" alt=""><figcaption></figcaption></figure>

### User

The `UserDropdown` widget lets you select one or more users from your Forest Admin project.

Options:

* `placeholder`*<mark style="color:green;">String</mark>*: Shows a hint within the widget when no content is present.

```typescript
form: [{
  type: 'String',
  label: 'Manager',
  widget: 'UserDropdown',
  placeholder: 'Select the manager in charge',
}],
```

<figure><img src="/files/YSVO9zWrtWXhH2k7C17g" alt=""><figcaption></figcaption></figure>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.forestadmin.com/cloud/code-customization/actions/form/widgets.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.