Name Widget Examples

Use these examples when you are building a custom form and want to reuse the Name element UI (#type => 'name') outside of normal entity form displays.

Full widget element example

$form['contact_name'] = [
  '#type' => 'name',
  '#title' => $this->t('Contact name'),
  '#required' => TRUE,
  '#default_value' => [
    'title' => '',
    'given' => 'Jane',
    'middle' => '',
    'family' => 'Smith',
    'generational' => '',
    'credentials' => '',
  ],
  '#minimum_components' => [
    'given' => 'given',
    'family' => 'family',
  ],
  '#allow_family_or_given' => FALSE,
  '#widget_layout' => 'stacked',
  '#wrapper_type' => 'fieldset',
  '#component_layout' => 'default',
  '#show_component_required_marker' => TRUE,
  '#flag_required_input' => TRUE,
  '#credentials_inline' => FALSE,
  '#open' => FALSE,
  '#summary_attributes' => [],
  '#components' => [
    'title' => [
      'type' => 'select',
      'title' => $this->t('Title'),
      'title_display' => 'description',
      'size' => 6,
      'maxlength' => 31,
      'options' => [
        '-- Select --',
        'Mr.',
        'Mrs.',
        'Ms.',
        'Dr.',
      ],
    ],
    'given' => [
      'type' => 'textfield',
      'title' => $this->t('Given'),
      'title_display' => 'title',
      'size' => 20,
      'maxlength' => 63,
    ],
    'middle' => [
      'type' => 'textfield',
      'title' => $this->t('Middle'),
      'title_display' => 'description',
      'size' => 20,
      'maxlength' => 127,
    ],
    'family' => [
      'type' => 'textfield',
      'title' => $this->t('Family'),
      'title_display' => 'title',
      'size' => 20,
      'maxlength' => 63,
    ],
    'generational' => [
      'type' => 'select',
      'title' => $this->t('Generational'),
      'title_display' => 'description',
      'size' => 5,
      'maxlength' => 15,
      'options' => [
        '-- Select --',
        'Jr.',
        'Sr.',
      ],
    ],
    'credentials' => [
      'type' => 'textfield',
      'title' => $this->t('Credentials'),
      'title_display' => 'placeholder',
      'size' => 35,
      'maxlength' => 255,
    ],
  ],
];

Top-level properties

• #components: per-component UI definitions.
• #minimum_components: which components count as required for a complete name.
• #allow_family_or_given: treat one of given/family as satisfying both minimums.
• #widget_layout: built-in values include stacked and inline.
• #wrapper_type: fieldset, details, or container.
• #component_layout: default, asian, eastern, or german.
• #show_component_required_marker: add required marker to required component labels.
• #flag_required_input: mark required component inputs as required.
• #credentials_inline: keep credentials inline instead of forcing a break.
• #open: applies when #wrapper_type is details.

Per-component properties

Each key in #components (title, given, middle, family, generational, credentials) can define:

• type: textfield or select.
• title: label string.
• title_display: title, description, placeholder, attribute, or none.
• size: HTML input size.
• maxlength: max allowed length.
• options: required for select. When resolved via name.options_provider, the array may contain a _none key for the empty prompt option; raw arrays may use ---prefixed labels instead. See Options Provider service.
• autocomplete: route settings for autocomplete.
• attributes: additional input attributes.
• exclude: hide a component.

Built-in autocomplete example

The built-in route (name.autocomplete) is useful when your custom form points at an existing Name field definition.

$form['contact_name']['#components']['credentials']['autocomplete'] = [
  '#autocomplete_route_name' => 'name.autocomplete',
  '#autocomplete_route_parameters' => [
    'field_name' => 'field_author_name',
    'entity_type' => 'node',
    'bundle' => 'article',
    'component' => 'credentials',
  ],
];

Notes:

• Route params must identify a real Name field.
• Suggestions are controlled by that field's autocomplete settings.
• For credentials, include the data source in field settings to suggest stored credentials values.

Custom autocomplete source example

When you need suggestions from another source, use your own route.

$form['contact_name']['#components']['title']['autocomplete'] = [
  '#autocomplete_route_name' => 'my_module.name_title_autocomplete',
];

Then return JSON results from your controller in core autocomplete format:

[
  ['value' => 'Dr.', 'label' => 'Dr.'],
  ['value' => 'Prof.', 'label' => 'Prof.'],
]

Field widget display settings

When configuring the NameWidget on a form display (Manage form display), these widget settings control labels, layout, and required markers:

• labels — per-component label strings (title, given, middle, family, generational, credentials).
• size — per-component HTML input size.
• title_display — per-component label display mode (title, description, placeholder, attribute, or none).
• widget_layout — built-in layout (stacked, inline, or custom layouts from hook_name_widget_layouts()).
• field_title_display — overrides the field-level label display when the widget defaults to before.
• show_component_required_marker — show required markers on required component labels.
• flag_required_input — mark required component inputs as HTML required.
• credentials_inline — keep credentials inline instead of forcing a break.
• override_field_settings — when enabled, widget display settings override shared field storage settings for this form display.
• wrapper_type — fieldset, details, or container around the component group.

Field storage settings (components, autocomplete, options) live on the field type. See Field storage settings.

For admin UI guidance, see the name.widget_options help topic.

Configure widget display on a form display

use Drupal\Core\Entity\Entity\EntityFormDisplay;

$display = EntityFormDisplay::load('node.article.default');
if ($display) {
  $display->setComponent('field_author_name', [
    'type' => 'name_default',
    'weight' => 10,
    'settings' => [
      'labels' => [
        'title' => 'Title',
        'given' => 'Given name',
        'middle' => 'Middle name(s)',
        'family' => 'Family name',
        'generational' => 'Suffix',
        'credentials' => 'Credentials',
      ],
      'size' => [
        'title' => 6,
        'given' => 20,
        'middle' => 20,
        'family' => 20,
        'generational' => 5,
        'credentials' => 35,
      ],
      'title_display' => [
        'title' => 'description',
        'given' => 'title',
        'middle' => 'description',
        'family' => 'title',
        'generational' => 'description',
        'credentials' => 'placeholder',
      ],
      'widget_layout' => 'stacked',
      'field_title_display' => 'before',
      'show_component_required_marker' => TRUE,
      'flag_required_input' => TRUE,
      'credentials_inline' => FALSE,
      'override_field_settings' => FALSE,
      'wrapper_type' => 'fieldset',
    ],
  ])->save();
}

Related docs

• Code Examples
• Field storage settings
• Autocomplete Service
• Element Validator service
• Widget Layout Hook