Basic section

A basic section is used to create structured content sections with a title, subtitle, and various content blocks. It provides a flexible layout system that can accommodate different types of content including text, images, videos, lists, code blocks, logos, and call-to-action elements.

The basic section pattern is composed of the following elements:

The default basic section uses a 50/50 grid layout that splits on large screens and stacks on smaller screens.

Layout Options

With Label

Basic sections can include a muted heading label above the main title.

Linked Title

The title can be made clickable by providing link attributes.

Subtitle

The subtitle is an optional text displayed below the main title, with a configurable heading level (h4 or h5).

By default, the subtitle is rendered as an h4 element, but you can change it to h5 by setting the heading_level property.

Split Layout

Use is_split_on_medium=true to create a 50/50 grid layout that splits on medium screens and above.

Top Rule variants

By default, the basic section has a default horizontal rule at the top. You can also use muted or highlighted rules, or disable the rule entirely using the top_rule_variant parameter.

Padding Variants

Basic sections support customizable padding options at both the pattern and item level, using the section pattern. The Jinja macro for the pattern applies the section padding automatically.

Pattern level

By default, the pattern is wrapped in a regular section.

For different spacing needs, you may instead use a deep section or a shallow section by changing the padding parameter.

Please refer to the section documentation for more guidance on padding selection.

Block level

Each item within the section can also have its own padding applied using the padding property. By default, items have no additional padding, but you can set padding: "shallow" to increase spacing around the item.

The last block will always have no additional padding, regardless of the item padding setting. This way, the pattern padding is the only padding at the bottom of the pattern.

Content Blocks

The basic section pattern uses a flexible block model where you can pass an array of items representing different content types. Each item has a type that determines the block behavior and an item object containing the specific configuration.

Description

Description blocks can be used to display elaborative text content.

By default, the description contents are rendered within a <p> tag, but you can also use type:"html" to render raw HTML content.

{
  "type": "description",
  "item": {
    "type": "text" | "html",
    "content": "Your content here"
  }
}

• type: Either "text" (default) or "html". Text content is wrapped in <p> tags, HTML content is rendered as-is.
• content: The text or HTML content to display.

Media

Image and video blocks allow you to embed rich media content.

Images

Images are automatically wrapped in the highlighted image container and can have configurable aspect ratios and a caption.

{
  "type": "image",
  "item": {
    "aspect_ratio": "16-9" | "3-2" | "",
    "caption_html": "Optional caption with HTML",
    "attrs": {
      "src": "image-url",
      "alt": "alt-text"
    }
  }
}

• aspect_ratio: Optional aspect ratio constraint. Valid values: "16-9", "3-2", or empty string for default.
• caption_html: Optional HTML caption. If provided, the image and caption are wrapped in a <figure> element.
• attrs: Dictionary of image attributes (src, alt, class, etc.). The p-image-container__image class is automatically applied. See attribute forwarding docs for more info.

Videos

Videos are automatically embedded in an iframe using the embedded media utility.

{
  "type": "video",
  "item": {
    "attrs": {
      "src": "video-url",
      "allowfullscreen": ""
    }
  }
}

• attrs: Dictionary of iframe attributes. Videos are automatically wrapped in the u-embedded-media utility. See attribute forwarding docs for more info.

List

Lists use the list pattern to display various types of lists.

• Bullet lists: Standard bullet points
• Numbered lists: Ordered lists
• Status lists: Lists with tick or cross icons
• Default lists: Simple unordered lists (no icon or numbering)
• Nested lists: Hierarchical list structures

{
  "type": "list",
  "item": {
    "list_items": [
      {
        "list_item_type": "bullet" | "tick" | "cross" | "number" | "",
        "content": "List item content",
        "sublist": {
          "list_items": [...]
        }
      }
    ]
  }
}

• list_item_type: Type of list item. If any item is "number", the entire list becomes ordered.
• content: HTML content of the list item.
• sublist: Optional nested list configuration.

Code

The code pattern allows you to display pre-formatted code snippets. Contents are wrapped in a <pre> tag and automatically dedented to remove leading whitespace.

Contents may also be wrapped in a <code> tag to indicate a code block.

Note: Multi-line code blocks will preserve indentation.

