Field.MultiSelection#

Some properties provide flexibility for specific integrations. Follow the component's usage guidance. Customizations beyond the documented patterns need a use case approved by DNB UX. Read about intended use and customization.

Properties#

Field-specific properties#

	Type	Description
`variant`	`"popover"` `"inline"`	Defines the variant of the component. `popover` renders a trigger button that opens a popover with the item list. `inline` renders the item list inline as checkboxes.
`data`	`Array<{ value, title, text?: React.ReactNode, description?: React.ReactNode, disabled?, ... }>`	Array of objects where each object contains at least `value` and `title`. Can also include `text` for an optional primary extra line, `description` for an optional secondary gray line, plus `disabled`, `help`, and `className`.
`dataPath`	`string`	Path to data in Form.Handler context. The context data array should contain objects with `value` and `title` properties.
`showSearchField`	`boolean`	Show a search/filter input field to search through items.
`search`	`SearchOptions`	Configure search behavior when `showSearchField` is enabled. An object with optional keys: `filter` (enable result filtering, default `true`), `reorder` (enable relevance reordering, default `true`), `numbers` (enable number-optimized matching, default `false`), `matchInsideWordsFrom` (threshold for in-word search, default `3`), and `match` (matching mode `"word"` or `"starts-with"`, default `"word"`). When `filter` is `false`, items are not filtered out but are still reordered by relevance unless `reorder` is also `false`. Example: `search={{ numbers: true }}`.
`showSelectAll`	`boolean`	Show a "Select all" checkbox at the top of the list.
`showSelectedTags`	`boolean`	Show selected items as removable tags inside the popover. When enabled and nothing is selected, a placeholder text is shown.
`maxHeight`	`string` `number`	Sets the maximum height of the scrollable item list for the `inline` variant. Numbers are interpreted as rem.
`listDriver`	`MultiSelectionListDriver`	Opt in to a custom item-list renderer. Use `createMultiSelectionVirtualization` from `@dnb/eufemia/extensions/forms/Field/MultiSelection/Virtualization` for large data sets. Install the optional `@tanstack/react-virtual` peer dependency when using this driver. The inline variant defaults to a `32rem` maximum height when virtualized; use `maxHeight` to override it.
`showConfirmButton`	`boolean`	Show confirm and cancel buttons at the bottom of the popover. Selections are only applied when the user confirms.
`selectedItemsCollapsibleThreshold`	`number`	When the total number of items exceeds this threshold, the selected items are hidden by default and can be toggled with a header. Defaults to `10`.
`openOnFind`	`boolean`	Keeps collapsed selected tags findable by the browser's find-in-page feature. Matching content expands the selected tags. Defaults to `false`.
`minItems`	`number`	Minimum number of items required to be selected. Triggers a validation error if fewer items are selected.
`maxItems`	`number`	Maximum number of items allowed to be selected. Triggers a validation error if more items are selected.
`width`	`"medium"` `"large"`	The width of the component. Supported values: `"medium"` and `"large"`. Defaults to `"large"`.

General properties#

type MultiSelectionItem = {
  value: number | string
  title: ReactNode
  text?: ReactNode
  description?: ReactNode
  disabled?: boolean
  children?: Array<MultiSelectionItem> // Optional nested items for grouping
}

	Type	Description
