Custom Twig Filters Reference API

SitePack registers a small set of custom filters inside the Twig environment to streamline asset URLs and sanitize link behavior. Colour math lives in the Functions Guide (calculate_brightness, calculate_text_color), though CSS color-mix() is usually the better tool — see below.

Twig filters are applied directly to variables using the pipe character (|). They can be chained together or parameterized to yield precise layouts.

---

Filters Reference Directory

asset_url

An alias for the theme_asset() function (see the Functions Guide). Turns a relative path inside your theme's /assets directory into a fully qualified, CDN-served URL.

• Signature: string | asset_url
• Example Usage:

  <link rel="stylesheet" href="{{ 'css/theme.css' | asset_url }}">
  <img src="{{ 'img/icons/bag.svg' | asset_url }}" alt="Shopping Bag">

ensure_link

Validates and normalizes an arbitrary path string (typically merchant-entered, e.g. a custom banner link or CTA URL) so it always resolves to a working link.

• Behavior:
  • An empty or null value becomes /.
  • Values starting with /, http, #, mailto:, or tel: pass through unchanged.
  • Anything else gets a leading / prepended (e.g., 'contact-us' becomes /contact-us).
• Signature: string | ensure_link
• Example Usage:

  <a href="{{ page['hero-cta-url'] | ensure_link }}" class="btn-primary btn-lg">
    Shop Collection
  </a>

sitepack_html

Safely renders a trusted rich-text HTML field — a product description, a product short description, a blog post body — that a merchant authored in the editor. It sanitizes the HTML against an allowlist (formatting, headings, lists, tables, links and images are kept; <script>, <iframe>, on* handlers and javascript: URLs are stripped) and then marks it safe to print.

• Signature: string | sitepack_html
• Use it instead of raw. The generic raw filter is not available in the theme sandbox (see the note under Core Twig filters); sitepack_html is the safe replacement for printing rich HTML fields. For plain text you never need it — ordinary {{ ... }} output is already escaped.
• Example Usage:

  <div class="product-description">
    {{ product.description | sitepack_html }}
  </div>
  
  <div class="hub-prose">
    {{ article.content | sitepack_html }}
  </div>

---

Translating Strings: the trans Filter

To render translated copy, use the trans filter documented in full in the Translations Guide:

{{ 'general.welcome' | trans({'%site_name%': site.name}) }}

This is Symfony's standard translation filter running against your theme's translations/*.json dictionaries — note that its parameter placeholders use the %percent-sign% style, not Twig's own {{ double-curly }} interpolation.

---

Combining Filters and Functions

Filters chain naturally and combine with the color functions from the Functions Guide to build small dynamic stylesheet snippets:

<style>
  :root {
    {# Calculate a darker hover shade from a merchant-picked colour #}
    --accent-hover: {{ calculate_brightness(page['accent-color'] | default('#ff5500'), -15) }};
  }
</style>

Prefer deriving shades in plain CSS where you can — color-mix() and filter: brightness() stay bound to the merchant's live setting, whereas a Twig-computed value is baked in at render time:

.btn:hover        { filter: brightness(92%); }
.card             { border: 1px solid color-mix(in srgb, var(--text-color) 15%, transparent); }

---

Core Twig filters you may use

Custom filters are only part of the picture: theme templates run in a sandbox, and any core Twig filter not on its allow-list is rejected. These are permitted:

abs            capitalize     date           default        escape         first
join           json_encode    keys           last           length         lower
merge          nl2br          number_format  replace        reverse        round
slice          sort           striptags      title          trim           upper
url_encode     format

Anything absent from that list and from the custom filters above is rejected when you sync the theme. That includes filters you may know from Twig elsewhere, such as split, map, reduce, batch, column and spaceless.

raw is not available

The generic raw filter is deliberately not in the sandbox — it is the classic way to introduce cross-site scripting from a template. To output a trusted rich-text HTML field (a product or blog description) use the sitepack_html filter, which sanitizes the HTML for you; to emit structured data use sitepack_json_ld(). Both are safe by construction.

A few common needs are handled by a function or a filter chain rather than a single core filter:

To do this	Use
Render a product or article image	{{ article.image }} — image fields arrive fully qualified and ready to use.
Shorten copy to an excerpt	{{ article.content|striptags|slice(0, 200) }}
Output a trusted rich-text HTML field	{{ product.description | sitepack_html }} — sanitizes and prints merchant HTML (see above).
Emit structured data (JSON-LD)	{{ sitepack_json_ld(event.json_ld) }} — a safe <script type="application/ld+json"> block, e.g. the Event object from sitepack_events().

---

Exploring Further:

Now that you have configured functions and filters, learn how to build extensibility zones for app integrations in the Template Hooks & App Blocks Guide!