@dnb/eufemia
Version:
DNB Eufemia Design System UI Library
1,438 lines (1,302 loc) • 41.5 kB
Markdown
---
title: 'Field.Selection'
description: '`Field.Selection` is a wrapper component for selecting between options using a dropdown or similar user experiences.'
version: 10.104.0
generatedAt: 2026-04-17T18:46:12.699Z
checksum: 090b7d977ba4be5e2c4c04d199a30a4048416c59f443a56985df2f80629d9c40
---
```tsx
import { Field } from '@dnb/eufemia/extensions/forms'
render(<Field.Selection />)
```
`Field.Selection` is a component for selecting between options using a dropdown or similar user experiences.
Before using this component, ensure there is not a more specific [field component](/uilib/extensions/forms/feature-fields/) available that better suits your needs.
Uses the [Field.Option](/uilib/extensions/forms/base-fields/Option/) pseudo-component to define options.
There is a corresponding [Value.Selection](/uilib/extensions/forms/Value/Selection) component.
```tsx
import { Field } from '@dnb/eufemia/extensions/forms'
render(
<Field.Selection placeholder="Select something...">
<Field.Option value="foo" title="Foo!" />
<Field.Option value="bar" title="Baar!" />
</Field.Selection>
)
```
You can also use the `dataPath` property to provide the data to the component:
```jsx
import { Field } from '@dnb/eufemia/extensions/forms'
render(
<Form.Handler
data={{
myDataPath: [
{ title: 'Foo!', value: 'foo' },
{ title: 'Bar!', value: 'bar' },
],
}}
>
<Field.Selection dataPath="/myDataPath" />
</Form.Handler>
)
```
- [Source code](https://github.com/dnbexperience/eufemia/tree/main/packages/dnb-eufemia/src/extensions/forms/base-fields/Selection)
- [Docs code](https://github.com/dnbexperience/eufemia/tree/main/packages/dnb-design-system-portal/src/docs/uilib/extensions/forms/base-fields/Selection)
The autocomplete variant (`variant="autocomplete"`) is a special easy drop-in version – basically as a replacement for the Dropdown variant, but with a search capability.
The [Autocomplete](/uilib/components/autocomplete/) by itself can be customized and used in various ways. If you need more control, you can use the `autocompleteProps` property to forward any additional properties (camelCase) to the [Autocomplete](/uilib/components/autocomplete/) component.
## Demos
### Variants summary
As there are many variants, they are split into separate sections. Here is a summary of the variants:
#### Dropdown
```tsx
render(
<Field.Selection
label="Label text"
onChange={(value) => console.log('onChange', value)}
>
<Field.Option value="foo" title="Foo!" />
<Field.Option value="bar" title="Baar!" />
</Field.Selection>
)
```
```tsx
render(
<Field.Selection
variant="autocomplete"
label="Label text"
onChange={(value) => console.log('onChange', value)}
>
<Field.Option value="foo" title="Foo!" />
<Field.Option value="bar" title="Baar!" />
</Field.Selection>
)
```
```tsx
render(
<Field.Selection
variant="radio"
label="Label text"
onChange={(value) => console.log('onChange', value)}
>
<Field.Option value="foo" title="Foo!" />
<Field.Option value="bar" title="Baar!" />
</Field.Selection>
)
```
```tsx
render(
<Field.Selection
variant="button"
label="Label text"
onChange={(value) => console.log('onChange', value)}
>
<Field.Option value="foo" title="Foo!" />
<Field.Option value="bar" title="Baar!" />
</Field.Selection>
)
```
---
```tsx
render(
<Field.Selection
onFocus={(value) => console.log('onFocus', value)}
onBlur={(value) => console.log('onBlur', value)}
onChange={(value) => console.log('onChange', value)}
>
<Field.Option value="foo" title="Foo!" />
<Field.Option value="bar" title="Baar!" />
</Field.Selection>
)
```
```tsx
render(
<Field.Selection
placeholder="Select something..."
onChange={(value) => console.log('onChange', value)}
>
<Field.Option value="foo" title="Foo!" />
<Field.Option value="bar" title="Baar!" />
</Field.Selection>
)
```
```tsx
render(
<Field.Selection
label="Label"
value="bar"
transformSelection={({ title }) => {
return title
}}
>
<Field.Option value="foo" title="Foo!" text="Additional text" />
<Field.Option value="bar" title="Baar!" text="Additional text" />
</Field.Selection>
)
```
```tsx
render(
<Field.Selection
value="bar"
label="Label text"
onChange={(value) => console.log('onChange', value)}
>
<Field.Option value="foo" title="Foo!" />
<Field.Option value="bar" title="Baar!" />
</Field.Selection>
)
```
```tsx
render(
<Field.Selection
value="bar"
label="Label text"
help={{
title: 'Help is available',
content:
'Somewhere along the way, we must learn that there is nothing greater than to do something for others.',
}}
onChange={(value) => console.log('onChange', value)}
>
<Field.Option value="foo" title="Foo!" />
<Field.Option value="bar" title="Baar!" />
</Field.Selection>
)
```
```tsx
render(
<Field.Selection
value="bar"
label="Label text"
layout="horizontal"
onChange={(value) => console.log('onChange', value)}
>
<Field.Option value="foo" title="Foo!" />
<Field.Option value="bar" title="Baar!" />
</Field.Selection>
)
```
```tsx
render(
<Field.Selection
value="bar"
label="Label text"
onChange={(value) => console.log('onChange', value)}
disabled
>
<Field.Option value="foo" title="Foo!" />
<Field.Option value="bar" title="Baar!" />
</Field.Selection>
)
```
```tsx
const Example = () => {
return (
<Field.Selection label="Label text">
<Field.Option value="foo" title="Foo!" disabled />
<Field.Option value="bar" title="Baar!" />
</Field.Selection>
)
}
render(<Example />)
```
```tsx
render(
<Field.Selection
value="bar"
label="Label text"
onChange={(value) => console.log('onChange', value)}
error={new Error('This is what is wrong...')}
>
<Field.Option value="foo" title="Foo!" />
<Field.Option value="bar" title="Baar!" />
</Field.Selection>
)
```
```tsx
const Example = () => {
const [numOptions, setNumOptions] = React.useState(3)
return (
<>
<Field.Selection
value="option-15"
label="Label text"
onChange={(value) => console.log('onChange', value)}
>
{Array.from(Array(numOptions).keys()).map((key) => (
<Field.Option
key={key}
value={key}
title={`Option ${key + 1}`}
/>
))}
</Field.Selection>
<p>
{[3, 4, 5].map((num, i) => (
<Button
key={i}
size="medium"
right="x-small"
variant={numOptions === num ? 'primary' : 'secondary'}
on_click={() => setNumOptions(num)}
>
{num} options
</Button>
))}
</p>
</>
)
}
render(<Example />)
```
```tsx
render(
<Field.Selection
value="option-15"
label="Label text"
onChange={(value) => console.log('onChange', value)}
>
<Field.Option value="option-1" title="One" />
<Field.Option value="option-2" title="Two" />
<Field.Option value="option-3" title="Three" />
<Field.Option value="option-4" title="Four" />
<Field.Option value="option-5" title="Five" />
<Field.Option value="option-6" title="Six" />
<Field.Option value="option-7" title="Seven" />
<Field.Option value="option-8" title="Eight" />
<Field.Option value="option-9" title="Nine" />
<Field.Option value="option-10" title="Ten" />
<Field.Option value="option-11" title="Eleven" />
<Field.Option value="option-12" title="Twelve" />
<Field.Option value="option-13" title="Thirteen" />
<Field.Option value="option-14" title="Fourteen" />
<Field.Option value="option-15" title="Fifteen" />
<Field.Option value="option-16" title="Sixteen" />
<Field.Option value="option-17" title="Seventeen" />
<Field.Option value="option-18" title="Eighteen" />
<Field.Option value="option-19" title="Nineteen" />
<Field.Option value="option-20" title="Twenty" />
<Field.Option value="option-21" title="Twenty-one" />
<Field.Option value="option-22" title="Twenty-two" />
<Field.Option value="option-23" title="Twenty-three" />
<Field.Option value="option-24" title="Twenty-four" />
<Field.Option value="option-25" title="Twenty-five" />
</Field.Selection>
)
```
```tsx
render(
<Field.Selection
value="foo"
label="Label text"
onChange={(value) => console.log('onChange', value)}
onFocus={(value) => console.log('onFocus', value)}
onBlur={(value) => console.log('onBlur', value)}
required
>
<Field.Option value="foo" title="Foo!" />
<Field.Option value="bar" title="Baar!" />
</Field.Selection>
)
```
```tsx
render(
<Form.Handler
data={{
example: {
list: [
{
title: 'One',
value: 'one',
},
{
title: 'Two',
value: 'two',
},
],
},
selection: 'two',
}}
>
<Field.Selection
label="Label text"
path="/selection"
dataPath="/example/list"
>
<Field.Option value="foo">Fooo</Field.Option>
</Field.Selection>
</Form.Handler>
)
```
#### Dropdown with the data property
```tsx
render(
<Field.Selection
label="Label text"
data={[
{
title: 'One',
value: 'one',
},
{
title: 'Two',
value: 'two',
},
]}
/>
)
```
### Dropdown widths
```tsx
render(
<Flex.Stack>
<Field.Selection label="Default width (property omitted)" value="bar">
<Field.Option value="foo" title="Foo!" />
<Field.Option value="bar" title="Baar!" />
</Field.Selection>
<Field.Selection
label="Small selection with a long label"
value="bar"
width="small"
>
<Field.Option value="foo" title="Foo!" />
<Field.Option value="bar" title="Baar!" />
</Field.Selection>
<Field.Selection label="Medium" value="bar" width="medium">
<Field.Option value="foo" title="Foo!" />
<Field.Option value="bar" title="Baar!" />
</Field.Selection>
<Field.Selection label="Large" value="bar" width="large">
<Field.Option value="foo" title="Foo!" />
<Field.Option value="bar" title="Baar!" />
</Field.Selection>
<Field.Selection label="Stretch" value="bar" width="stretch">
<Field.Option value="foo" title="Foo!" />
<Field.Option value="bar" title="Baar!" />
</Field.Selection>
</Flex.Stack>
)
```
### Dropdown groups
```tsx
render(
<Field.Selection
label="Label text"
path="/selection"
dataPath="/example/list"
groups={['Foos', 'Bars']}
>
<Field.Option value="foo" groupIndex={0}>
Fooo
</Field.Option>
<Field.Option value="bar" groupIndex={1}>
Bar
</Field.Option>
</Field.Selection>
)
```
---
### Autocomplete variant
```tsx
render(
<Field.Selection
variant="autocomplete"
label="Label text"
onChange={(value) => console.log('onChange', value)}
onFocus={(value) => console.log('onFocus', value)}
onBlur={(value) => console.log('onBlur', value)}
required
validateInitially
>
<Field.Option value="foo" title="Foo!" />
<Field.Option value="bar" title="Baar!" />
</Field.Selection>
)
```
```tsx
render(
<Field.Selection
variant="autocomplete"
label="Label text"
path="/selection"
dataPath="/example/list"
groups={['Foos', 'Bars']}
>
<Field.Option value="foo" groupIndex={0}>
Fooo
</Field.Option>
<Field.Option value="bar" groupIndex={1}>
Bar
</Field.Option>
</Field.Selection>
)
```
---
### Radio variant
#### Radio empty
```tsx
render(
<Field.Selection
variant="radio"
onChange={(value) => console.log('onChange', value)}
>
<Field.Option value="foo" title="Foo!" />
<Field.Option value="bar" title="Baar!" />
</Field.Selection>
)
```
```tsx
render(
<Field.Selection
variant="radio"
label="Label text"
value="bar"
onChange={(value) => console.log('onChange', value)}
>
<Field.Option value="foo" title="Foo!" />
<Field.Option value="bar" title="Baar!" />
</Field.Selection>
)
```
```tsx
render(
<Field.Selection
variant="radio"
label="Label text"
value="bar"
layout="horizontal"
onChange={(value) => console.log('onChange', value)}
>
<Field.Option value="foo" title="Foo!" />
<Field.Option value="bar" title="Baar!" />
</Field.Selection>
)
```
```tsx
render(
<Field.Selection
variant="radio"
label="Label text"
value="bar"
optionsLayout="horizontal"
onChange={(value) => console.log('onChange', value)}
>
<Field.Option value="foo" title="Foo!" />
<Field.Option value="bar" title="Baar!" />
</Field.Selection>
)
```
```tsx
render(
<Field.Selection
variant="radio"
label="Label text"
value="bar"
layout="horizontal"
optionsLayout="horizontal"
onChange={(value) => console.log('onChange', value)}
>
<Field.Option value="foo" title="Foo!" />
<Field.Option value="bar" title="Baar!" />
</Field.Selection>
)
```
```tsx
render(
<Field.Selection
variant="radio"
value="bar"
label="Label text"
onChange={(value) => console.log('onChange', value)}
disabled
>
<Field.Option value="foo" title="Foo!" />
<Field.Option value="bar" title="Baar!" />
</Field.Selection>
)
```
```tsx
const Example = () => {
return (
<Field.Selection label="Label text" variant="radio">
<Field.Option value="foo" title="Foo!" disabled />
<Field.Option value="bar" title="Baar!" />
</Field.Selection>
)
}
render(<Example />)
```
```tsx
render(
<Field.Selection
variant="radio"
value="bar"
label="Label text"
onChange={(value) => console.log('onChange', value)}
error={new Error('This is what is wrong...')}
>
<Field.Option value="foo" title="Foo!" />
<Field.Option value="bar" title="Baar!" />
</Field.Selection>
)
```
```tsx
render(
<Form.Handler
data={{
example: {
list: [
{
title: 'One',
value: 'one',
},
{
title: 'Two',
value: 'two',
},
],
},
selection: 'two',
}}
>
<Field.Selection
variant="radio"
label="Label text"
path="/selection"
dataPath="/example/list"
>
<Field.Option value="foo">Fooo</Field.Option>
</Field.Selection>
</Form.Handler>
)
```
#### Radio with the data property
```tsx
render(
<Field.Selection
variant="radio"
label="Label text"
data={[
{
title: 'One',
value: 'one',
},
{
title: 'Two',
value: 'two',
},
]}
/>
)
```
#### Radio with List composition
Use render prop children to compose each option with [List](/uilib/components/list) and set selected state from the current field value.
```tsx
render(
<Form.Handler
defaultData={{
selection: 'bar',
myDataPath: [
{
value: 'foo',
title: 'Foo!',
amount: 1234,
},
{
value: 'bar',
title: 'Baar!',
amount: 5678,
},
{
value: 'baz',
title: 'Baz!',
amount: 9999,
},
],
}}
>
<Field.Selection
label="Select an option"
variant="radio"
path="/selection"
dataPath="/myDataPath"
width="large"
>
{({ value: selectedValue, options = [] }) => {
return (
<List.Container>
{options.map(({ value, title, amount }) => {
return (
<List.Item.Basic
key={value}
selected={value === selectedValue}
>
<List.Cell.Start>
<Field.Option value={value} title={title} />
</List.Cell.Start>
<List.Cell.End>
<Value.Currency value={amount} />
</List.Cell.End>
</List.Item.Basic>
)
})}
</List.Container>
)
}}
</Field.Selection>
</Form.Handler>
)
```
You can nest other fields and show them based on your desired logic.
```tsx
render(
<Form.Handler onSubmit={console.log}>
<Form.Card>
<Field.Selection
variant="radio"
label="Make a selection"
path="/mySelection"
required
>
<Field.Option value="nothing" title="Nothing" />
<Field.Option value="showInput" title="Show an input" />
<Form.Visibility
visibleWhen={{
path: '/mySelection',
hasValue: 'showInput',
}}
animate
compensateForGap="auto" // makes animation smooth
>
<Section variant="info" innerSpace>
<Field.String placeholder="Enter some value" required />
</Section>
</Form.Visibility>
<Field.Option
value="showAdditionalOption"
title="Show additional option"
/>
<Form.Visibility
visibleWhen={{
path: '/mySelection',
hasValue: (value) =>
value === 'showAdditionalOption' || value === 'showMeMore',
}}
animate
compensateForGap="auto" // makes animation smooth
>
<Field.Option
value="showMeMore"
title="Show even more"
bottom="x-small"
/>
<Form.Visibility
animate
visibleWhen={{
path: '/mySelection',
hasValue: 'showMeMore',
}}
>
<Section variant="info" innerSpace>
<Field.String placeholder="Enter more info" required />
</Section>
</Form.Visibility>
</Form.Visibility>
</Field.Selection>
</Form.Card>
<Form.SubmitButton />
</Form.Handler>
)
```
```tsx
render(
<Form.Handler
defaultData={{
mySelection: 'first',
firstSelection: 'first',
}}
onSubmit={console.log}
>
<Form.Card>
<Field.Selection path="/mySelection" variant="radio">
<Field.Option value="first" title="First" />
<Form.Visibility
visibleWhen={{
path: '/mySelection',
hasValue: 'first',
}}
animate
compensateForGap="auto" // makes animation smooth
>
<Form.Card top bottom>
<Field.Number
path="/firstNumber"
label="First number"
value={1}
allowNegative={false}
required
exclusiveMinimum={900}
exclusiveMaximum={1000}
/>
<Field.String
path="/firstString"
label="First String"
value="foo"
pattern="bar"
minLength={4}
/>
<Field.Boolean
path="/firstBoolean"
label="First boolean"
variant="checkbox"
required
/>
<Field.Selection
path="/firstSelection"
variant="radio"
required
label="First selection"
>
<Field.Option value="first" title="First nested" />
<Form.Visibility
visibleWhen={{
path: '/firstSelection',
hasValue: 'first',
}}
animate
compensateForGap="auto" // makes animation smooth
>
<Form.Card top bottom>
<Field.Number
path="/firstNestedNumber"
label="First nested number"
required
/>
</Form.Card>
</Form.Visibility>
<Field.Option value="second" title="Second nested" />
</Field.Selection>
</Form.Card>
</Form.Visibility>
<Field.Option value="second" title="Second" />
<Field.Option value="third" title="Third" />
</Field.Selection>
</Form.Card>
<Form.SubmitButton />
</Form.Handler>
)
```
---
### Buttons variant
#### ToggleButton empty
```tsx
render(
<Field.Selection
variant="button"
onChange={(value) => console.log('onChange', value)}
>
<Field.Option value="foo" title="Foo!" />
<Field.Option value="bar" title="Baar!" />
</Field.Selection>
)
```
```tsx
render(
<Field.Selection
variant="button"
label="Label text"
value="bar"
onChange={(value) => console.log('onChange', value)}
>
<Field.Option value="foo" title="Foo!" />
<Field.Option value="bar" title="Baar!" />
</Field.Selection>
)
```
```tsx
render(
<Field.Selection
variant="button"
label="Label text"
optionsLayout="horizontal"
onChange={(value) => console.log('onChange', value)}
>
<Field.Option value="foo" title="Foo!" />
<Field.Option value="bar" title="Baar!" />
</Field.Selection>
)
```
```tsx
render(
<Field.Selection
variant="button"
value="bar"
label="Label text"
onChange={(value) => console.log('onChange', value)}
disabled
>
<Field.Option value="foo" title="Foo!" />
<Field.Option value="bar" title="Baar!" />
</Field.Selection>
)
```
```tsx
const Example = () => {
return (
<Field.Selection label="Label text" variant="button">
<Field.Option value="foo" title="Foo!" disabled />
<Field.Option value="bar" title="Baar!" />
</Field.Selection>
)
}
render(<Example />)
```
```tsx
render(
<Field.Selection
variant="button"
value="bar"
label="Label text"
onChange={(value) => console.log('onChange', value)}
error={new Error('This is what is wrong...')}
>
<Field.Option value="foo" title="Foo!" />
<Field.Option value="bar" title="Baar!" />
</Field.Selection>
)
```
You can nest other fields and show them based on your desired logic.
```tsx
render(
<Form.Handler>
<Form.Card>
<Field.Selection
variant="button"
label="Make a selection"
path="/mySelection"
>
<Field.Option value="nothing" title="Nothing" />
<Field.Option value="showInput" title="Show an input" />
<Form.Visibility
animate
visibleWhen={{
path: '/mySelection',
hasValue: 'showInput',
}}
>
<Section variant="info" innerSpace>
<Field.String placeholder="Enter some value" />
</Section>
</Form.Visibility>
<Field.Option
value="showAdditionalOption"
title="Show additional option"
/>
<Form.Visibility
animate
visibleWhen={{
path: '/mySelection',
hasValue: (value) =>
value === 'showAdditionalOption' || value === 'showMeMore',
}}
>
<Field.Option
value="showMeMore"
title="Show even more"
bottom="x-small"
/>
<Form.Visibility
animate
visibleWhen={{
path: '/mySelection',
hasValue: 'showMeMore',
}}
>
<Section variant="info" innerSpace>
<Field.String placeholder="Enter more info" />
</Section>
</Form.Visibility>
</Form.Visibility>
</Field.Selection>
</Form.Card>
</Form.Handler>
)
```
```tsx
render(
<Form.Handler
data={{
example: {
list: [
{
title: 'One',
value: 'one',
},
{
title: 'Two',
value: 'two',
},
],
},
selection: 'two',
}}
>
<Field.Selection
variant="button"
label="Label text"
path="/selection"
dataPath="/example/list"
>
<Field.Option value="foo">Fooo</Field.Option>
</Field.Selection>
</Form.Handler>
)
```
#### ToggleButton with the data property
```tsx
render(
<Field.Selection
variant="button"
label="Label text"
data={[
{
title: 'One',
value: 'one',
},
{
title: 'Two',
value: 'two',
},
]}
/>
)
```
```tsx
render(
<Field.Selection label="Label" error="This is what is wrong...">
<Field.Option value="foo">Foo</Field.Option>
<Field.Option value="bar">Bar</Field.Option>
</Field.Selection>
)
```
```tsx
render(
<Field.Selection label="Label" info="Useful information (?)">
<Field.Option value="foo">Foo</Field.Option>
<Field.Option value="bar">Bar</Field.Option>
</Field.Selection>
)
```
```tsx
render(
<Field.Selection label="Label" warning="I'm warning you...">
<Field.Option value="foo">Foo</Field.Option>
<Field.Option value="bar">Bar</Field.Option>
</Field.Selection>
)
```
## Properties
### Field-specific properties
```json
{
"props": {
"variant": {
"doc": "Choice of UI feature. Can be: `dropdown`, `autocomplete`, `button`, `radio`.",
"type": "string",
"status": "optional"
},
"value": {
"doc": "Defines the `value`. When using variant `radio` or `button`, value has to be a `string`.",
"type": ["number", "string"],
"status": "optional"
},
"transformSelection": {
"doc": "Transform the displayed selection for Dropdown and Autocomplete variant. Use it to display a different value than the one in the data set. The first parameter is the props of the Option component or data item. You can return a React.ReactNode that will be displayed in the selection.",
"type": "function",
"status": "optional"
},
"optionsLayout": {
"doc": "Layout for the list of options. Can be `horizontal` or `vertical`.",
"type": "string",
"status": "optional"
},
"width": {
"doc": "`small`, `medium` or `large` for predefined standard widths, `stretch` for fill available width.",
"type": ["string", "false"],
"status": "optional"
},
"data": {
"doc": "Data to be used for the component. The object needs to have a `value` and a `title` property. Provide the Dropdown or Autocomplete data in the format documented here: [Dropdown](/uilib/components/dropdown) and [Autocomplete](/uilib/components/autocomplete) documentation.",
"type": "array",
"status": "optional"
},
"groups": {
"doc": "An array of group titles for the list items. Only the first group can be `undefined`",
"type": "React.ReactNode[]",
"status": "optional"
},
"dataPath": {
"doc": "The path to the context data (Form.Handler). The context data object needs to have a `value` and a `title` property. The generated options will be placed above given JSX based children. When `children` is a function, the generated options are instead provided as `options` to the function.",
"type": "string",
"status": "optional"
},
"autocompleteProps": {
"doc": "Forward any additional props (camelCase) to the [Autocomplete](/uilib/components/autocomplete/) component. `onType` will additionally provide the `value` parameter with `emptyValue` support in addition to the internal `dataContext`.",
"type": "object",
"status": "optional"
},
"dropdownProps": {
"doc": "Forward any additional props (camelCase) to the [Dropdown](/uilib/components/dropdown/) component.",
"type": "object",
"status": "optional"
},
"size": {
"doc": "The sizes you can choose is small (1.5rem), default (2rem), medium (2.5rem) and large (3rem) are supported component sizes. Defaults to default / null. Also, if you define a number like size=\"2\" then it will be forwarded as the input element attribute. Consider rather setting field sizes with [Form.Appearance](/uilib/extensions/forms/Form/Appearance/).",
"type": "string",
"status": "optional"
},
"children": {
"doc": "For providing [Field.Option](/uilib/extensions/forms/base-fields/Option/) components and other children. Can also be a render function that receives `{ value, options }`, where `options` are from `data` or `dataPath` and may include additional custom properties.",
"type": ["React.ReactNode", "function"],
"status": "optional"
}
}
}
```
```json
{
"props": {
"value": {
"doc": "Source data value for the field. Will take precedence over the path value given in the data context.",
"type": "{valueType}",
"status": "optional"
},
"defaultValue": {
"doc": "Default source data value for the field. Will not take precedence over the path value given in the data context.",
"type": "{valueType}",
"status": "optional"
},
"path": {
"doc": "JSON Pointer for where the data for the field is located in the source dataset (when using Form.Handler or DataContext). The `path` will also be set as the `name` attribute for the [string](/uilib/extensions/forms/base-fields/String/)-field.",
"type": "string",
"status": "optional"
},
"info": {
"doc": "Info message shown below / after the field by default. Use `statusPosition=\"above\"` to show status messages above the field. When provided as a function, the function will be called with the current value as argument. The second parameter is an object with `{ conditionally, getValueByPath, getFieldByPath }`. To show the message first after the user has interacted with the field, you can call and return `conditionally` function with a callback and with options: `conditionally(() => 'Your message', { showInitially: true })`",
"type": ["React.Node", "Array<React.Node>", "function"],
"status": "optional"
},
"warning": {
"doc": "Warning message shown below / after the field by default. Use `statusPosition=\"above\"` to show status messages above the field. When provided as a function, the function will be called with the current value as argument. The second parameter is an object with `{ conditionally, getValueByPath, getFieldByPath }`. To show the message first after the user has interacted with the field, you can call and return `conditionally` function with a callback and with options: `conditionally(() => 'Your message', { showInitially: true })`",
"type": ["React.Node", "Array<React.Node>", "function"],
"status": "optional"
},
"error": {
"doc": "Error message shown below / after the field. When provided as a function, the function will be called with the current value as argument. The second parameter is an object with `{ conditionally, getValueByPath, getFieldByPath }`. To show the message first after the user has interacted with the field, you can call and return `conditionally` function with a callback and with options: `conditionally(() => 'Your message', { showInitially: true })`",
"type": [
"Error",
"FormError",
"Array<Error | FormError>",
"function"
],
"status": "optional"
},
"disabled": {
"doc": "Set `true` to show the field but without the possibility of changing the value.",
"type": "boolean",
"status": "optional"
},
"emptyValue": {
"doc": "The value to use (in `onChange` events etc) when emptying the field. Makes it possible for instance to provide `undefined` instead of an empty string when clearing the content of a text input.",
"type": ["{valueType}", "undefined"],
"status": "optional"
},
"required": {
"doc": "When set to `true`, the field will give an error if the value fails the required validation. When set to `false`, the field will not be required, but will add a \"(optional)\" suffix to the label.",
"type": "boolean",
"status": "optional"
},
"labelSuffix": {
"doc": "Will append an additional text to the label, like \"(optional)\". When using `inheritLabel`, the suffix will not be inherited. NB: The visual appearance of the `labelSuffix` may change in the future.",
"type": "React.Node",
"status": "optional"
},
"schema": {
"doc": "Custom JSON Schema for validating the value.",
"type": "object",
"status": "optional"
},
"validateInitially": {
"doc": "Set to `true` to show validation based errors initially (from given value-prop or source data) before the user interacts with the field.",
"type": "boolean",
"status": "optional"
},
"validateUnchanged": {
"doc": "Set to `true` to show validation based errors when the field is touched (like focusing a field and blurring) without having changed the value. Since the user did not introduce a new error, this will apply when the value was initially invalid based on validation.",
"type": "boolean",
"status": "optional"
},
"validateContinuously": {
"doc": "Set to `true` to show validation based errors continuously while writing, not just when blurring the field.",
"type": "boolean",
"status": "optional"
},
"errorMessages": {
"doc": "Custom error messages for each type of error, overriding default messages. The messages can be a React.ReactNode or a string.",
"type": "object",
"status": "optional"
},
"onChangeValidator": {
"doc": "Custom validator function where you can return `undefined`, `Error`, `FormError` or an Array with either several other validators or several `Error` or `FormError`. It is triggered on every change done by the user. The function can be either asynchronous or synchronous. The first parameter is the value, and the second parameter returns an object containing { errorMessages, connectWithPath, validators }.",
"type": "function",
"status": "optional"
},
"onBlurValidator": {
"doc": "Custom validator function where you can return `undefined`, `Error`, `FormError` or an Array with either several other validators or several `Error` or `FormError`. It is triggered when the user leaves a field (e.g., blurring a text input or closing a dropdown). The function can be either asynchronous or synchronous. The first parameter is the value, and the second parameter returns an object containing { errorMessages, connectWithPath, validators }.",
"type": "function",
"status": "optional"
},
"transformIn": {
"doc": "Transforms the `value` before its displayed in the field (e.g. input).",
"type": "function",
"status": "optional"
},
"transformOut": {
"doc": "Transforms the value before it gets forwarded to the form data object (context) or returned as the `onChange` value parameter. The first parameter is the internal value. Some fields do support a second parameter, like the SelectCountry, where the country object is given.",
"type": "function",
"status": "optional"
},
"label": {
"doc": "Label text displayed above the field. Most fields already have a default label, so check the field translations for an existing label entry. Only set `label` when you need to override the default.",
"type": "string",
"status": "optional"
},
"labelDescription": {
"doc": "A more discreet text displayed beside the label (i.e for \"(optional)\").",
"type": "string",
"status": "optional"
},
"labelDescriptionInline": {
"doc": "If true, the `labelDescription` will be displayed on the same line as the label.",
"type": "boolean",
"status": "optional"
},
"labelSrOnly": {
"doc": "Use `true` to make the label only readable by screen readers.",
"type": "boolean",
"status": "optional"
},
"labelSize": {
"doc": "Define the font-size of the label based on the [font-size](/uilib/typography/font-size/) table.",
"type": ["medium", "large"],
"status": "optional"
},
"help": {
"doc": "Provide help content for the field using `title` and `content` as a string or React.Node. Additionally, you can set `open` to `true` to display the inline help, set the `breakout` property to `false` to disable the breakout of the inline help content, set `outset` to `false` to display the help text inline (inset) instead of the default outset behavior, or use `renderAs` set to `dialog` to render the content in a [Dialog](/uilib/components/dialog/) (recommended for larger amounts of content).",
"type": "object",
"status": "optional"
},
"hideHelpButton": {
"doc": "Set `true` when you render the inline help button outside the label (e.g. inside a checkbox suffix) so FieldBlock skips drawing the default label help button.",
"type": "boolean",
"status": "optional"
},
"statusPosition": {
"doc": "Controls where status messages (`error`, `warning`, `info`) are visually shown. Use `below` (default) or `above`.",
"type": ["\"below\"", "\"above\""],
"status": "optional"
},
"layout": {
"doc": "Layout for the label and input. Can be `horizontal` or `vertical`.",
"type": "string",
"status": "optional"
},
"layoutOptions": {
"doc": "Use this to set additional options for the `horizontal` layout. E.g. `{ width: \"medium\" }`. You can also use a custom width `{number}rem`. Instead of a width, you can use a min/max width. E.g. `{ minWidth: \"6rem\", maxWidth: \"12rem\" }`.",
"type": "object",
"status": "optional"
},
"width": {
"doc": "Will set the width for the whole block. Use `small`, `medium`, `large` for predefined standard widths. You can also set a custom width `{number}rem` or use `stretch` or `false`.",
"type": ["string", "false"],
"status": "optional"
},
"contentWidth": {
"doc": "Will set the width for its contents. Use `small`, `medium`, `large` for predefined standard widths. You can also set a custom width `{number}rem` or use `stretch` or `false`.",
"type": ["string", "false"],
"status": "optional"
},
"[Space](/uilib/layout/space/properties)": {
"doc": "Spacing properties like `top` or `bottom` are supported.",
"type": ["string", "object"],
"status": "optional"
}
},
"omit": ["value"]
}
```
```json
{
"props": {
"onChange": {
"doc": "Will be called on value changes made by the user, with the new value as argument. When an `async` function is used, the corresponding [FieldBlock](/uilib/extensions/forms/create-component/FieldBlock/) will show an indicator on the field label. You can return `{ success: 'saved' } as const` to show a success symbol, or an error or an object with these keys `{ info: 'Info message', warning: 'Warning message', error: Error('My error') } as const`. The second parameter is an object that e.g. contains `props` (all given `Field.*` properties).",
"type": "(value) => void",
"status": "optional"
},
"onFocus": {
"doc": "Will be called when the component gets into focus. Like clicking inside a text input or opening a dropdown. Called with active value as argument. The second parameter is an object that e.g. contains `props` (all given `Field.*` properties).",
"type": "(value) => void",
"status": "optional"
},
"onBlur": {
"doc": "Will be called when the component stop being in focus. Like when going to next field, or closing a dropdown. Called with active value as argument. The second parameter is an object that e.g. contains `props` (all given `Field.*` properties).",
"type": "(value) => void",
"status": "optional"
},
"onStatusChange": {
"doc": "Called whenever the status messages (info, warning or error) gets visible or changes. Receives the current `{ info, warning, error }` object.",
"type": "({ info?, warning?, error? }: FieldStatus) => void",
"status": "optional"
}
}
}
```