Display Suite
Display Suite allows you to take full control over how your content is displayed using a drag and drop interface.
ds
Install
composer require 'drupal/ds:8.x-3.32'
Overview
Display Suite provides a powerful and flexible way to control how content, users, and other entities are displayed in Drupal. It extends the core Field UI to give site builders more control over entity displays by allowing them to select layouts, create custom fields, and apply field templates.
With Display Suite, you can select different layouts for your content (1-4 columns, stacked, fluid variants), drag and drop fields into different regions, create dynamic fields (Token, Twig, Block, or Copy fields), and control the HTML markup output with field templates. It integrates with Views to provide advanced entity row styling options with alternating view modes, grouping, and language rendering.
Display Suite works as a layer on top of Drupal's core entity display system, storing its configuration as third-party settings on entity view displays. It provides its own plugin system for creating custom DS fields that can display computed values, blocks, or any custom content.
Features
- Drag and drop interface for arranging fields into layout regions on the Manage Display screen
- Multiple built-in layouts including 1, 2, 3, and 4 column layouts with stacked, fluid, and equal-width variants
- Custom field creation: Token fields, Twig fields, Block fields, and Copy fields for reusing existing field definitions
- Field templates (Default, Minimal, Expert, Reset) for controlling individual field markup output with wrappers, classes, and attributes
- Views integration with DS Entity Row plugin supporting alternating view modes, grouping, delta fields, and advanced render control
- Layout cloning to copy display configurations between view modes
- Emergency mode to temporarily disable Display Suite rendering
- CSS class management for regions and fields
- Token and Twig support for dynamic content in custom fields
- Integration with Layout Discovery for using any registered layouts
Use Cases
Creating a multi-column article layout
Use Display Suite to create a two or three column layout for article content types. Navigate to Admin > Structure > Content types > Article > Manage display, select a DS layout (e.g., Two column stacked), then drag your fields into the appropriate regions (header for title, left column for main content, right column for metadata like author and date, footer for tags). Save and view an article to see the new layout.
Adding a custom computed field
Create a Twig field at Admin > Structure > Display Suite > Fields > Add twig field. Name it 'Reading Time', select the 'Node' entity type, and enter Twig code like '{{ (entity.body.value|striptags|split(' ')|length / 200)|round }} min read'. This field can then be placed in any node display to show estimated reading time.
Embedding a block in entity display
Use a Block field to embed a block directly in your entity display. Go to Admin > Structure > Display Suite > Fields > Add block field, select a block (e.g., a Related Content view block or a custom block), then place this field in your entity's display like any other field.
Creating alternating teasers in Views
In a Views listing, use the DS Entity Row format and enable 'Alternating view mode'. Configure different view modes for odd and even rows (e.g., Teaser and Teaser Alternate) to create visual variety in content listings.
Controlling field markup with Expert template
Enable field templates in DS settings, then on Manage Display, click the settings gear for a field and select 'Expert' template. Configure outer wrappers (div, span, etc.), add custom classes like 'field-featured', set attributes, and add prefix/suffix HTML for complete control over field output.
Per-node view mode selection
Enable the DS Switch View Mode submodule, create multiple view modes for nodes (e.g., Full, Full with sidebar, Landing page), then when editing a node, use the 'Display settings' section to select which view mode should be used when viewing that specific node.
Cloning display configuration
After setting up a complex layout for one view mode, use the 'Clone layout' feature to copy it to another view mode. In Manage Display, when no layout is selected, choose a source view mode from the Clone layout dropdown to duplicate the configuration.
Tips
- Use the 'Disable layout CSS styles' option when your theme provides its own responsive grid system to avoid CSS conflicts.
- The Reset layout and Reset field template output content with minimal markup - useful when you want complete control via CSS/JS or when outputting to an API.
- Token fields are processed at render time, so they work well for dynamic content like 'Posted X time ago' or conditional content based on field values.
- Twig fields have access to the full entity object, making them powerful for complex computed displays without writing custom code.
- Copy fields let you reuse a DS field definition across multiple entity types without recreating it.
- The Expert field template supports token replacement in wrapper classes and attributes for dynamic styling based on entity data.
- Use ui_limit on custom fields to restrict them to specific bundles or view modes, keeping the Field UI cleaner.
- When debugging, DS Devel's Markup tab shows the actual HTML output, which is invaluable for theming and troubleshooting.
- The ds_classes_alter hook allows modules or themes to add context-aware CSS classes dynamically.
- DS stores configuration as third-party settings on entity view displays, making it fully exportable with core config management.
Technical Details
Admin Pages 9
/admin/structure/ds
Main Display Suite administration page listing all entity types and bundles. Provides quick access to manage display settings for each entity bundle.
/admin/structure/ds/settings
Configure global Display Suite settings including field template defaults, emergency mode, and class management options.
/admin/structure/ds/classes
Define custom CSS classes that can be applied to layout regions and fields on Manage Display pages.
/admin/structure/ds/fields
Manage custom Display Suite fields including Token fields, Twig fields, Block fields, and Copy fields.
/admin/structure/ds/fields/manage_token
Create a custom field that uses Token replacements to display dynamic content.
/admin/structure/ds/fields/manage_twig
Create a custom field using Twig template syntax for advanced dynamic content.
/admin/structure/ds/fields/manage_block
Create a custom field that renders a block plugin within entity displays.
/admin/structure/ds/fields/manage_copy
Create a field that copies the output of an existing Display Suite field.
/admin/structure/ds/emergency
Emergency controls to temporarily disable Display Suite rendering site-wide. Useful for debugging infinite loops or display issues.
Permissions 3
Hooks 7
hook_ds_fields_info_alter
Alter the DS field definitions before they are cached. Use to modify field properties or add new fields programmatically.
hook_ds_pre_render_alter
Alter the entity render array before DS processes it. Called before layout is applied.
hook_ds_layout_settings_alter
Alter layout settings when saving from the Field UI form.
hook_ds_layout_region_alter
Alter the available regions and region options on the Field UI display page.
hook_ds_label_options_alter
Alter the label display options available for fields.
hook_ds_classes_alter
Alter the list of CSS classes available for regions or fields.
hook_ds_views_row_render_entity
Advanced hook for controlling Views DS entity row rendering. Must enable 'Advanced view mode' in Views row settings.
Troubleshooting 7
After selecting a layout, you must save the Manage Display form. If fields disappear, they were moved to the first region - drag them to the appropriate regions and save again.
Use the Emergency mode at /admin/structure/ds/emergency to temporarily disable Display Suite. This often indicates a view embedded in an entity display that references the same entity.
DS fields only appear when a DS layout is selected. Ensure you've chosen a layout from the dropdown in the Layout settings on the Manage Display page.
Check the field's 'Limit field' setting. Ensure the bundle/view mode combination matches your configured limits (e.g., article|* for all article view modes).
Field templates must be enabled in Display Suite settings (/admin/structure/ds/settings). Check 'Enable field templates' and save.
Display Suite automatically disables itself when Layout Builder is enabled for a display. Disable Layout Builder in the entity display settings to use DS instead.
Some Views row options like 'Use view mode of display settings' require the DS Switch View Mode submodule to be enabled. Advanced view mode requires implementing hook_ds_views_row_render_entity().
Security Notes 4
- Token and Twig fields can output raw HTML. Ensure only trusted administrators have permission to create and edit these fields.
- The DS Extras 'Field permissions' feature adds granular access control but should be tested thoroughly as it creates permissions for all DS fields.
- Block fields render arbitrary blocks in entity context - verify blocks don't expose sensitive data when rendered in unexpected contexts.
- When using tokens in Expert field templates, be aware that user-controlled data could be injected if not properly sanitized.