Schema Form Designs

Schema Form Design entities are used to add customizations to the data defined in the schema while rendering the form.

Using them, you can modify existing form elements by adding or replacing generated data, without touching the schema.

To declare a custom design, open the /admin/config/content/schema-form-design page, click the 'Add Schema Form Design' button, and fill in the fields:

Fields

ID

ID – a unique identifier for the Schema Form Design entity. Used to reference this design in routes or code by this value.

If the ID matches the schema key (for example, system.site or my_module.api_settings), it will be automatically applied to the schema form generated for this schema. For config entities, use the format [module_name].[config_entity_name], like my_module.my_entity, to design the edit form.

If it doesn't match an existing schema, you can apply it manually to any schema by specifying the ID in the design argument.

For example, you can create two different designs with IDs like system.site.design1 and system.site.design2, and on different routes apply a different design for the same schema like this:

my_module.basic_site_settings:
  path: '/admin/config/system/site-information-designed'
  defaults:
    _form: 'Drupal\schema_form\SchemaConfigFromRouteForm'
    _title: 'Basic site settings'
  requirements:
    _permission: 'administer site configuration'
  options:
    editable_config_names:
      - system.site
    design: system.site.design1

The key line here is design: system.site.design1 – it attaches the design to this route.

An example of attaching the design programmatically in the form class:

public function getSchemaFormDesignId(): string|null {
  return 'system.site.design1';
}

And using the service:

$form = \Drupal::service('schema_form')->getSchemaForm(
  schemaName: 'system.site',
  defaultValues: NULL,
  design: 'system.site.design1',
);

Instead of system.site, you can use your own custom schema key.

Label

Label – a display name for the Schema Form Design entity, used only to name the design in the admin panel. It is not used to render the form itself.

Custom schema name

Custom schema name – a custom name of the schema key to use with this design. Usually, the Schema Form Design id matches the schema key, but in some cases, the schema key value can be different. In that cases, you can put here the custom value of the schema key, and it will be used to render this design by default. Alternatively, you can put the Schema Form Design id in the Schema Form route without filing this field, to apply the design to any Schema Form form.

Design

Design – a YAML-formatted declaration of the design that is applied to the schema.

The design is additional data that is attached to the items declared in the schema. It usually starts with mapping: to attach customizations to specific items in the schema mapping. But if your schema has a root element that should be rendered, you can apply customizations to it at the root level.

Available options for the design YAML:

form_element – here you can set any values of the element as in the Drupal element array, such as overriding the title, description, altering the weight, or changing the form element type. See the example below.
skip – a boolean flag indicating that this item should be skipped from rendering.

More options will be added in the future to allow further customization.

Example of a design for a simple feedback form:

mapping:
  first_name:
    form_element:
      '#title': Enter your full name here
      '#weight': 20
      '#required': true
  last_name:
    skip: true
  message:
    form_element:
      '#description': Please write your detailed feedback here.

This design is intended to be attached to a schema like this:

my_module.my_feedback_form:
  type: mapping
  mapping:
    first_name:
      type: string
      label: First name
    last_name:
      type: string
      label: Last name
    email:
      type: email
      label: Your email
      constraints:
        NotBlank: ~
    message:
      type: text
      label: Message text
      constraints:
       NotBlank: ~

Inline design in the schema

You can apply design customizations options and metadata directly in the schema file, without creating a separate Schema Form Design entity.

This approach is covered on a separate page Schema Form schema fields