`value`	`Array<MultiSelectionItem>`	(optional) Source data value for the field. Will take precedence over the path value given in the data context.
`defaultValue`	`Array<MultiSelectionItem>`	(optional) Default source data value for the field. Will not take precedence over the path value given in the data context.
`path`	`string`	(optional) 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-field.
`info`	`React.ReactNode` `Array<React.ReactNode>` `function`	(optional) 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 })`.
`warning`	`React.ReactNode` `Array<React.ReactNode>` `function`	(optional) 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 })`.
`error`	`Error` `FormError` `Array<Error \| FormError>` `function`	(optional) 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 })`.
`disabled`	`boolean`	(optional) Set `true` to show the field but without the possibility of changing the value.
`emptyValue`	`Array<MultiSelectionItem>` `undefined`	(optional) 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.
`required`	`boolean`	(optional) 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.
`labelSuffix`	`React.ReactNode`	(optional) Will append additional text to the label, like "(optional)", displayed in a secondary text color. When using `inheritLabel`, the suffix will not be inherited.
`schema`	`object`	(optional) Custom JSON Schema for validating the value.
`validateInitially`	`boolean`	(optional) Set to `true` to show validation based errors initially (from given value-property or source data) before the user interacts with the field.
`validateUnchanged`	`boolean`	(optional) 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.
`validateContinuously`	`boolean`	(optional) Set to `true` to show validation based errors continuously while writing, not just when blurring the field.
`errorMessages`	`object`	(optional) Custom error messages for each type of error, overriding default messages. The messages can be a `React.ReactNode` or a string.
`onChangeValidator`	`function`	(optional) 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, and runs during form submit by default. 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 }. Use `withValidatorOptions(validator, { runOnSubmit: 'never' })` to keep it from running during form submit, or `'when-changed'` to run it only when the value has changed since the validator last ran. Object and array values are compared by reference. If an asynchronous validator does not settle within `asyncSubmitTimeout` (30 seconds by default), the field clears its pending state, so a Promise that never settles does not leave the field stuck. A submit waiting for that field is canceled and must be retried.
`onBlurValidator`	`function`	(optional) 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), and runs during form submit by default. 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 }. Use `withValidatorOptions(validator, { runOnSubmit: 'never' })` to keep it from running during form submit, or `'when-changed'` to run it only when the value has changed since the validator last ran. Object and array values are compared by reference. If an asynchronous validator does not settle within `asyncSubmitTimeout` (30 seconds by default), the field clears its pending state, so a Promise that never settles does not leave the field stuck. A submit waiting for that field is canceled and must be retried.
`transformIn`	`function`	(optional) Transforms the `value` before it's displayed in the field (e.g. input).
`transformOut`	`function`	(optional) 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.
`label`	`string`	(optional) 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.
`labelDescription`	`string`	(optional) Supporting text displayed below the label by default. Set `labelDescriptionInline` to `true` to display it on the same line as the label.
`labelDescriptionInline`	`boolean`	(optional) If `true`, the `labelDescription` will be displayed on the same line as the label.
`labelSrOnly`	`boolean`	(optional) Use `true` to make the label only readable by screen readers.
`labelSize`	`"medium"` `"large"`	(optional) Define the font-size of the label based on the font-size table.
`help`	`object`	(optional) Provide help content for the field using `title` and `content` as a string or `React.ReactNode`. Additionally, you can set `open` to `true` to display the inline help, set `openOnFind` to `true` to open matching inline help from browser find-in-page, 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 (recommended for larger amounts of content).
`hideHelpButton`	`boolean`	(optional) 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.
`statusPosition`	`"below"` `"above"`	(optional) Controls where status messages (`error`, `warning`, `information`) are visually shown. Use `below` (default) or `above`.
`layout`	`"horizontal"` `"vertical"`	(optional) Layout for the label and input. Can be `horizontal` or `vertical`.
`layoutOptions`	`object`	(optional) 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" }`.
`Space`	`string` `object`	(optional) Spacing properties like `top` or `bottom` are supported.

Translations#

More info about translations can be found in the general localization and Eufemia Forms localization docs.

Key	nb-NO	en-GB	sv-SE	da-DK
`MultiSelectionField.placeholder`	Velg en eller flere	Select one or more	Välj en eller flera	Vælg en eller flere
`MultiSelectionField.selectAll`	Velg alle	Select all	Välj alla	Vælg alle
`MultiSelectionField.searchPlaceholder`	Søk...	Search...	Sök...	Søg...
`MultiSelectionField.searchLabel`	Søk	Search	Sök	Søg
`MultiSelectionField.noOptions`	Ingen alternativer	No options	Inga alternativ	Ingen muligheder
`MultiSelectionField.skipToActions`	Hopp over alternativer og gå til handlinger	Skip options and go to actions	Hoppa över alternativ och gå till åtgärder	Spring muligheder over, og gå til handlinger
`MultiSelectionField.confirmButton`	Bekreft ({count} valgt)	Confirm ({count} selected)	Bekräfta ({count} valda)	Bekræft ({count} valgt)
`MultiSelectionField.cancelButton`	Avbryt	Cancel	Avbryt	Annuller
`MultiSelectionField.selectionCount`	{count} av {total} valgt	{count} of {total} selected	{count} av {total} valda	{count} af {total} valgt
`MultiSelectionField.clearAll`	Fjern alle	Clear all	Rensa alla	Ryd alt
`MultiSelectionField.errorMinItems`	Du må velge minst {minItems}.	You must select at least {minItems} items.	Du måste välja minst {minItems}.	Du skal vælge mindst {minItems}.
`MultiSelectionField.errorMaxItems`	Du kan ikke velge mer enn {maxItems}.	You cannot select more than {maxItems} items.	Du kan inte välja fler än {maxItems}.	Du kan ikke vælge mere end {maxItems}.
`Field.errorSummaryTitle`	Feil som må rettes	Please correct the following errors	Fel som måste åtgärdas	Felter der skal rettes
`Field.stateSummary`	Oppsummering:	Summary:	Sammanfattning:	Oversigt:
`Field.errorSummary`	Feil som må rettes:	Please correct the following errors:	Fel som måste åtgärdas:	Felter der skal rettes:
`Field.errorRequired`	Dette feltet må fylles ut.	This field is required.	Detta fält måste fyllas i.	Dette felt skal udfyldes.
`Field.errorPattern`	Du må skrive inn en gyldig verdi.	You must enter a valid value.	Du måste ange ett giltigt värde.	Du skal indtaste en gyldig værdi.
`Field.optionalLabelSuffix`	(valgfritt)	(optional)	(valfritt)	(valgfrit)

Suggest an edit