Documentation
Paragraphs
Sites built with the Paragraphs module can render their paragraph types as Maya components without writing templates. Go to Appearance > Settings > Maya (or your sub-theme), open Paragraph types, and choose a component for each type. Types without a component render as Drupal would.
Components
| Component | Renders | Parts |
|---|---|---|
| Grid | Referenced items side by side, one per column. | Items, number of columns, view mode of the items, heading, shaded background |
| Card | A bordered box. | Image, heading, link, body |
| Spotlight | Text and a button beside a large image, like the home page spotlight. | Image, heading, link, body |
| Button | A link styled as a button, with an optional heading and text above it. | Heading, link, button text, body (text fields only) |
| Accordion item | A heading that expands to show the text. | Heading, open by default, body |
| Hidden | Nothing, not even an empty grid cell. Use it for spacers and other layout helpers. |
How fields fill the parts
Each part takes the first field that fits it, unless you pick a field in the type's fields settings. Pick None to leave a part empty.
| Part | First field that fits |
|---|---|
| Items | Entity reference revisions (paragraphs), then dynamic entity reference, then any entity reference that is not an image |
| Number of columns | A list or number field with column in its machine name. Values from 1 to 6. |
| View mode of the items | An Entity reference display field, or one with view_mode or display_mode in its name. Without one, paragraphs use their default view mode and other entities their teaser. |
| Heading | A text field with title or heading in its name, then one with label |
| Shaded background | A field with background in its name. Any value shades the grid. |
| Image | An image field or a media reference |
| Link | A link field. The link text labels the button. |
| Button text | A text field with button, text or label in its name. Overrides the link text. |
| Open by default | A boolean field |
| Body | Every other field the paragraph's display shows, in its order. Fields the display hides stay hidden. List, number and boolean fields are treated as settings and left out. |
Grids span the content column. Text inside them, and text fields elsewhere in a node, keep to a readable width.
Example
A site with these paragraph types:
| Type | Fields | Component |
|---|---|---|
| Section | Contents (paragraphs), Columns (list: 1-4), Background color (list) | Grid |
| Card | Image (media), Title, Text, Link | Card |
| Hero | Image (media), Title, Text, Link | Spotlight |
| Detail | Label, Text, Open (boolean) | Accordion item |
| Gap | Size (list) | Hidden |
needs no field choices: every part is filled automatically.
Configuration
The mapping is stored in the theme's settings, so it deploys with configuration:
# maya.settings.yml, or mysubtheme.settings.yml
paragraphs:
section:
component: grid
gallery:
component: grid
fields:
items: field_images
A sub-theme needs a schema for its settings to validate. Reuse Maya's in config/schema/mysubtheme.schema.yml:
mysubtheme.settings:
type: maya.settings
Templates
Each component has a template in templates/paragraphs, for example paragraph--maya-grid.html.twig. Override one in a sub-theme to change every paragraph type mapped to that component, or use the type's own suggestion (paragraph--section.html.twig) to change just that type.