Skip to main content

Shared inputs

Shared inputs let you define an input once and reuse the exact same configuration across multiple modules and settings. Instead of copying the same select options, color palette, or validation rules into every module that needs them, you define one source of truth and reference it.

When to use shared inputs​

Use shared inputs when the same input appears in more than one place and should always behave identically. Common examples:

  • a brand color picker with a fixed palette used across many modules
  • a CTA style selector (primary, secondary, ghost) that several modules expose
  • an alignment toggle (left, center, right) used in multiple layouts
  • a category select with a standard list of options
  • any input where the options, defaults, or validations are likely to change over time

If you'd otherwise have to update five modules to add one new color or one new option, the input belongs in Shared.

The Shared setting​

Every template base has a special, pinned Shared setting at the top of its settings panel — right next to Global.

Inputs you add inside the Shared setting are definitions: they describe the type, options, defaults, validations, hint text, and placeholder text, but they don't render anywhere by themselves. They only show up where they are referenced.

TODO: Add a screenshot of the Shared setting expanded with a few defined inputs (e.g. brand color, CTA style, alignment).

Shared Reference inputs​

To use a shared input, add an input of type Shared Reference to any setting (template base or module) and pick which Shared input it points to.

A Shared Reference inherits the source input's structure and behavior:

  • input type
  • options (for selects, color pickers, etc.)
  • default value
  • constraints and validations
  • hint text
  • placeholder text
  • editor controls, such as whether an emoji button appears on text inputs

You can configure these fields on the reference itself:

  • Name — the label shown in this specific setting
  • Key — the key used in Liquid for this specific reference
  • Conditional visibility — when this reference should appear in its local setting
  • Hint text — helper copy for this specific reference
  • Placeholder — example text for this specific reference, available when the shared source input supports placeholders

If you leave hint text or placeholder blank on the reference, Better Email falls back to the values from the Shared definition. That means the same shared input can show up with different local labels and helper copy in different modules without losing its underlying behavior.

<a href="{{ link.url }}" style="background:{{ button.style_color }};">
  {{ button.label }}
</a>

Here, style_color is a Shared Reference pointing to the central brand color picker. If the palette changes in the Shared setting, every module that references it updates automatically.

How shared inputs and Global inputs work together​

Shared inputs and Global inputs solve different problems:

  • Global inputs hold a single value used across the whole email. Marketers set it once on the email itself.
  • Shared inputs are reusable input definitions that each module fills in independently.

Use Global when every module should read the same value. Use Shared when every module should expose the same kind of input, but with its own value.

Best practices​

  • Put any input that appears in more than one place into the Shared setting.
  • Keep names of references readable in their local context — they don't have to match the Shared input's name.
  • Prefer Shared inputs over duplicated select options; it removes drift over time.
  • Use clear keys so referenced values are easy to read in Liquid.
  • If a value should be the same across the entire email, use a Global input instead of a Shared one.