Skip to main content

​
Overview

The Card block (_card.liquid) is a versatile container that supports background media (images or videos), overlay effects, and flexible content layouts. Cards can contain nested blocks and support various aspect ratios and alignment options.

​
Schema Definition

​
Supported Child Blocks

The card block accepts these nested block types: 
"blocks": [
  { "type": "text" },
  { "type": "_heading" },
  { "type": "image" },
  { "type": "video" },
  { "type": "product-card" },
  { "type": "collection-card" },
  { "type": "@theme" },
  { "type": "@app" }
]

​
Configuration Settings

​
Layout Settings

​
content_direction
select
default:"column"
Direction of content flow
  • column - Vertical layout
  • row - Horizontal layout
​
vertical_on_mobile
checkbox
default:"true"
Force vertical layout on mobile devices (when content_direction is “row”)
​
horizontal_alignment
select
default:"flex-start"
Horizontal alignment for row layouts
  • flex-start - Left aligned
  • center - Center aligned
  • flex-end - Right aligned
  • space-between - Distribute space between items
​
vertical_alignment
select
default:"center"
Vertical position for row layouts
  • flex-start - Top
  • center - Center
  • flex-end - Bottom
​
vertical_alignment_flex_direction_column
select
default:"center"
Vertical position for column layouts
  • flex-start - Top
  • center - Center
  • flex-end - Bottom
  • space-between - Distribute space
​
gap
range
default:"12"
Spacing between child elements (0-100px)

​
Appearance Settings

​
inherit_color_scheme
checkbox
default:"true"
Inherit color scheme from parent section
​
color_scheme
color_scheme
default:"scheme-1"
Color scheme when not inheriting (visible_if: inherit_color_scheme == false)
​
background_media
select
default:"none"
Background media type
  • none - No background
  • image - Static image
  • video - Video background
​
background_image
image_picker
Background image (visible when background_media is “image”)
​
video
video
Background video (visible when background_media is “video”)
​
aspect_ratio
select
default:"adapt"
Card aspect ratio (visible when background_media is set)
  • adapt - Auto (based on media)
  • portrait - 2:3 ratio
  • square - 1:1 ratio
  • landscape - 16:9 ratio

​
Overlay Settings

​
toggle_overlay
checkbox
default:"false"
Enable media overlay
​
overlay_color
color
default:"#00000026"
Overlay color with alpha support (visible when toggle_overlay is true)
​
overlay_style
select
default:"solid"
Overlay style
  • solid - Solid color
  • gradient - Gradient effect
​
gradient_direction
select
default:"to top"
Gradient direction (visible when overlay_style is “gradient”)
  • to top - Bottom to top fade
  • to bottom - Top to bottom fade

​
Link Settings

​
link
url
Make entire card clickable
​
open_in_new_tab
checkbox
default:"false"
Open link in new tab

​
Padding Settings

​
padding-block-start
range
default:"0"
Top padding (0-100px)
​
padding-block-end
range
default:"0"
Bottom padding (0-100px)
​
padding-inline-start
range
default:"0"
Left padding (0-100px)
​
padding-inline-end
range
default:"0"
Right padding (0-100px)

​
Liquid Implementation

​
Basic Structure

{% assign block_settings = block.settings %}

<div
  class="card{% if block_settings.inherit_color_scheme == false %} color-{{ block_settings.color_scheme }}{% endif %}"
  ref="slides[]"
  data-carousel-card
  {{ block.shopify_attributes }}
>
  {%- if block_settings.link != blank and block_settings.background_media != 'video' -%}
    <a href="{{ block_settings.link }}" class="card__link"
      {% if block_settings.open_in_new_tab %}target="_blank" rel="noopener"{% endif %}>
    </a>
  {%- endif -%}
  
  <div class="card__media-wrapper">
    {% render 'background-media',
      background_media: block_settings.background_media,
      background_video: block_settings.video,
      background_image: block_settings.background_image
    %}
  </div>
  
  <div class="card__content">
    <div class="card__inner layout-panel-flex">
      {% content_for 'blocks' %}
    </div>
  </div>
</div>

​
Aspect Ratio Logic

{% case block_settings.aspect_ratio %}
  {% when 'landscape' %}
    {% assign card_ratio = '16 / 9' %}
  {% when 'portrait' %}
    {% assign card_ratio = '2 / 3' %}
  {% when 'square' %}
    {% assign card_ratio = '1 / 1' %}
  {% when 'adapt' %}
    {% if preview_image %}
      {% assign card_ratio = preview_image.aspect_ratio %}
    {% endif %}
{% endcase %}

​
CSS Classes

​
Main Classes

  • .card - Main container with overflow hidden and border radius
  • .card__content - Content wrapper with z-index layering
  • .card__inner - Flex container for child blocks
  • .card__media-wrapper - Absolute positioned background media
  • .card__link - Full-card clickable overlay

​
Utility Classes

  • .color-{scheme} - Color scheme variants
  • .layout-panel-flex - Flexbox layout system
  • .background-transparent - Transparent background for overlay effects

​
Usage Examples

​
Card with Background Image

{
  "type": "_card",
  "settings": {
    "background_media": "image",
    "aspect_ratio": "landscape",
    "toggle_overlay": true,
    "overlay_color": "#00000040",
    "content_direction": "column",
    "vertical_alignment_flex_direction_column": "flex-end"
  },
  "blocks": {
    "heading": {
      "type": "_heading",
      "settings": {
        "text": "Featured Collection"
      }
    }
  }
}

​
Horizontal Card Layout

{
  "type": "_card",
  "settings": {
    "content_direction": "row",
    "horizontal_alignment": "space-between",
    "vertical_alignment": "center",
    "gap": 24,
    "padding-inline-start": 32,
    "padding-inline-end": 32
  }
}

​
Clickable Card

{
  "type": "_card",
  "settings": {
    "link": "/collections/new-arrivals",
    "background_media": "image",
    "toggle_overlay": true,
    "overlay_style": "gradient",
    "gradient_direction": "to top"
  }
}

​
Source Code Reference

View the complete implementation: /source/blocks/_card.liquid:1-533

Build docs developers (and LLMs) love

Get started for freeTalk to us