{
  "type": "code-block",
  "item": {
    "content": "Your code here",
    "is_code_snippet": true | false
  }
}

• content: The code content.
• is_code_snippet: If true, content is wrapped in <code> tags within the <pre> tag.

Logo

Logos may be displayed with the logo block (in the case of a simple list of logos), or the linked logo block (in the case of clickable logos).

We recommend against using both the logo block and linked logo block in the same section, as it can lead to confusion.

Logo block

The logo block is suitable for displaying logos in a flow layout. If you would like to include links to learn more about logo items, use the linked logo block instead.

{
  "type": "logo-block",
  "item": {
    "is_fixed_width": true | false,
    "logos": [
      {
        "attrs": {
          "src": "logo-url",
          "alt": "alt-text",
          "class": "optional-css-class"
        },
        "has_line_break_after": true | false
      }
    ]
  }
}

• is_fixed_width: Whether to wrap logos in a fixed-width container (default: true).
• logos: Array of logo objects. Each logo element has the following properties:
  • attrs: Dictionary of image attributes for the logo. The p-image-container__image class is applied automatically. See attribute forwarding docs for more info.
  • has_line_break_after: Whether to include a line break after the logo (hidden on small screens). Use this to force a logo to a new line, avoiding orphaned logos on the last line. See the logo block documentation for more information.

Linked logo block

The linked logo block uses the linked logo section pattern to display clickable logos.

Linked logo sections within the basic section always have no title and no top horizontal rule, in order to incorporate them into the basic section layout.

{
  "type": "linked-logo-block",
  "item": {
    "links": [
      {
        "href": "link-url",
        "text": "Link text",
        "label": "Aria label",
        "image_attrs": {
          "src": "logo-url",
          "alt": "alt-text",
          "width": "200",
          "height": "100"
        }
      }
    ]
  }
}

• links: Array of link objects. Each link element has the following properties:
  • href: URL the logo links to.
  • text: Text for the link (used as the link text).
  • label: Aria label for the link (for accessibility).
  • image_attrs: Dictionary of image attributes for the logo. p-image-container__image is applied automatically. See attribute forwarding docs for more info.

CTA

The CTA block allows you to include call-to-action elements within the section.

It supports three types of CTA items:

• Primary: 1 main call-to-action button
• Secondary: Supporting action buttons
• Link: Text link

We recommend against using the CTA item as a standalone item in the section. Instead, you should use the CTA Section pattern.

{
  "type": "cta-block",
  "item": {
    "primary": {
      "content_html": "Primary button text",
      "attrs": {
        "href": "link-url",
        "class": "optional-css-class"
      }
    },
    "secondaries": [
      {
        "content_html": "Secondary button text",
        "attrs": {
          "href": "link-url"
        }
      }
    ],
    "link": {
      "content_html": "Link text",
      "attrs": {
        "href": "link-url"
      }
    }
  }
}

• primary: Optional primary button configuration.
• secondaries: Optional array of secondary button configurations.
• link: Optional text link configuration.

Each of the CTA configurations accepts the following properties:

• content_html: The inner HTML of the CTA item.
• attrs: Dictionary of button/link attributes. These are applied to the CTA element. If href is present, the CTA item will be an <a>, otherwise it will be a <button>. See attribute forwarding docs for more info.

Notification

The Notification block allows you to include notifications within the section.

{
  "type": "notification",
  "item": {
    "type": "positive",
    "title": "This is a notification",
    "content": "The quick brown fox jumps over the lazy dog"
  }
}

• type: One of "information", "caution", "negative", or "positive"
• title: Title text of the notification block
• content: Descriptive text of the notification block

See Notifications for more information on notification blocks.

Jinja Macro

The vf_basic_section Jinja macro can be used to generate a basic section pattern. The API for the macro is shown below.

Parameters

Import

Jinja Macro

To import the Basic Section Jinja macro, copy the following import statement into your Jinja template.

{% from "_macros/vf_basic-section.jinja" import vf_basic_section %}

View the building with Jinja macros guide for macro installation instructions.

SCSS

Since Patterns leverage many other parts of Vanilla in their composition and content, we recommend importing the entirety of Vanilla for full support.