Skip to content

Name Field Developer Docs

This documentation is for developers integrating or extending the Drupal Name module in custom code.

Field, widget, and formatter

The module provides a Drupal field type for structured personal names:

  • Field type — NameItem stores name values on entities.
  • Widget — NameWidget for editing; configurable per field and display (Field Settings, Widget examples).
  • Formatter — NameFormatter for display; delegates to the name.formatter service (Formatter examples).
  • Form element — #type => 'name' for non-field forms.

See API Overview for architecture, class names, and plugin IDs.

Name structure

Each name value is a keyed array with six core components:

  • title
  • given
  • middle
  • family
  • generational
  • credentials

Field storage settings control which components are visible and required, reading-order layout (default, asian, eastern, german), and input type (text, select, or autocomplete). Preferred and alternative variants can also participate in formatting when configured. See Field Settings for the full settings reference.

Formatting names

Display output is driven by name formats — NameFormat config entities with token patterns (for example, t g f). Site-wide defaults live under administration configuration; custom code uses the name.formatter service.

List formats (NameListFormat) join multiple names into natural-language lists. The name.format_parser service resolves format patterns. See the Formatter service and Parser service for programmatic use.

$formatter = \Drupal::service('name.formatter');
$label = $formatter->format([
  'given' => 'Jane',
  'family' => 'Smith',
], 'full');

Add custom formats via config entities — see Extending. Token output uses [entity:field:formatted:FORMAT_ID]; see Token integration.

Beyond the field

Version requirements

  • Drupal 10.3+ or Drupal 11+
  • PHP 8.3+

Project resources

pipeline status coverage report