Skip to content

Lucit Text Auto-Fit Guide for Dynamic Macro Text

This guide explains how Lucit auto-fit text works when a text field value is supplied by macros that can produce variable-length content.

Why Auto-Fit Is Needed

Macro-driven text fields (for example, {item.title}) may produce unknown character lengths at render time.

Because of this, a designer may want Lucit to automatically grow and constrain text so it fills its containing div without overflowing.

In the UI, this behavior is enabled by setting Font Size to Auto, then optionally configuring:

  • Max Size
  • Max Chars
  • Wrap Text

Depending on these settings, Lucit resizes text to best fit the container.

Core Trigger

Any element that should run fit-text logic must include:

  • class: lc_format_fit_text

Example:

<div class="lc_ut_designer lc_dt_data lc_dt_text lc_format_fit_text">{item.title}</div>

Fit-text processing typically runs after other text-formatting functions have already run on the element.

Template Markup Examples

1) Simple Auto-Fit (No Max Size, No Max Chars)

<div id="data_source_text_6h4v1zis" title="" x-objectcode="item_title" class="lc_ut_designer lc_dt_data lc_dt_text lc_format_fit_text" x-placeholder="Your Caption" x-optional-field="false" x-fieldname="Title" data-value="{item.title}" x-element-settings="{}" x-element-setting-values="{}">{item.title}</div>

2) Auto-Fit with Max Size and Max Chars

<div id="data_source_text_6h4v1zis" title="" x-objectcode="item_title" class="lc_ut_designer lc_dt_data lc_dt_text lc_format_fit_text" x-placeholder="Your Caption" x-optional-field="false" x-fieldname="Title" data-value="{item.title}" x-element-settings="{}" x-element-setting-values="{}" data-max-font-size="5.25" data-max-chars="25">{item.title}</div>

3) Auto-Fit with Ellipsis when Max Chars Is Exceeded

<div id="data_source_text_6h4v1zis" title="" x-objectcode="item_title" class="lc_ut_designer lc_dt_data lc_dt_text lc_format_fit_text" x-placeholder="Your Caption" x-optional-field="false" x-fieldname="Title" data-value="{item.title}" x-element-settings="{}" x-element-setting-values="{}" data-max-font-size="5.25" data-max-chars="25" data-max-chars-show-ellipsis="true">{item.title}</div>

4) Auto-Fit with Wrap Text Enabled

<div id="data_source_text_6h4v1zis" title="" x-objectcode="item_title" class="lc_ut_designer lc_dt_data lc_dt_text lc_format_fit_text" x-placeholder="Your Caption" x-optional-field="false" x-fieldname="Title" data-value="{item.title}" x-element-settings="{}" x-element-setting-values="{}" data-max-font-size="5.25" data-max-chars="25" data-max-chars-show-ellipsis="true">{item.title}</div>

Units

Auto-fit max font sizing uses vmax units.

Runtime Behavior (Current Function)

The current fit-text function (non-legacy path) follows this flow:

  1. Skip the element unless it has class lc_format_fit_text.
  2. Read data-max-font-size.
  3. If no data-max-font-size is present, fall back to the legacy algorithm.
  4. Otherwise, set font size to 0vmax.
  5. Record baseline scrollHeight and scrollWidth.
  6. Increase font size in 0.25vmax steps.
  7. Stop when one of these conditions is hit:
  8. Height grows past baseline,
  9. Width grows past baseline,
  10. Size reaches configured max,
  11. Loop reaches safety limit.
  12. Step back by 2 * 0.25vmax for buffer space.
  13. Save iteration count in data-fit-text-iterations.

Conflicting CSS Styles to avoid

This restriction applies specifically to dynamic macro text elements — elements that have both the lc_dt_data class and a macro as their text value (e.g. {item.title}). On those elements, the CSS styles listed below should be avoided when lc_format_fit_text is also set, because they produce unpredictable results with the fit-text algorithm.

The function calculates the font size by first setting the element's font size to 0vmax, measuring the element's initial scrollHeight and scrollWidth, then gradually increasing the font size in 0.25vmax steps until the text grows beyond the original measured space or reaches the configured max font size. It then backs off slightly to avoid clipping. Any style that alters how the browser reports scroll dimensions or constrains layout — before or during that loop — will corrupt the result.

If necessary, write a custom formatting function to handle your use case.

Styles to Avoid 

white-space: pre;
white-space: pre-line;
white-space: pre-wrap;
white-space: nowrap;

display: inline;
display: contents;

overflow: hidden;

width: auto;
height: auto;

text-overflow: ellipsis;

min-width: max-content;
min-height: max-content;

-webkit-text-stroke: 4px ...;

Notes for Template Authors

  • Use lc_format_fit_text on any element that should auto-fit.
  • ALWAYS set data-max-font-size to enable the current vmax algorithm.
  • If data-max-font-size is omitted, behavior falls back to legacy fit logic and may be un-predictable.
  • Combine data-max-chars and data-max-chars-show-ellipsis when you need strict character limits for unpredictable macro output.