Settings

Settings
Setting Default Notes
position bottom top, middle, bottom or between (first and last groups at the edges)
layout ['logoLabel', 'title', 'description', 'meta'] What's drawn, in order, and how it's grouped, see Layout
align left left, center or right
textEdges caps Place by cap height to baseline (caps) or by the letters' ink (ink)
padding 80 Inset for the text in px, as CSS shorthand: one value, [vertical, horizontal], [top, horizontal, bottom] or [top, right, bottom, left]. Text wraps at the width between the sides, and center centres within them
gap 24 Space below each element in px, between line boxes, so the visible space also takes in line height and descenders. With between, gaps between groups are minimums. Elements can set their own
fontPath Inter Font file for every element, unless it sets its own, see Fonts. Unset, each element uses the bundled Inter in its own weight (Bold title, Medium label, Regular description and meta)
googleFont none Google Fonts family for every element, as Fraunces or Fraunces:700, see Fonts. fontPath wins over it
imageFieldHandles ['seoImage', 'hero', 'featuredImage'] Share image fields for entries without a Social Image field
defaultImagePath img/og-default.png Returned by default()
format auto png, jpeg, or auto for JPEG when the card has a background image and PNG otherwise. Photos are several times smaller as JPEG, and flat cards keep crisper text as PNG
jpegQuality 85 1 to 100, for cards saved as JPEG
seoPlugins true Give SEOmatic and SEOmate each entry's share image, see With SEOmatic or SEOmate
sections, entryTypes [] Overrides by handle
styles [] Named overrides editors choose per entry, see Styles
label, title, description, meta Each element's settings, see Elements
logo, background, border See below

Element, logo, background and border settings are each an array under their name. In sections and entryTypes, an array changes only the keys it names, so 'border' => ['color' => '#ff0000'] keeps the border's widths.

Layout #

layout lists what's drawn, from the top: label, title, description, meta, logo for the logo on a row of its own, and logoLabel for the logo beside the label. An array groups items. Anything left out isn't drawn.

PHP 
'position' => 'between',
'layout' => [
    ['logoLabel'],
    ['title', 'description', 'meta'],
],

Items in a group keep their own gaps. With between, the first group sits at the top, the last at the bottom, and any between are spaced evenly, so this puts the logo and label at the top and the rest together at the bottom. Other positions stack the groups as one. Each item can appear once, and logoLabel counts as both the logo and the label.

Leave layout unset and cards stack as before, with each element its own group and in the order of: logoLabel, title, description, and meta. Like any setting, sections, entryTypes and styles can override it.

Elements #

label, title, description and meta each take an array of their settings. A string sets just the text, and false hides the element.

PHP 
'title' => [
    'text' => '{title}',
    'size' => 96,
    'lineHeight' => 1.05,
    'maxLines' => 2,
],
'description' => ['text' => '{summary}', 'lineHeight' => 1.3],
'meta' => false,
Key Default (label, title, description, meta) Notes
text {type.name}, {title}, empty, empty Object template, see Card text
show true Turn the element off. Hiding the label keeps the logo
size 28, 116, 32, 28 Text size in px
lineHeight 1.02 A multiple of the size, as in CSS. The extra space is shared above and below each line
maxLines 1, 3, 2, 1 Lines before the text is clamped with an ellipsis. A title needing fewer is balanced across the lines it uses
uppercase false, true, false, false Set the text in capitals
color #a3a3a3, #ffffff, #a3a3a3, #a3a3a3 Text colour
colorField none A Color field (or hex text field) to take the colour from, falling back to color
fontPath none The element's font file, over fontPath and googleFont
googleFont none The element's Google font, over fontPath and googleFont. The element's own fontPath wins over it
gap none Space below the element, over gap
align none left, center or right, over align. The label's also aligns a logo beside it
PHP 
'logo' => ['path' => '@webroot/img/logo.png', 'height' => 40],

A string sets just the path, and false hides the logo.

Key Default Notes
path none PNG or SVG drawn beside the label, or on its own row (see Layout)
height 48 Height in px. Its width follows its proportions
show true Turn the logo off
align none left, center or right on its own row, over align. Beside the label, it follows the label's

A PNG works on every server. Export it at about four times height so it stays sharp. SVG logos need ImageMagick with SVG support, which many servers don't have; without it the card is drawn with no logo and a warning is logged. Where it is available, ImageMagick's built-in SVG renderer can't draw masks, gradients or filters, so an SVG using them may come out wrong.

Background #

PHP 
'background' => [
    'color' => '#1f1f1f',
    'imageField' => 'hero',
    'opacity' => 0.4,
    'blendMode' => 'multiply',
],

A string sets just the colour. The image is the imageField's, then the share image (with useShareImage), then imagePath. With a Social Image field, the share image is the custom image or image field the editor picked. With the card picked, or no field, it's the first image in imageFieldHandles.

Images from asset fields must be JPEG, PNG, GIF, WebP or AVIF. Anything else, such as an SVG, is skipped with a warning in the log, as ImageMagick chooses how to read a file from its contents rather than its extension. imagePath is set in config, so it isn't checked.

Key Default Notes
color #000000 Canvas colour
colorField none A Color field (or hex text field) to take the colour from, falling back to color
imageField none Asset field for the background image
useShareImage false Fall back to the share image as the background: the Social Image field's pick, else the first image in imageFieldHandles
imagePath none Fixed background image, used last
fit cover cover (cropped around the focal point) or contain
padding, radius 0 Inset and corner radius in px
grayscale false Set the image in grayscale
opacity 0.25 Strength of the image. A transparent PNG keeps its transparency, scaled by this
imagePathOpacity none opacity for the imagePath image only, so a section can show its photos stronger than the pattern it falls back to
blur 0 Blur strength in px, roughly as CSS blur()
blendMode normal How the image blends with the colour: multiply, screen, overlay, darken, lighten, color-dodge, color-burn, hard-light, soft-light, difference or exclusion, as in CSS

Border #

PHP 
'border' => ['width' => [8, 0, 0, 0], 'color' => '#f5b400'],

A number or list sets just the widths, so 'border' => [8, 0, 0, 0] is a bar along the top in the default colour.

Key Default Notes
width 0 Widths in px, as CSS shorthand like padding. Drawn over the background image, and the text sits inside it
color #ffffff Border colour
colorField none A Color field (or hex text field) to take the colour from, falling back to color
View on GitHub