<div class="mdx">When the number of choices is small (&lt;=3) the default is a radio widget, otherwise it
is a select widget. You can specify the type to use with <code>widgetType</code>. Any extra props are passed through to the underlying component (eg. <code>showSearch</code> in the last example)</div>

 Basic Usage

basic

<div class="mdx">Pass <code>multiple</code> through to allow selection of multiple values. In this case the value will
be an array. When the number of choices is small (&lt;=3) the default is a checkbox widget, otherwise it
is a select widget. You can specify the type to use with <code>widgetType</code>. Any extra props are passed through to the underlying component (eg. <code>showSearch</code> in the last example)</div>

 Multiple selection

multiple

ChoicesWidget

The specific widget chosen is one of

* [SelectAsyncChoicesWidget](SelectAsyncChoicesWidget) - when `asyncChoices` is provided. `widgetType` is ignored in this case.
* [SelectChoicesWidget](doc:SelectChoicesWidget) - when `widgetType="select"` or `widgetType` is not specified and there is more than 3 choices.
* [RadioChoicesWidget](doc:RadioChoicesWidget) - when `widgetType="radio"` or `multiple={false}` and `widgetType` is not specified and there is 3 or fewer choices.
* [CheckboxChoicesWidget](doc:CheckboxChoicesWidget) - when `widgetType="checkbox"` or `multiple={true}` and `widgetType` is not specified and there is 3 or fewer choices.


props

ChoicesWidgetProps

ReactElement

ValueType

checked

undefined

false

true

name

string

onBlur

__type

onChange

__call

onFocus

type

value

FieldValue

Properties

InputProps

HTMLElement

