TRMNL X Guide
TRMNL X is a larger, 4-bit ePaper display. This guide covers what changed in the Framework to support it: new size modifiers, container query units, responsive overflow columns, and layout improvements. Existing plugins keep working; adopt these features to use the larger screen, portrait orientation, and expanded grayscale.
The --base Modifier
Every element and component now supports an explicit --base size modifier. It produces the exact same result as using the class without any size modifier, but it lets you reset to the default size at a specific breakpoint.
Previously, if you set a smaller size for compact screens, there was no way to undo it at a larger breakpoint. Now you can:
<!-- Small title on compact screens, default size on large screens -->
<span class="title title--small lg:title--base">Dashboard</span>
<!-- Extra-small value by default, normal size on medium+ screens -->
<span class="value value--xsmall md:value--base">48,206</span>
<!-- Small gap by default, standard gap on large screens -->
<div class="flex flex--col gap--small lg:gap--base">...</div>
The --base modifier is available on:
- Typography:
Title
Title
Style headings with consistent typography
Headings for a plugin screen. Five size variants from small to xxlarge, each with responsive prefixes for breakpoints and orientation.
(
title--base), Value Value Display data values with consistent formatting Figures and readouts on a plugin screen. Twelve size variants from xxsmall to peta, plus value--tnums for tabular numbers that keep columns aligned. (value--base), Label Label Create clear labels for unified content identification Short captions and status chips for a plugin screen. Five sizes plus style variants (filled, outline, underline, inverted) and semantic variants such as label--success and label--error. (label--base), Description Description Format descriptive text with standardized styles Supporting body text, sized to sit under a Title or a Value rather than compete with it. Four size variants from base to xxlarge, with wrapping or line clamping for longer copy. (description--base) - Rich Text:
Rich Text
Rich Text
Display formatted paragraphs with alignment and size variants
A container for long-form text: paragraphs, headings, lists, and quotes. The framework styles the children of the content block, so text from a feed renders in the framework font without a class on every tag.
(
content--base) - Components:
Table
Table
Create data tables optimized for 1-bit rendering
Tabular data with optional row indexes. Five size variants, and the Overflow and Clamp engines drop rows and truncate cells that do not fit the space available.
(
table--base), Progress Progress Display progress bars in different styles Progress bars and step dots for completion state. The fill renders as a bitmap pattern on 1-bit displays and as a solid color on 4-bit+ displays. (progress-bar--base,progress-dots--base) - Utilities:
Gap
Gap
Set precise spacing between elements with predefined gap values
Utility classes for the space between the children of a flex, grid, or column container. Predefined sizes, arbitrary values, distribution modifiers, and responsive variants.
(
gap--base), Rounded Rounded Control element rounding with predefined values Utility classes for corner radius. Predefined sizes, per-corner control, and arbitrary pixel values. (rounded--base), Text Stroke Text Stroke Legible text when displayed on shaded backgrounds Outline text so it stays legible on a shaded background. Set the stroke width and color with the text stroke utilities. (text-stroke--base), Image Stroke Image Stroke Legible images when displayed on shaded backgrounds Outline a vector or transparent raster image so it stays legible on a shaded background. Set the stroke width and color with the image stroke utilities. (image-stroke--base)
New Larger Typography Sizes
To take full advantage of TRMNL X's larger display, new size tiers have been added across all typography elements. All new sizes support responsive prefixes and render correctly on 2-bit and 4-bit screens.
Value
Four new sizes for hero-style numbers and display text. See the Value Value Display data values with consistent formatting Figures and readouts on a plugin screen. Twelve size variants from xxsmall to peta, plus value--tnums for tabular numbers that keep columns aligned. docs for full details.
<span class="value value--mega">42</span> <!-- 170px -->
<span class="value value--giga">42</span> <!-- 220px -->
<span class="value value--tera">42</span> <!-- 290px -->
<span class="value value--peta">42</span> <!-- 380px -->
<!-- Responsive example: xxxlarge on OG, giga on X -->
<span class="value value--xxxlarge lg:value--giga">42</span>Title
Three new large sizes for headings. See the Title Title Style headings with consistent typography Headings for a plugin screen. Five size variants from small to xxlarge, each with responsive prefixes for breakpoints and orientation. docs.
<span class="title title--large">Heading</span> <!-- 30px -->
<span class="title title--xlarge">Heading</span> <!-- 35px -->
<span class="title title--xxlarge">Heading</span> <!-- 40px -->Label, Description, Rich Text
New large sizes for
Label
Label
Create clear labels for unified content identification
Short captions and status chips for a plugin screen. Five sizes plus style variants (filled, outline, underline, inverted) and semantic variants such as label--success and label--error.
(label--large, label--xlarge, label--xxlarge),
Description
Description
Format descriptive text with standardized styles
Supporting body text, sized to sit under a Title or a Value rather than compete with it. Four size variants from base to xxlarge, with wrapping or line clamping for longer copy.
(description--large, description--xlarge, description--xxlarge), and
Rich Text
Rich Text
Display formatted paragraphs with alignment and size variants
A container for long-form text: paragraphs, headings, lists, and quotes. The framework styles the children of the content block, so text from a feed renders in the framework font without a class on every tag.
content (content--xlarge, content--xxlarge, content--xxxlarge).
Container Query Units
The
Layout
Layout
Primary container for organizing plugin content
The Layout is the content container inside a View, exactly one layout per view. It arranges content horizontally (layout--row) or vertically (layout--col), with alignment and stretch modifiers.
element now establishes a CSS Container Query context, enabling a new set of container-relative sizing utilities. Unlike viewport units, these are relative to the layout's dimensions, so they work correctly inside mashup slots (half vertical, quadrant, etc.) where the available space is a fraction of the full screen.
<!-- Width as percentage of the layout container -->
<div class="w--[50cqw]">Half the layout width</div>
<!-- Height as percentage of the layout container -->
<div class="h--[80cqh]">80% of layout height</div>
<!-- Min/max constraints -->
<div class="w--min-[30cqw] w--max-[70cqw]">Constrained width</div>
<!-- Responsive container query units -->
<div class="w--[100cqw] lg:w--[50cqw]">Full width on small, half on large</div>
Available utilities: w--[Ncqw], h--[Ncqh] (0 to 100), plus w--min-[Ncqw], w--max-[Ncqw], h--min-[Ncqh], h--max-[Ncqh]. All support responsive variants. See the
Size
Size
Define exact width and height dimensions for elements
Utility classes for width and height. Fixed sizes, arbitrary values, dynamic sizes, and container query units, each also available as a min or max constraint and with responsive variants.
docs for full details.
Responsive Arbitrary Sizes
The w--[Npx] and h--[Npx] utilities now support responsive prefixes, where they used to be static-only. Pixel values range from 0 to 128. See the
Size
Size
Define exact width and height dimensions for elements
Utility classes for width and height. Fixed sizes, arbitrary values, dynamic sizes, and container query units, each also available as a min or max constraint and with responsive variants.
docs.
<!-- Responsive arbitrary sizes -->
<div class="w--[80px] md:w--[110px] lg:w--[128px]">Responsive arbitrary width</div>
<div class="h--[100px] portrait:h--[128px]">Orientation-aware height</div>Responsive Overflow Columns
The Overflow Overflow Handle column items overflow The Overflow engine automatically lays out items into up to N columns and adds an "and X more" label when content exceeds the available height. It also applies text clamping per-column width and handles grouped headers without leaving orphaned headings. engine now reads responsive data attributes to determine how many columns to generate, based on screen size and orientation. Resolution order (most specific wins): size + portrait, then size, then portrait, then base.
<!-- 2 columns on small screens, 3 on large -->
<div class="columns"
data-overflow-max-cols="2"
data-overflow-max-cols-lg="3">
...
</div>
<!-- Different column counts for portrait orientation -->
<div class="columns"
data-overflow-max-cols="3"
data-overflow-max-cols-portrait="1"
data-overflow-max-cols-lg-portrait="2">
...
</div>
Supported suffixes: -sm, -md, -lg, -portrait, -sm-portrait, -md-portrait, -lg-portrait. The same pattern works for data-overflow-cols (fixed column count).
Layout Improvements
Axis-Correct stretch-x / stretch-y
stretch-x and stretch-y now behave correctly relative to the
Layout
Layout
Primary container for organizing plugin content
The Layout is the content container inside a View, exactly one layout per view. It arranges content horizontally (layout--row) or vertically (layout--col), with alignment and stretch modifiers.
direction. In layout--row, stretch-x grows along the horizontal axis and stretch-y stretches vertically, and in layout--col the axes are swapped. These utilities also now include min-width: 0 / min-height: 0 to prevent flex children from overflowing their containers.
Responsive Grid Column Spans
The
Grid
Grid
Create grid layouts with predefined column structures
Utility classes for column-based and row-based grids. Set the column count, span cells across columns, and change either at a breakpoint.
col--span-* classes now work with all responsive prefixes. Responsive parent variants also work: if the grid itself has a responsive prefix (e.g., portrait:grid), nested children resolve correctly.
<div class="grid grid--cols-6">
<div class="col--span-6 lg:col--span-3">Full width on small, half on large</div>
<div class="col--span-6 lg:col--span-3">Full width on small, half on large</div>
</div>
<!-- Portrait reflow -->
<div class="grid grid--cols-2 portrait:grid--cols-1 portrait:gap">
<div class="item col--span-2 portrait:col--span-1">...</div>
</div>Item Component
The
Item
Item
Build standardized list items and content blocks
A row for lists, schedules, and other repeating content, with optional meta text, an index, or an icon. Stack items in a Layout and let the Overflow engine handle the ones that do not fit.
component now gives .icon elements the same flex styling as .content. Items in
Flex
Flex
Arrange elements with flexible layouts and alignment options
Utility classes for Flexbox layouts. Row and column directions with alignment, centering, and stretching modifiers.
row containers automatically stretch to match the tallest sibling, and items in
Grid
Grid
Create grid layouts with predefined column structures
Utility classes for column-based and row-based grids. Set the column count, span cells across columns, and change either at a breakpoint.
containers stretch to fill their cell height.
Gap and Rounded Utilities
Gap
New
Gap
Gap
Set precise spacing between elements with predefined gap values
Utility classes for the space between the children of a flex, grid, or column container. Predefined sizes, arbitrary values, distribution modifiers, and responsive variants.
classes: gap--base (explicit base, useful for responsive reset), gap--auto (distributes space evenly around items), and gap--distribute (first item at start, last at end, space between). Arbitrary gaps now start from gap--[0px] (previously 5px). gap--space-between remains as a legacy alias.
Rounded
New
Rounded
Rounded
Control element rounding with predefined values
Utility classes for corner radius. Predefined sizes, per-corner control, and arbitrary pixel values.
class: rounded--base (explicit base, 10px). Arbitrary values now start from rounded--[0px] (previously 1px).
Rich Text Improvements
The Rich Text Rich Text Display formatted paragraphs with alignment and size variants A container for long-form text: paragraphs, headings, lists, and quotes. The framework styles the children of the content block, so text from a feed renders in the framework font without a class on every tag. component has several improvements:
content--centernow correctly centers text on 4-bit screens.- Rich text content max-width is now size-aware and adjusts automatically per screen size (small: 380px, medium: 640px, large: 780px). In portrait orientation, it uses the full screen width.
- All content size variants support responsive prefixes.
<div class="richtext">
<div class="content content--small lg:content--base">
<p>Small on compact devices, default on large screens</p>
</div>
</div>Responsive Clamp
The
Clamp
Clamp
Manage text overflow with single and multi-line truncation
The Clamp engine truncates text to a specified number of lines using word-based ellipsis. It preserves the original text, measures available width, and re-applies clamping whenever layouts change.
system now supports the lg breakpoint.
<!-- 2 lines on small/medium, 4 on large, 1 in portrait -->
<span class="label"
data-clamp="2"
data-clamp-lg="4"
data-clamp-portrait="1">
Long label text...
</span>
Available attributes: data-clamp, data-clamp-sm, data-clamp-md, data-clamp-lg, data-clamp-portrait, data-clamp-sm-portrait, data-clamp-md-portrait, data-clamp-lg-portrait.
Landscape Orientation Default
landscape: prefixed classes need no class of their own on the screen element. Landscape is the default orientation, so landscape: prefixes activate whenever .screen--portrait is not present. See the
Responsive
Responsive
Adapt styles to the device's size class, orientation, and bit depth using variant prefixes
The Responsive system adapts a layout to the device it renders on. Size-based breakpoints follow the size class each device carries, and Bit-depth variants follow its color capabilities. Combine them to control how your content appears across TRMNL's range of devices.
docs.
Bug Fixes
- Title bar on 4-bit screens: Fixed an issue where the background image could bleed through on 4-bit displays. The title bar now explicitly clears the background image before applying the background color.
- Half horizontal layout height: The layout height inside half horizontal views was incorrectly using quadrant dimensions. It now correctly uses half horizontal dimensions.
- Available height computation: Improved height calculation for elements inside flex column layouts. The engine now sums sibling heights and gaps instead of relying on
getBoundingClientRect(), which can be inaccurate before layout settles.
Internal Changes
The following changes are under-the-hood improvements to how the Framework generates its CSS. They don't introduce new classes or markup patterns, but they make the responsive system more robust and maintainable.
- Responsive mixin system refactored to use a shared
parse-selector-componentshelper, fixing edge cases with nested selectors. - New
with-responsive-parent-child-variantsmixin powers responsive grid column spans and flex child utilities. - New device-specific responsive generators (
responsive-for-bit-depth,responsive-orientation-for-bit-depth) for scoped bit-depth overrides. - Value and rich text device overrides refactored from manual per-class rules to generated loops.
screen--sm,screen--md, andscreen--lgnow apply size-specific CSS variable overrides (previously empty).