Lucit Template Element Settings Guide

Overview

Element settings let template users configure an individual element without editing JavaScript. Use them for reusable elements whose content, appearance, or behavior depends on user input, such as a launch date, a payment calculator, or a configurable label.

Define the inputs in the element's x-element-settings HTML attribute. Users right-click the element on the canvas and choose Edit Settings to configure its values. The ADVANCED tab lets developers edit the raw x-element-settings JSON.

The selected values are stored in x-element-setting-values. During rendering, Lucit passes those values to a registerDesignerFormattingFunction callback as its fourth argument, elementSettings.

Definitions and selected values

Element settings use two separate HTML attributes:

Attribute	Purpose	Structure
x-element-settings	Defines the inputs shown in the settings dialog.	A JSON object containing a fields array.
x-element-setting-values	Stores the values selected for this element.	A JSON object whose property names match field key values.

For example, the setting definition is:

{
  "fields": [
    {
      "key": "target_date_iso",
      "name": "Target Date (ISO)",
      "type": "text",
      "placeholder": "2026-10-09T00:00:00"
    }
  ]
}

The selected values are a separate object, not another fields array:

{
  "target_date_iso": "2026-10-09T00:00:00"
}

Field definitions

The fields array uses Lucit's shared form field configuration format. See the Lucit Form Fields Specification for the complete fields array structure, field object schema, supported types, validation rules, dropdown options, and conditional display settings.

The most common properties are:

Property	Purpose
key	Unique setting identifier; use this exact name when reading elementSettings.
name	Label shown in the settings dialog. Required for input fields.
type	Input type, such as text, int, float, bool, or color.
description	Help text explaining what the user should enter.
placeholder	Hint shown for an empty input, supported by certain field types. Designer formatting functions can also receive this as a fallback when no value is configured.
default_value	Default value in the form configuration; its type must match the field type.
required	Whether a value must be supplied before submitting the form.

Do not assume that a placeholder has been explicitly saved in x-element-setting-values. Validate the values received by your callback even when the form defines placeholders or defaults.

Element settings configure an element on the template canvas. If you instead need users to enter information when posting an ad, see Lucit Template Custom Fields.

Configure settings in the Template Designer

1. Add or select an element on the template canvas.
2. Right-click the element and choose Edit Settings.
3. Open the ADVANCED tab and edit the x-element-settings JSON. Paste the JSON object containing fields, not an HTML attribute declaration.
4. Save the definitions, then configure the actual input values in the same settings dialog. Reopen the dialog if needed.
5. Save the selected values.
6. Inspect the element's HTML to confirm that x-element-setting-values contains the expected keys and values. Right-click the element and choose Edit CSS / HTML to inspect its code.
7. Add a designer formatting function in the JS tab of the template's global Code Editor: Templates → {Template} → Canvas → Actions Bar → <>.

You can also define both attributes directly in the element's HTML, as shown below. Keep the field definitions and selected values in sync when editing code manually.

End-to-end example: configurable launch date

This example displays a configured launch date as MM / DD / YY. It uses a text field so the user can enter an ISO-style date/time string directly.

1. Define the element and its setting

<div
  id="obj_launch_date_text"
  title="Launch Date"
  x-objectcode="your_new_text"
  class="lc_ut_designer lc_dt_element lc_dt_text lc_dt_text_editable lc_format_fit_text"
  x-fieldname="your_new_text"
  x-optional-field="false"
  x-element-settings='{"fields":[{"key":"target_date_iso","name":"Target Date (ISO)","type":"text","description":"Enter a date/time such as 2026-10-09T00:00:00.","placeholder":"2026-10-09T00:00:00"}]}'
  x-element-setting-values='{"target_date_iso":"2026-10-09T00:00:00"}'>
  10 / 09 / 26
</div>

Both attributes contain valid JSON. The example uses single quotes around HTML attribute values so the JSON can retain its required double quotes. If a JSON string contains an apostrophe, encode it as ' when embedding it in a single-quoted HTML attribute. Encode literal ampersands as & as well.

The element's initial text remains visible until the formatting function replaces it.

2. Read the setting in JavaScript

Add this registration to the template's JS tab:

registerDesignerFormattingFunction(
  "format_obj_launch_date_text",
  (el, dataValue, dataObject, elementSettings) => {
    const value = elementSettings?.target_date_iso;
    const raw = typeof value === "string" ? value.trim() : "";

    if (!raw) {
      return;
    }

    const parsed = new Date(raw);

    if (Number.isNaN(parsed.getTime())) {
      return;
    }

    const month = String(parsed.getMonth() + 1).padStart(2, "0");
    const day = String(parsed.getDate()).padStart(2, "0");
    const year = String(parsed.getFullYear() % 100).padStart(2, "0");

    el.textContent = month + " / " + day + " / " + year;
  },
  '[id="obj_launch_date_text"]'
);

Lucit calls the function for the element matching the selector and supplies its settings as elementSettings. The function does not use dataValue or dataObject, but retains those argument positions so it can access the fourth argument.

Missing, non-string, or unparseable values leave the initial text unchanged. Using textContent treats the output as text rather than HTML.

Date and timezone behavior

A date/time such as 2026-10-09T00:00:00 has no timezone offset and is interpreted in the renderer's local timezone. This example also uses local date getters. If you need to represent a specific instant, include Z or an explicit offset and choose the intended display timezone; displaying that instant in another timezone can change the calendar date. JavaScript date parsing is not strict calendar validation, so validate allowed formats and date ranges separately when needed.

See the Lucit Designer Formatting Functions Guide for the full callback contract and examples that combine element settings with dynamic data.

Common mistakes and fixes

Problem	Fix
Invalid JSON	Use double quotes for JSON keys and strings; remove comments and trailing commas. Escape JSON correctly when embedding it in HTML.
Definitions confused with values	Put the fields array in x-element-settings and the selected key/value pairs in x-element-setting-values.
Key mismatch	Read the exact field key, such as elementSettings.target_date_iso, not its display name.
Missing or unexpected value type	Check values before using string or numeric methods. Use ?? rather than || for fallbacks when 0 or false are valid values.
Wrong function type	Use registerDesignerFormattingFunction to operate on the matching element's content or styles.
Selector does not match	Make sure the registered selector matches the intended element's ID, class, or attribute.
Date appears on the wrong day	Check whether the input includes a timezone and whether the formatter uses local or UTC date getters.

Validation checklist

Before publishing a template:

1. Confirm that both settings attributes contain valid JSON.
2. Check the fields array against the Lucit Form Fields Specification.
3. Confirm that selected-value keys match the intended input fields.
4. Read values defensively in JavaScript and handle missing or invalid input.
5. Verify that the registered selector matches the intended element.
6. Change the setting in Edit Settings and preview the result. Test both configured values and fallback behavior.
7. If using the Lucit CLI, run lucit template validate <template-name> and resolve any reported errors. Validation does not replace checking the rendered result.

Related guides

• Lucit Form Fields Specification
• Lucit Template HTML Guide
• Lucit Template JavaScript Guide
• Lucit Designer Formatting Functions Guide
• Lucit Template Custom Fields
• Template Designer General Navigation Guide