Any [AsyncChoices](doc:AsyncChoices), if applicable. This typically comes from [Field.asyncChoices](doc:Field#var-asyncChoices).

asyncChoices

AsyncChoicesInterface

Any choices, if applicable. This typically comes from [Field.choices](doc:Field#var-choices).

This can be a `Map` of value to label or an array of 2-element arrays `[value, label]`.


choices

The input props for the widget. This should include, at minimum:

- onChange
- value

Can also include

- name
- onBlur
- onFocus
- type
- checked
- multiple


input

Any extra details such as field errors, touched status etc. The values here depend on the form
library in use. If using [@prestojs/final-form](/docs/final-form/) see [FieldRenderProps](https://final-form.org/docs/react-final-form/types/FieldRenderProps)
for what this will be.

Record

WidgetProps

SingleValue

<div class="mdx">Any extra props are passed through to <a href="https://ant.design/components/checkbox/#Checkbox-Group">Radio.Group</a>. Choices are rendered as:<pre><div class="prism-highlight"><pre class="prism-code-jsx" style="background-color:#282c34;color:#ffffff;font-family:monospace, monospace"><div class="token-line" style="color:#ffffff;font-family:monospace, monospace">&lt;Checkbox.Group&gt;</div><div class="token-line" style="color:#ffffff;font-family:monospace, monospace"> &lt;Radio key=&quot;1&quot; value=&quot;1&quot;&gt;One&lt;/Radio&gt;</div><div class="token-line" style="color:#ffffff;font-family:monospace, monospace"> &lt;Radio key=&quot;2&quot; value=&quot;2&quot;&gt;Two&lt;/Radio&gt;</div><div class="token-line" style="color:#ffffff;font-family:monospace, monospace">&lt;/Checkbox.Group&gt;</div></pre></div></pre> You can customise the component used instead of <code>Radio</code> by passing <code>radioComponent</code> (eg. <code>radioComponent={RadioChoicesWidget.Button}</code>). You can pass any extra props to each <code>Radio</code> by passing <code>choiceProps</code> which is a <code>Map</code> of choice value to the props to apply.</div>

RawValue

number

boolean

Any additional props are passed through to the specify widget

widgetType

Variables

__index

TestDataItem

label

constructor

new Record

item

__get

_key

getLabel

Constructors

Accessors

Methods

React.ReactNode

Choice

If true then multiple values can be selected. When this is true
retrieve() will be passed and return an array rather than a single value.

getChoices

Generate the list of choices. This can return an array of single choices or grouped choices.

A grouped choice is a 2 element Array with a label and a list of choices.


items

getMissingLabel

Return label to use when an item can't be found. This can be used by widgets to control
what is rendered when an item for a value cannot be found (eg. when it's deleted or
when it's loading). The exact details of how this is used depend on the widget.

getValue

Get the value to use for an item. The value should be unique and is what's used when a
choice is selected (eg. it's the value that would be saved to a database).

list

Function to resolve a list of choices based on the provided params.

What this function is passed depends on the implementation but when used with
[useAsyncChoices](doc:useAsyncChoices) it will be passed `query` (the query object eg. to
filter results with), `paginator` (the current paginator if any) and `listOptions` (any
additional options passed on the `listOptions` prop to `useAsyncChoices`).
Official presto widgets all use `useAsyncChoices` and so will use these parameters.


params

Promise

retrieve

Function to resolve specific values. This is used to know how to render the label for a value(s).

The first parameter is the value to retrieve (will be an array when `multiple` is true).

`deps` is the value returned by `useRetrieveProps`.


deps

useListProps

Hook that returns any extra props to pass through to `list` in components/hooks that
consume this (eg. [useAsyncChoices](doc:useAsyncChoices)). This is useful to
store state for things like pagination.

What this function is passed depends on the implementation but when used with
[useAsyncChoices](doc:useAsyncChoices) it will be `query` (the query object eg. to
filter results with) and `listOptions` (any additional options passed on the `listOptions`
prop to `useAsyncChoices`).
Official presto widgets all use `useAsyncChoices` and so will use these parameters.


args

useResolveItems

Resolve the specific instance of an item to use. By default this should just return `item`
but can be used to resolve a specific instance of a class from a cache for example.

useRetrieveProps

Hook that returns props to pass through to `retrieve` in components/hooks that consume this (eg. [useAsyncChoices](doc:useAsyncChoices).
This is useful for things like hooking into an existing cache (eg. [useViewModelCache](doc:useViewModelCache)).
The value returned here is passed as the second parameter to `retrieve`. In addition the `existingValues` key is
passed through to `useAsyncValue` as the list of items it can resolve existing values from.

What this function is passed depends on the implementation but when used with
[useAsyncChoices](doc:useAsyncChoices) it will be passed `id` if there's a current value
and it's not an array, `ids` if there's a current value and it is an array, `existingValues` which is
the values returned by `list` (may be null if `list` not yet called) and `retrieveOptions`
(any additional options passed on the `retrieveOptions` prop to `useAsyncChoices`).
Official presto widgets all use `useAsyncChoices` and so will use these parameters.


A choice is a `value` that identifies the item (eg. an id) and a `label` that
describes the item and is shown to users (eg. the name).

When `multiple` is true multiple values can be selected.

To define async choices two things are required:

1) A function to resolve existing value(s). This is used when viewing existing
   value(s) and need label(s) to show (eg. when displaying a choice on a detail
   view or rendering the value selected on a select widget).
2) A function to list & filter the available  choices. This is used when selecting
   a value (eg. the options shown in a select widget).

Both of these functions may need to store state (eg. pagination for a listing)
or access things from context (eg. read values from a cache). This can be done
via two hooks - `useListProps` and `useRetrieveProps`. This functions should be
called from a component or hook that deals with async choices when calling
`list` and `retrieve` respectively. The return value from the hook is passed to
the corresponding function.

For a default implementation see [AsyncChoices](doc:AsyncChoices)


AsyncChoices

ItemType

null

new AsyncChoices

options

AsyncChoicesInterface.multiple

AsyncChoicesOptions

AsyncChoicesInterface.getChoices

AsyncChoicesInterface.getLabel

AsyncChoicesInterface.getMissingLabel

AsyncChoicesInterface.getValue

AsyncChoicesInterface.list

AsyncChoicesInterface.retrieve

AsyncChoicesInterface.useListProps

AsyncChoicesInterface.useResolveItems

AsyncChoicesInterface.useRetrieveProps

Default implementation for [AsyncChoicesInterface](doc:AsyncChoicesInterface)

All options can be customised via `options`.

You must provide `list` and `retrieve` - everything else can be optional with the following restrictions:

* `getLabel` - this is optional if items returned by `list` and `retrieve` implement [NodeLabeled](doc:NodeLabeled) otherwise it must be provided
* `getValue` - this is optional if items returned by `list` and `retrieve` implement [Identifiable](doc:Identifiable) otherwise it must be provided


	Parameter	Type	Description
*	props		Any additional props are passed through to the specify widget
*	props.input	InputProps	The input props for the widget. This should include, at minimum: onChange value Can also include name onBlur onFocus type checked multiple
*	props.choices	Map\|[(RawValue\|RawValue[]), string][]	The choices to render. This can be a `Map` of value to label or an array of 2-element arrays `[value, label]`.
	props.multiple	boolean	Whether multiple values are accepted
	props.widgetType	"select"\|"checkbox"\|"radio"	Choices are rendered as either SelectChoicesWidget, RadioChoicesWidget (only if `multiple=false`) or CheckboxChoicesWidget (only if `multiple=true) Specify`select`, 'radio', or` checkbox`to choose one of these or leave blank to select based on number of choices (if > 3 defaults to 'select' otherwise 'checkbox' or 'radio' depending on value of`multiple`).

ChoicesWidget
This is a React component

Examples

Basic Usage

Multiple selection

ExamplesJavascriptTypescript

Basic Usage

Multiple selection

Examples