Layout structures

Table of contents

• Structure components
  • Sections and containers
  • Columns
• Controlling layout in components with children
• Complex components with multiple slots for nesting children

Structure components

In Experiences, you can create complex layouts by using structure components such as section, container, and columns. These components serve as content wrappers, allowing you to control the layout orientation and direction of multiple elements, as well as basic styling like margin and padding.

Sections and containers

The section and container components are content wrappers that allow you to control the layout orientation and direction of multiple elements. They provide a way to group elements together and apply common styles or layout properties to them. For example, you can use a section or container to group a set of related elements together and set their layout direction to 'row' or 'column'.

Sections are always full-width, spanning the entire width of the viewport, making them ideal for edge-to-edge layout blocks. Containers, in contrast, are usually centered with margin: auto and have a max width of 1192px, great for creating centered content with a consistent maximum width.

Columns

The columns component allows you to create column-based layouts on a 12 column grid. This is useful for creating complex layouts with multiple columns of content. Each child of a columns component can be assigned a specific number of columns, allowing you to control the width of each child relative to the total width of the columns component.

Controlling layout in components with children

When you add children to a component in Experiences, the children are automatically wrapped in a <div> element within the Experiences canvas. This can sometimes unexpectedly break layouts, especially if you're trying to create a layout with multiple children in a row or column.

To work around this issue, you can use a container or section component to wrap your children. This allows you to control the layout of the children and apply common styles to them.

For example, if you want to create a horizontal layout, you can place a section as the top-level child, set its layout direction to 'row', and then nest the components you want to layout horizontally within that section. This approach allows you to make style adjustments on the nested structure component, thereby controlling the layout direction and other styles. These adjustments can be made in the Design sidebar.

For advanced use cases, you can write CSS to target the .contentful-container class to overwrite styles for sections and containers. This gives you more control over the appearance of your components and allows you to create more complex layouts.

Complex components with multiple slots for nesting children

Starting from @contentful/experiences-sdk-react v1.6.0, custom components can be enhanced with multiple slots for nesting children components. This enhancement provides developers with greater flexibility in creating complex structures within their custom components, if desired.

To utilize multiple slots, define a slots configuration in the component definition. Each slot requires a unique key and a display name.

defineComponents([
  {
    component: NestedSlots,
    definition: {
      // ... other props ...
      slots: {
        childrenSlot1: {
          displayName: 'Slot 1',
        },
        childrenSlot2: {
          displayName: 'Slot 2',
        },
      },
    },
  }
])

In your custom component, manage the props for each slot. Use the key of each slot definition object as the prop variable name:

const NestedSlots: React.FC<Props> = ({ childrenSlot1, childrenSlot2, ...props }) => {
  return (
    <div {...props}>
      <>
        <p>First Slot</p>
        {childrenSlot1}
      </>
      <>
        <p>Second Slot</p>
        {childrenSlot2}
      </>
    </div>
  );
};

Upon adding the custom component to an experience, each slot automatically receives a container component. The container's display name matches the slot's configured display name. This slot container aids in layout management, facilitating the positioning and orientation of nested child components.