Article SizingGuide

Content width and a maximum width New

In the base layouts and their text-based presets, set width: 'auto' to measure text plus layout spacing. An optional finite, non-negative maxWidth caps that measurement before text wraps and height is calculated. Numeric widths ignore the cap. Without a cap, automatic width can grow to fit the content. The image-only preset uses separate image-based measurements.

article.setStyle({
  width: 'auto',
  maxWidth: 280,
  height: 'auto',
  header: { height: 'auto', padding: 6, color: '#e2e8f0' },
  subheader: {
    height: 'auto', padding: { top: 6, bottom: 6 }, color: '#f1f5f9',
    text: { numberOfLines: 4, color: '#334155' }
  },
  image: { visible: true, margin: { top: 4, right: 12, bottom: 4, left: 4 } }
});

In the base layouts, image resolution does not determine card width. Portrait images fit the measured width; landscape reserves its thumbnail and margins. Drawing, image decode targets, stacking, hit areas, and viewport fitting use the resolved dimensions. Try the Article Sizing example.

Images and star overlays

Changed image.maxHeight caps rendered images in both layouts and their presets, with any image shape and automatic or numeric card height. It defaults to 200 pixels and leaves an explicitly set card height unchanged.

Portrait images retain their width and crop centrally when too tall. Fixed-height portrait cards also constrain images to the height remaining after text, borders, and margins. Square/circle shapes show a central slice when capped, without squeezing circles into ellipses.

Landscape and pill thumbnails are constrained by available width and image.maxHeight. Automatic card height grows with text while keeping a stable preferred thumbnail footprint (62 pixels with default margins); numeric card height uses the card height minus its top and bottom image margins. For example, a 70-pixel card with 4-pixel image margins, sufficient width and image.maxHeight: 20 has a thumbnail no larger than 20 pixels while the card stays 70 pixels tall. With the default cap, that thumbnail remains 62 pixels.

Migration: fixed-height landscape thumbnails and automatic square/circle portrait images previously ignored this cap. Raise it if an image should retain its former size. Automatic card heights can shrink with the image.

image.margin accepts a number or per-side object. Landscape's right margin separates the thumbnail from the text blocks. Object overrides merge by side; switching from a number to an object replaces the shorthand, with any still-unspecified sides resolving to zero. image.visible: false removes the image and spacing while retaining its URL and loaded image; it does not cancel loading. In the base layouts, missing or loading images occupy no image area. The image-only preset instead keeps the placeholder described below.

Changed In both layouts, the star overlays the top-right corner without changing text wrapping or card dimensions. Its size and hit area stay within the card bounds. Add text margin or padding when content needs extra clearance.

Image-only sizing and placeholders New

The image-only preset keeps a filled card when its image is missing, loading, failed, or hidden. It uses the effective backgroundColor (preset default '#f0f0f0', light grey), including hover and active overrides. Borders, rounded corners, connectors, and the hit area remain; no text or loading icon is added.

Numeric dimensions stay fixed. Automatic dimensions assume a square until the image is available, subject to the size caps:

maxWidth caps automatic width only; image.maxHeight caps automatic placeholder height. With both dimensions automatic, the square starts from the preset's 220-pixel width and respects both caps. Raising image.maxHeight from its default 200 to 320 allows a 220 × 220 placeholder. Fixed heights remain fixed. These sizes describe the whole placeholder card; borders and image margins do not enlarge it.

After loading, automatic height follows the image's aspect ratio with normal portrait fitting and cropping. Automatic width with a fixed height fits that aspect ratio to the available image height, then applies maxWidth. With both dimensions automatic, width starts at 220 pixels (capped by maxWidth) and height follows the image. Square and circle image shapes retain their usual crop.

timeline.load([
  {
    id: 'image-placeholder', title: 'Image to follow', from: { year: 2024 },
    cardLayout: 'image-only',
    style: { width: 180, height: 'auto', backgroundColor: '#e2e8f0' }
  }
]);

Try image-only in the preset and sizing example: its middle card has no image, so you can compare the placeholder with loaded images.

Updating existing configurations

v1.7.0 introduces changes to card sizing and styling that may affect existing configurations.

Some style options that were previously ignored by certain layouts now take effect. If you've customised your article styles, check that your cards still look as intended when upgrading from v1.6.x or earlier. You only need to change settings if their appearance is affected.

Main changes to check

• Portrait card height: a numeric height now applies to portrait cards, not just landscape. If you only intended it for landscape, move it to article.layoutStyles.landscape.style and use height: 'auto' for portrait.
• Landscape text styling: landscape cards now respect explicit header/subheader heights, background colours, and subtitle line counts. If these settings were intended only for portrait, move them to article.layoutStyles.portrait.style. To keep the usual landscape appearance, use automatic text-block heights, transparent backgrounds, and a single subtitle line.
• Zero-height text blocks: setting header.height: 0 or subheader.height: 0 now hides the block and its text. Use 'auto' or a positive height to keep the text visible.

These settings can also be overridden by lane, per-article, hover, and active styles. See the article style cascade.

Other visual changes

• Image spacing: landscape images now have a default 4px gap before the text. Adjust image.margin if you want to remove it.
• Image sizing: image.maxHeight now applies to all image shapes in both layouts. Increase it if images appear smaller or more cropped than before.
• Star positioning: landscape stars no longer reserve space in the text area. Add right padding to the header or subheader if text overlaps the star.
• Subtitle spacing: the default subheader.text.lineHeight is now 14px. Set an explicit value if needed.

Custom card layouts

If you've registered custom layouts, see custom layout compatibility for the additional styling and sizing details.