Field widget

A field widget is the form control that an editor uses to enter the data of one field. One field type can be edited with several widgets, for example a select list, radio buttons or an autocomplete for a term reference. You choose the widget per field and per form mode on the Manage form display page.

How field widgets work in Drupal 11

The Field UI help describes the Manage form display page of a content type or other entity sub-type. For each field you select the widget, open its settings with the Edit button (a wheel), and reorder the fields. Choosing Hidden from the widget drop-down, or dragging the field into the Disabled section, removes the field from the form. An entity type can have several form modes; each one either uses the default settings or its own custom settings.

In code, a widget is a plugin:

• It carries the FieldWidget attribute with an id, a label, a field_types list and an optional multiple_values flag.
• It implements WidgetInterface, in most cases by extending WidgetBase, and lives in Drupal\{module}\Plugin\Field\FieldWidget.
• Its formElement() method returns the Form API elements for a single value. For a field with several values, core calls it once for each value. A widget that sets multiple_values handles all values in one element.
• massageFormValues() turns the submitted values into the array of field values. settingsForm() and settingsSummary() provide the settings and the one-line summary.

Core examples: string_textfield (labeled Textfield) is the default widget of the string field type, with the settings Size of textfield and Placeholder. boolean_checkbox is the single on/off checkbox for a boolean. options_select is the select list. entity_reference_autocomplete_tags (labeled Autocomplete (Tags style)) manages all values of a reference field in one text field. The Field API describes the plugin system. A module can change existing widget definitions with hook_field_widget_info_alter().

Example

In the Drupal User Guide, the Recipe form asks for ingredients one by one. Go to Structure › Content types, open the menu beside Recipe and choose Manage form display. For the Ingredients field, select Autocomplete (Tags style) in the Widget column and click Save. The form now shows one text field that accepts multiple values.

Common mistakes

• Looking for the setting on the display page. Manage display holds the field formatter, which controls the output. The widget affects only the edit form.
• Hiding a field in the form and forgetting it. A field set to Hidden or dragged to Disabled can no longer be filled in by editors.
• Editing the wrong form mode. A form mode with custom settings does not follow the default. Check which form mode you are on before you save.
• Expecting a widget to change the field type. A widget changes how data is entered. The field type decides what can be stored.

For marketing and content teams

The widget shapes your daily editing work. If entering tags one by one is slow, or a long select list is hard to use, ask your site builder to change the widget on Manage form display. No code is needed when a suitable widget already exists. If none fits your workflow, a developer can write a new widget plugin.

With DXPR

The content types that ship with DXPR Builder hide their builder field on the edit form, so editors change that content only in the builder. You can do the same on your own content types by moving the builder field into the Disabled section of Manage form display; see the setup guide and DXPR Builder.

Sources

• Drupal User Guide: Concept: Forms and Widgets
• Drupal User Guide: Changing Content Entry Forms
• Drupal core 11.4.8: Field UI help text (FieldUiHooks.php)
• Drupal core 11.4.8: Field Widget API topic (field.api.php)
• Drupal core 11.4.8: WidgetInterface
• Drupal core 11.4.8: FieldWidget attribute
• Drupal core 11.4.8: StringTextfieldWidget
• Drupal core 11.4.8: EntityReferenceAutocompleteTagsWidget
• Drupal core 11.4.8: BooleanCheckboxWidget
• Drupal core 11.4.8: OptionsSelectWidget
• DXPR Builder: Use DXPR Builder on your content types