Key value field
Provides field types for storing key-value pairs with optional descriptions, supporting both plain text and formatted text values.
key_value_field
Install
composer require 'drupal/key_value_field:8.x-1.4'
composer require 'drupal/key_value_field:8.x-1.3'
Overview
Key Value Field is a Drupal field module that allows content editors to store structured data in the form of key-value pairs. Each field entry consists of three components: a key (identifier), a value (content), and an optional description (for administrative notes or context).
The module provides two field type variants: a plain text version for simple string values, and a long text version that supports text formats (like Basic HTML, Filtered HTML, etc.) for rich content. Both variants include database indexing on the key column for efficient lookups and querying.
This module is particularly useful for storing metadata, configuration snippets, custom attributes, API credentials (non-sensitive), or any other structured data where a labeled value needs to be associated with an entity. The optional description field provides a way to document the purpose or usage of each key-value pair without affecting the displayed output.
Features
- Two field types: Key / Value (plain) for simple text and Key / Value (long) for formatted text with text format support
- Three-column data structure: key (indexed), value, and optional description for each field entry
- Configurable maximum length for the key field (default 255 characters) with database-level enforcement
- Customizable widget labels for Key, Value, and Description fields to match your content model terminology
- Placeholder text support for all input fields to guide content editors
- Toggle to enable or disable the description field per widget configuration
- Formatter option to display value only or full key:value format
- Default text format configuration for the long text variant
- Database index on the key column for efficient queries and lookups
- Support for multi-value fields with standard Drupal cardinality settings
- Automatic validation requiring a key when a value is entered
- Compatible with Drupal 9.5, 10, and 11
Use Cases
Product Specifications
Use Key/Value fields to store product specifications like 'Weight: 2.5kg', 'Dimensions: 10x20x5cm', 'Material: Aluminum'. Each specification becomes a key-value pair, and the description field can document the measurement unit or data source.
API Configuration Storage
Store API endpoint configurations with keys like 'endpoint_url', 'api_version', 'timeout_seconds' and their corresponding values. The description field can explain what each configuration does or link to documentation.
Custom Metadata Attributes
Add custom metadata to content that doesn't fit standard fields. For example, store 'schema.org' properties as key-value pairs for SEO purposes, with the description explaining each property's usage.
Translation Keys and Values
Store translation strings or labels where the key is an identifier and the value is the translated text. The long text variant allows formatted content with text formats.
Feature Flags or Settings
Store feature toggle names and their values (enabled/disabled, configuration values) for content items, allowing per-entity configuration storage.
Tips
- The key field is indexed in the database, making it efficient to query entities by specific key values using Entity Query or Views
- Use the description field for internal documentation about what each key-value pair represents - it won't appear in the rendered output
- Customize widget labels to match your content model - for example, change 'Key' to 'Property Name' and 'Value' to 'Property Value' for better editor UX
- When using the long text variant, configure a default text format to ensure consistent formatting across entries
- The key is conditionally required - it becomes required only when a value is entered, allowing empty field entries
- For multi-value fields, each delta can have different key-value pairs, useful for storing multiple attributes on a single entity
Technical Details
Hooks 3
hook_help
Provides help text for the module on the help page
hook_theme
Declares theme implementations (currently empty, returns empty array)
hook_field_info_alter
Alters field type definitions for backward compatibility with Drupal versions before 10.2. Sets the category for the key_value field type on older Drupal versions.
Troubleshooting 3
Delete the module folder and re-download/clone it, then clear all caches using 'drush cr' or through the admin UI.
The key field is required when a value is entered. Either fill in both fields or leave both empty.
The key length is validated at the database level. Either shorten the key or increase the 'Key maximum length' in the field storage settings (only possible before data exists).