Skip to content

docs: operate: common props for UI widgets #832

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

docs: operate: common props for UI widgets #832

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
faa65ed
docs: operate: common props for UI widgets
palkerecsenyi Jul 18, 2025
3fa45b3
docs: operate: "Props" -> "Additional props"
palkerecsenyi Jul 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
164 changes: 43 additions & 121 deletions docs/operate/customize/metadata/custom_fields/widgets.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,28 @@ _Introduced in v10_

The following document is a reference guide for all the React UI widgets available for custom fields.

## Common props

These props are applicable to all widgets. In the reference below, only props additional to these are shown for each widget.

- **fieldPath** `String` _required_: The path to the field e.g. `cern:experiment`.

- **label** `String` _required_: The label for the element's display. This is used whenever the field should be displayed e.g. upload form, landing page etc.

- **labelIcon** `String` _optional_: The optional icon that your field might have. The value should be one of the [Semantic UI icons](https://react.semantic-ui.com/elements/icon/).
- Previously known as **icon**.

- **placeholder** `String`: The placeholder for the element's display. You should fill this in with an example value.

- **helpText** `String` _required_: The description for the element's display. You should provide useful information on how the users should fill this field in.
- Previously known as **description**.

- **required** `Boolean` _optional_: Define if the field should be required i.e. display the `*` symbol.

- **disabled** `Boolean` _optional_: Define if the field should be displayed as disabled thus no input can be filled.

- **hidden** `Boolean` _optional_: Define if the field should be hidden completely. Hiding a field will still retain any value that it already contained.

## Input

An input field for a single string value.
Expand All @@ -14,29 +36,13 @@ An input field for a single string value.
<Input
fieldPath="cern:experiment_url"
label="Experiment URL"
labelIcon="linkify"
placeholder="https://your.experiment.url"
icon="linkify"
description="URL of the experiment to which the record belongs to."
helpText="URL of the experiment to which the record belongs to."
required={true}
/>
```

### Props

- **fieldPath** `String` _required_: The path to the field e.g. `cern:experiment`.

- **label** `String` _required_: The label for the element's display. This is used whenever the field should be displayed e.g. upload form, landing page etc.

- **placeholder** `String` _required_: The placeholder for the element's display. You should fill this in with an example value.

- **description** `String` _required_: The description for the element's display. You should provide useful information on how the users should fill this field in.

- **icon** `String` _optional_: The optional icon that your field might have. The value should be one of the [Semantic UI icons](https://react.semantic-ui.com/elements/icon/).

- **required** `Boolean` _optional_: Define if the field should be required i.e. display the `*` symbol.

- **disabled** `Boolean` _optional_: Define if the field should be displayed as disabled thus no input can be filled.

## NumberInput

An input field for numbers e.g. integers, float etc.
Expand All @@ -47,29 +53,13 @@ An input field for numbers e.g. integers, float etc.
<NumberInput
fieldPath="cern:experiment_id"
label="Experiment identifier"
labelIcon="calculator"
placeholder="Experiment id..."
icon="calculator"
description="Unique integer id of the experiment."
helpText="Unique integer id of the experiment."
required={true}
/>
```

### Props

- **fieldPath** `String` _required_: The path to the field e.g. `cern:experiment`.

- **label** `String` _required_: The label for the element's display. This is used whenever the field should be displayed e.g. upload form, landing page etc.

- **placeholder** `String` _required_: The placeholder for the element's display. You should fill this in with an example value.

- **description** `String` _required_: The description for the element's display. You should provide useful information on how the users should fill this field in.

- **icon** `String` _optional_: The optional icon that your field might have. The value should be one of the [Semantic UI icons](https://react.semantic-ui.com/elements/icon/).

- **required** `Boolean` _optional_: Define if the field should be required i.e. display the `*` symbol.

- **disabled** `Boolean` _optional_: Define if the field should be displayed as disabled thus no input can be filled.

## MultiInput

An input field for multiple string values.
Expand All @@ -80,27 +70,15 @@ An input field for multiple string values.
<MultiInput
fieldPath="cern:experiment_keywords"
label="Experiment keywords"
labelIcon="tags"
placeholder="Add keywords..."
icon="tags"
description="Keywords to describe the experiment."
helpText="Keywords to describe the experiment."
required={false}
disabled={false}
/>
```

### Props

- **fieldPath** `String` _required_: The path to the field e.g. `cern:experiment`.

- **label** `String` _required_: The label for the element's display. This is used whenever the field should be displayed e.g. upload form, landing page etc.

- **placeholder** `String` _required_: The placeholder for the element's display. You should fill this in with an example value.

- **description** `String` _required_: The description for the element's display. You should provide useful information on how the users should fill this field in.

- **icon** `String` _optional_: The optional icon that your field might have. The value should be one of the [Semantic UI icons](https://react.semantic-ui.com/elements/icon/).

- **required** `Boolean` _optional_: Define if the field should be required i.e. display the `*` symbol.
### Additional props

- **additionLabel** `String` _optional_: The label to show when a user is adding a new value.

Expand All @@ -118,24 +96,14 @@ A rich input field for HTML text, with a WYSIWYG editor.
<RichInput
fieldPath="cern:experiment_abstract"
label="Experiment abstract"
description="Long description of the experiment."
icon="book"
labelIcon="book"
helpText="Long description of the experiment."
required={false}
editorConfig={toolbar: [ 'bold', 'italic' ]}
/>
```

### Props

- **fieldPath** `String` _required_: The path to the field e.g. `cern:experiment`.

- **label** `String` _required_: The label for the element's display. This is used whenever the field should be displayed e.g. upload form, landing page etc.

- **description** `String` _required_: The description for the element's display. You should provide useful information on how the users should fill this field in.

- **icon** `String` _optional_: The optional icon that your field might have. The value should be one of the [Semantic UI icons](https://react.semantic-ui.com/elements/icon/).

- **required** `Boolean` _optional_: Define if the field should be required i.e. display the `*` symbol.
### Additional props

- **editorConfig** `Object` _optional_: The config to pass to the underlying HTML WYSIWYG editor as described in the [CKEditor configuration](https://ckeditor.com/docs/ckeditor5/latest/api/module_core_editor_editorconfig-EditorConfig.html) page.

Expand All @@ -149,24 +117,12 @@ An input field for multi line text.
<TextArea
fieldPath="cern:experiment_abstract"
label="Experiment abstract"
description="Long description of the experiment."
icon="book"
labelIcon="book"
helpText="Long description of the experiment."
required={false}
/>
```

### Props

- **fieldPath** `String` _required_: The path to the field e.g. `cern:experiment`.

- **label** `String` _required_: The label for the element's display. This is used whenever the field should be displayed e.g. upload form, landing page etc.

- **description** `String` _required_: The description for the element's display. You should provide useful information on how the users should fill this field in.

- **icon** `String` _optional_: The optional icon that your field might have. The value should be one of the [Semantic UI icons](https://react.semantic-ui.com/elements/icon/).

- **required** `Boolean` _optional_: Define if the field should be required i.e. display the `*` symbol.

## Dropdown

A dropdown field that renders the complete list of possible options, where the user can select one or multiple values. It is meant to be used with small vocabularies.
Expand All @@ -177,29 +133,17 @@ A dropdown field that renders the complete list of possible options, where the u
<Dropdown
fieldPath="cern:experiment_keywords"
label="Experiment keywords"
labelIcon="tags"
placeholder="Select keywords..."
icon="tags"
description="List of keywords to select that describe the experiment."
helpText="List of keywords to select that describe the experiment."
required={false}
search={true}
multiple={false}
clearable={true}
/>
```

### Props

- **fieldPath** `String` _required_: The path to the field e.g. `cern:experiment`.

- **label** `String` _required_: The label for the element's display. This is used whenever the field should be displayed e.g. upload form, landing page etc.

- **placeholder** `String` _required_: The placeholder for the element's display. You should fill this in with an example value.

- **description** `String` _required_: The description for the element's display. You should provide useful information on how the users should fill this field in.

- **icon** `String` _optional_: The optional icon that your field might have. The value should be one of the [Semantic UI icons](https://react.semantic-ui.com/elements/icon/).

- **required** `Boolean` _optional_: Define if the field should be required i.e. display the `*` symbol.
### Additional props

- **search** `Boolean` _optional_: Define if the user should be able to search in the current available options.

Expand All @@ -217,9 +161,9 @@ A dropdown field that allows the user to search for values, connected to the RES
<AutocompleteDropdown
fieldPath="cern:experiment_keywords"
label="Experiment keywords"
labelIcon="tags"
placeholder="Select keywords..."
icon="tags"
description="List of keywords to select that describe the experiment."
helpText="List of keywords to select that describe the experiment."
autocompleteFrom="/api/vocabularies/myexperimentkeywords"
autocompleteFromAcceptHeader="application/vnd.inveniordm.v1+json"
required={false}
Expand All @@ -228,25 +172,13 @@ A dropdown field that allows the user to search for values, connected to the RES
/>
```

### Props

- **fieldPath** `String` _required_: The path to the field e.g. `cern:experiment`.

- **label** `String` _required_: The label for the element's display. This is used whenever the field should be displayed e.g. upload form, landing page etc.

- **placeholder** `String` _required_: The placeholder for the element's display. You should fill this in with an example value.

- **description** `String` _required_: The description for the element's display. You should provide useful information on how the users should fill this field in.
### Additional props

- **autocompleteFrom** `String` _required_: The endpoint from which the component should fetch options. This will point to your vocabulary endpoint e.g. `/api/vocabularies/myvocabulary`.

- **autocompleteFromAcceptHeader** `String` _optional_: The `Accept` header to send to the `autocompleteFrom` API. If not provided, the **default** header is
`application/vnd.inveniordm.v1+json`.

- **icon** `String` _optional_: The optional icon that your field might have. The value should be one of the [Semantic UI icons](https://react.semantic-ui.com/elements/icon/).

- **required** `Boolean` _optional_: Define if the field should be required i.e. display the `*` symbol.

- **clearable** `Boolean` _optional_: Define if the user can deselect all the selected values.

- **multiple** `Boolean` _optional_ : Define if the field accepts multiple values.
Expand All @@ -261,24 +193,14 @@ A field for boolean values. It displays 2 checkboxes for each corresponding valu
<BooleanCheckbox
fieldPath="cern:experiment_active"
label="Active experiment"
icon="check"
description="Mark if the experiment is active."
labelIcon="check"
helpText="Mark if the experiment is active."
required={true}
/>
```

### Props

- **fieldPath** `String` _required_: The path to the field e.g. `cern:experiment`.

- **label** `String` _required_: The label for the element's display. This is used whenever the field should be displayed e.g. upload form, landing page etc.
### Additional props

- **trueLabel** `String` _required_: The label for the element's display when the value is `true`. This is used whenever the `true` value should be displayed e.g. upload form, landing page etc.

- **falseLabel** `String` _required_: The label for the element's display when the value is `false`. This is used whenever the `false` value should be displayed e.g. upload form, landing page etc.

- **description** `String` _required_: The description for the element's display. You should provide useful information on how the users should fill this field in.

- **icon** `String` _optional_: The optional icon that your field might have. The value should be one of the [Semantic UI icons](https://react.semantic-ui.com/elements/icon/).

- **required** `Boolean` _optional_: Define if the field should be required i.e. display the `*` symbol.