Widgets

This is the official documentation of Forest Admin Cloud.

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

• null any: Use the default widget.

• AddressAutocomplete String: Enables quick address input.

• Checkbox Boolean: Display a checkbox with false, true or null values.

• CheckboxGroup StringList, NumberList: Display a group of checkboxes to select multiple values.

• ColorPickerString: Select a color from the color picker.

• CurrencyInput Number: Display a field to enter money amount.

• DatePicker Date, Dateonly, String: Select a date from the date picker.

• Dropdown: Date, Dateonly, Number, String, StringList: Select from a limited set of values.

• FilePicker File, FileList: Display a file uploader to upload files.

• JsonEditorJson: Display a JSON editor with syntax highlighting.

• NumberInputNumber: Display a standard number input.

• NumberInputList NumberList: Display a group of number inputs to select multiple values.

• RadioGroup Date, Dateonly, Number, String: Display a set of radio buttons.

• RichText String: Display a rich text area allowing to input formatted text.

• TextArea String: Display a text area allowing the input of multiple lines of text.

• TextInput String: Display a text box allowing the input of a single line of text.

• TextInputList StringList: Display a group of text inputs to enter multiple values.

• UserDropdown String, StringList: 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.

import type { Agent } from '@forestadmin/forest-cloud';
import { Schema } from '../typings';

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

---

Address Autocomplete

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

Options:

• placeholderString: Shows a hint within the widget when no content is present.

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

Checkbox

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

Options:

• defaultValueBoolean: Specify the default value.

• isRequiredBoolean: Activate this option to only supports two states false and true.

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

Checkbox group

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

Options:

• options* [String or Object] or Function: 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'}]

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' },
  ],
}],

Color picker

The ColorPicker widget enables color selection.

Options:

• enableOpacityBoolean: Enables the option to select colors with adjustable opacity levels.

• placeholderString: Shows a hint within the widget when no content is present.

• quickPalette[String]: Provides a selection of pre-defined Hex or RGBA colors for expedited color choices.

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

Currency

The CurrencyInput widget enables users to input a currency value.

Options:

• base String: When specifying currency, use Unit for whole units and Cent for cents.

• currency* String: Currency code to display in the component. Valid currency ISO codes ↗ is required.
• max Number: Maximum value allowed.

• min Number: Minimum value allowed.

• placeholderString: Shows a hint within the widget when no content is present.

• step Number: The interval between two values.

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

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.

To convert ISO 8601 date strings to Date objects, you can directly parse them as follows:

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

Options:

• format String: The date picker uses moment.js library under the hood. You can refer to this documentation ↗ to specify your date display format.
• max Date: The maximum date allowed.

• min Date: The minimum date allowed.

• placeholderString: Shows a hint within the widget when no content is present.

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',
}],

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* [String or Object] or Function: 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'}]

• placeholderString: Shows a hint within the widget when no content is present.

• search String: 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.

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,
}],

File picker

The FilePicker widget allows to upload a file.

Options:

• extensions[String] or Function: 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 Number or Function: 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.

• maxCountNumber or Function: 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.

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,
}],

JSON Editor

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

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

Number

The NumberInput widget enables users to input numerical values.

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

Number (List)

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

Options:

• allowDuplicates Boolean: Enable/disable duplicate value entry.

• allowEmptyValues Boolean: Enable/disable empty value entry.

• allowReorder Boolean: Enable/disable to reorder values.

• max Number: Maximum value allowed.

• min Number: Minimum value allowed.

• placeholderString: Shows a hint within the widget when no content is present.

• step Number: The interval between two values.

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

Radio button

A RadioButton lets you choose one option from a list.

Options:

• options* [String or Object] or Function: 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'}]

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

Rich text

The rich text widget enables formatted text input.

Options:

• placeholderString: Shows a hint within the widget when no content is present.

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

TextArea

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

Options:

• rows Number: Display the desired number of rows.

• placeholderString: Shows a hint within the widget when no content is present.

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

TextInput

The TextInput widget lets you type one line of text.

Options:

• placeholderString: Shows a hint within the widget when no content is present.

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

TextInput (List)

The TextInputList widget lets you enter multiple text values.

Options:

• allowDuplicates Boolean: Enable/disable duplicate value entry.

• allowEmptyValues Boolean: Enable/disable empty value entry.

• allowReorder Boolean: Enable/disable to reorder values.

• placeholderString: Shows a hint within the widget when no content is present.

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

Time picker

The TimePicker widget helps you choose a time.

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

User

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

Options:

• placeholderString: Shows a hint within the widget when no content is present.

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