UI Patterns (SDC in Drupal UI)
Expose SDC (Single Directory Components) as Drupal plugins and use them seamlessly in Drupal development and site-building.
ui_patterns
Install
composer require 'drupal/ui_patterns:^2.0'
Overview
UI Patterns is a comprehensive module that extends Drupal Core's Single Directory Components (SDC) API, providing a robust framework for defining, managing, and using reusable UI components across your Drupal site. Components are reusable, nestable elements guided by clear standards that can be assembled to build any number of applications.
The module provides a plugin-based architecture where components can be used as blocks, layouts, field formatters, and Views row/style plugins. It includes a sophisticated source system that allows mapping various data sources (fields, entities, tokens, menus, breadcrumbs) to component props and slots.
UI Patterns extends JSON Schema validation for component properties, automatically detects property types (string, number, boolean, enum, URL, links, slots, etc.), and provides appropriate widgets for configuring each property type in the admin UI.
Features
- Extends Drupal Core SDC API with additional features and quality-of-life improvements
- Plugin-based architecture exposing components as Blocks, Layouts, Field Formatters, and Views plugins
- Comprehensive Source plugin system for mapping data to component props and slots
- PropType system with automatic detection from JSON Schema (string, number, boolean, enum, URL, links, list, attributes, slot, etc.)
- Component library browser for documentation and showcasing components
- Widget system for configuring component props (textfield, select, checkbox, WYSIWYG, etc.)
- Context-aware source plugins that adapt based on entity, field, or view context
- Support for component variants and custom attributes
- Twig filters for adding classes and setting attributes on components
- JSON Schema reference resolution with custom ui-patterns:// schema protocol
- Component negotiation system allowing themes to replace module components
- Legacy compatibility layer for UI Patterns 1.x components
- Stories/previews system for component documentation
Use Cases
Creating a Card Component for Content Listing
Create a card component in your theme with props for title, image, summary, and link. Enable UI Patterns Field Formatters and configure an entity reference field to use the 'Component per item' formatter. Map the referenced entity's title to the card's title prop, image field to image prop, and body summary to the summary prop. Each referenced entity renders as a styled card.
Building a Hero Section with Layout Builder
Create a hero component with slots for background, content, and call-to-action. Enable UI Patterns Layouts to expose it as a layout. In Layout Builder, select the hero layout for a section, then place blocks (text, images, buttons) into each slot region. Configure variant props to switch between centered and left-aligned styles.
Displaying Navigation Menus
Create a navigation component with a 'links' prop type. When configuring the component in a block, select the 'Menu' source for the links prop and choose the desired menu. The menu tree is automatically transformed into the links data structure expected by the component.
Creating Reusable Page Layouts
Define page layout components with slots for header, sidebar, main content, and footer. Use these as layouts in Layout Builder for consistent page structure across your site. Different variants can provide two-column or three-column arrangements.
Building Views with Component Templates
Create a teaser component for content teasers. Enable UI Patterns Views and configure a view to use 'Component (UI Patterns)' as the row plugin. Map view fields to component props using the field source plugins. Each view result renders using your component template.
Migrating from UI Patterns 1.x
Enable UI Patterns Legacy to load components defined in the 1.x YAML format. This allows gradual migration to the new SDC-based component format while maintaining backward compatibility with existing component definitions.
Tips
- Use the 'group' property in component.yml to organize components into logical categories in the library
- Define stories.yml files alongside your components to provide preview examples in the component library
- The 'attributes' prop is automatically added to all components - use it to pass custom classes and data attributes
- Use the 'noUi: true' property in component.yml to hide internal/utility components from selection interfaces
- Components can use the 'replaces' property to override components from other modules or themes
- Source plugins are context-aware - field sources only appear when entity context is available
- The add_class and set_attribute Twig filters help manipulate attributes within component templates
- Use JSON Schema $ref with 'ui-patterns://' protocol to reference UI Patterns' built-in prop type schemas
- PropType adapters handle data transformation between compatible but differently structured schemas
- Clear caches after adding or modifying components to see changes in the admin interface
Technical Details
Admin Pages 5
/admin/appearance/ui
Landing page for UI-related libraries including components, icons, styles, and examples. Serves as an entry point to the design system libraries.
/admin/appearance/ui/components
Browse all available UI components grouped by category. Displays component name, provider, description, and quick links to individual component pages. Components are organized by their 'group' property defined in component.yml.
/admin/appearance/ui/components/{provider}
Browse components provided by a specific module or theme. Shows all components from that provider organized by group.
/admin/appearance/ui/components/{provider}/{machineName}
Detailed documentation page for a single component. Shows component metadata (name, group, description, status), props table with types and defaults, slots table, and rendered story previews if defined.
/admin/structure/component
Administrative listing of all components with their form display management. Allows configuring how component props and slots are presented in content editing forms. Part of the experimental UI Patterns UI module.
Permissions 3
Hooks 6
hook_component_info_alter
Alter SDC component definitions after they are discovered. Allows modifying props, slots, and other component metadata.
hook_ui_patterns_source_value_alter
Alter values produced by source plugins before they are passed to components.
hook_ui_patterns_component_pre_build_alter
Prepare the component render element before it passes through the renderer pipeline.
hook_plugin_filter_block__ui_patterns_alter
Filter block plugins that can be used as sources in UI Patterns. Set _ui_patterns_compatible to FALSE to exclude blocks.
hook_component_form_display_groups
Define groups for the component form display configuration interface. (UI Patterns UI module)
hook_component_form_display_group_row_alter
Alter a group row in the component form display table. (UI Patterns UI module)
Troubleshooting 5
Check that the component.yml is valid, clear caches, and verify the component doesn't have 'noUi: true' set. Ensure the component has at least one slot defined for block/layout integration.
Verify the prop's JSON schema matches a known PropType. If using custom schemas, ensure they are compatible with existing prop types or create a PropType adapter.
Check that prop values match the expected JSON schema types. UI Patterns normalizes values, but incompatible data structures may still cause validation failures.
Ensure entity context is available. In blocks, this requires the block to be placed in a context that provides an entity (e.g., Layout Builder on an entity display).
Enable the UI Patterns Legacy module which requires UI Patterns Library. Ensure the legacy pattern definitions are in the expected YAML format.
Security Notes 4
- The WYSIWYG source respects Drupal's text format permissions - ensure appropriate formats are configured
- Token replacement in the Token source follows Drupal's token system security model
- Block sources filter out inline_block and certain system blocks by default to prevent content/config entity dependencies
- Component attribute values are sanitized through Drupal's Attribute class when rendered