TRMNL X Guide
TRMNL X is a larger, 4-bit ePaper display. This guide covers everything that changed in the Framework to support it. Your existing plugins will continue to work, but by adopting these new features you can build layouts that take full advantage of 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
The Title system provides consistent text headings with different size variants. It helps maintain visual hierarchy and readability throughout the interface.
(
title--base), Value Value Display data values with consistent formatting The Value system provides consistent text styling for displaying numerical and textual values, with various size options and support for tabular numbers. It ensures readability and visual hierarchy across different contexts. (value--base), Label Label Create clear labels for unified content identification The Label system provides various styles for displaying text labels, with options for different visual treatments and sizes. The filled variant uses black (darkest) background; label--primary, label--success, etc. use semantic colors. Labels can be used to highlight text, show status, or create visual hierarchy in your interface. (label--base), Description Description Format descriptive text with standardized styles The Description component provides a standardized way to display descriptive text content with consistent styling. (description--base) - Rich Text:
Rich Text
Rich Text
Display formatted paragraphs with alignment and size variants
The Rich Text component provides a flexible container for displaying text content with consistent styling and layout options. It's commonly used for paragraphs, articles, and other formatted text content that needs to maintain readability and visual hierarchy.
(
content--base) - Components:
Table
Table
Create data tables optimized for 1-bit rendering
The Table system provides structured data presentation with consistent styling and various size options. It's designed to display information in a clear, scannable format while maintaining visual hierarchy.
(
table--base), Progress Progress Display progress bars in different styles The Progress component provides visual indicators for completion status and step-based processes. Optimized for ePaper displays with bitmap patterns for 1-bit displays and solid colors for 4-bit+ displays. (progress-bar--base,progress-dots--base) - Utilities:
Gap
Gap
Set precise spacing between elements with predefined gap values
The Gap system provides consistent spacing between elements using CSS gap property. It offers predefined sizes, responsive spacing, and custom values to maintain visual rhythm throughout your interface.
(
gap--base), Rounded Rounded Control element rounding with predefined values The Rounded system provides consistent border radius values for creating smooth corners on elements. It offers predefined sizes, corner-specific controls, and custom values to maintain visual consistency throughout your interface. (rounded--base), Text Stroke Text Stroke Legible text when displayed on shaded backgrounds The Text Stroke system allows you to add outlined text with customizable stroke width and color. This is useful for creating text that stands out against shaded backgrounds. (text-stroke--base), Image Stroke Image Stroke Legible images when displayed on shaded backgrounds The Image Stroke system allows you to add an outline to a vector or transparent raster images with customizable stroke width and color. This is useful for creating images that stand out against shaded backgrounds. (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 The Value system provides consistent text styling for displaying numerical and textual values, with various size options and support for tabular numbers. It ensures readability and visual hierarchy across different contexts. 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 The Title system provides consistent text headings with different size variants. It helps maintain visual hierarchy and readability throughout the interface. 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
The Label system provides various styles for displaying text labels, with options for different visual treatments and sizes. The filled variant uses black (darkest) background; label--primary, label--success, etc. use semantic colors. Labels can be used to highlight text, show status, or create visual hierarchy in your interface.
(label--large, label--xlarge, label--xxlarge),
Description
Description
Format descriptive text with standardized styles
The Description component provides a standardized way to display descriptive text content with consistent styling.
(description--large, description--xlarge, description--xxlarge), and
Rich Text
Rich Text
Display formatted paragraphs with alignment and size variants
The Rich Text component provides a flexible container for displaying text content with consistent styling and layout options. It's commonly used for paragraphs, articles, and other formatted text content that needs to maintain readability and visual hierarchy.
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. There should be exactly one layout per view. Its height is calculated automatically based on the device type, orientation, and whether a title bar is present. It can arrange content horizontally (layout--row) or vertically (layout--col), with alignment and stretch modifiers. For organizing content inside it, use flex, columns, or grid.
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
The Size system provides utility classes for controlling width and height dimensions. It includes both fixed sizes and responsive utilities to handle various layout needs.
docs for full details.
Responsive Arbitrary Sizes
The w--[Npx] and h--[Npx] utilities now support responsive prefixes. Previously, these were static-only. The maximum value has been reduced from 1000px to 800px. See the
Size
Size
Define exact width and height dimensions for elements
The Size system provides utility classes for controlling width and height dimensions. It includes both fixed sizes and responsive utilities to handle various layout needs.
docs.
<!-- Responsive arbitrary sizes -->
<div class="w--[150px] md:w--[250px] lg:w--[400px]">Responsive arbitrary width</div>
<div class="h--[100px] portrait:h--[200px]">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. There should be exactly one layout per view. Its height is calculated automatically based on the device type, orientation, and whether a title bar is present. It can arrange content horizontally (layout--row) or vertically (layout--col), with alignment and stretch modifiers. For organizing content inside it, use flex, columns, or grid.
direction. In layout--row, stretch-x grows along the horizontal axis and stretch-y stretches vertically. 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
The Grid system provides a flexible way to create both column-based and row-based layouts. It supports various column counts, column spans, and responsive behaviors to create complex layouts easily.
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
The Item component provides a flexible container for displaying content with optional metadata and indexing. It's commonly used for lists, schedules, and other content that needs consistent formatting.
component now gives .icon elements the same flex styling as .content. Items in
Flex
Flex
Arrange elements with flexible layouts and alignment options
The Flex system provides utility classes for creating flexible layouts using Flexbox. It supports both row and column directions with various alignment, centering, and stretching options.
row containers automatically stretch to match the tallest sibling, and items in
Grid
Grid
Create grid layouts with predefined column structures
The Grid system provides a flexible way to create both column-based and row-based layouts. It supports various column counts, column spans, and responsive behaviors to create complex layouts easily.
containers stretch to fill their cell height.
Gap and Rounded Utilities
Gap
New
Gap
Gap
Set precise spacing between elements with predefined gap values
The Gap system provides consistent spacing between elements using CSS gap property. It offers predefined sizes, responsive spacing, and custom values to maintain visual rhythm throughout your interface.
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
The Rounded system provides consistent border radius values for creating smooth corners on elements. It offers predefined sizes, corner-specific controls, and custom values to maintain visual consistency throughout your interface.
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 The Rich Text component provides a flexible container for displaying text content with consistent styling and layout options. It's commonly used for paragraphs, articles, and other formatted text content that needs to maintain readability and visual hierarchy. 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 now work correctly even without an explicit .screen--landscape class on the screen element. Since landscape is the default orientation, landscape: prefixes activate whenever .screen--portrait is not present. See the
Responsive
Responsive
Adapt styles based on screen width using breakpoint prefixes
The Responsive system provides two complementary approaches for creating adaptive layouts: Size-based breakpoints that respond to screen dimensions, and Bit-depth variants that adapt to color capabilities. Together, they enable precise control over how your content appears across TRMNL's diverse 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).