Article 7 in the Developer Theming series documenting Liquid template variables for Localist Events theming.
Localist themes use Liquid 5.12.0.
Overview
Filters are transformations applied to variable output using the pipe operator (|). They modify the data before it renders in the template.
Basic Syntax
A filter is applied after a variable name, separated by a pipe:
{{ variable | filter }}
Some filters accept arguments:
{{ variable | filter: argument }}
Filters can be chained together, with each filter processing the output of the previous one:
{{ variable | filter1 | filter2 | filter3 }}
Filter Categories
Localist Events provides custom filters in addition to Liquid’s standard filters. Custom filters are built specifically to handle common Localist data transformations (dates, numbers, currency, text formatting).
Custom Localist Filters
isodate
Converts a date value to ISO8601 format (YYYY-MM-DDTHH:MM:SSZ).
Syntax:
{{ variable | isodate }}
Use case: Machine-readable date formats for APIs, data attributes, or JSON.
Example:
<!-- Input: 2026-04-13 14:30:00 -->
{{ event.start_time | isodate }}
<!-- Output: 2026-04-13T14:30:00Z -->
date
Formats a date using a custom format string. The format string uses standard Ruby strftime conventions.
Syntax:
{{ variable | date: format }}
Common format patterns:
-
%Y— 4-digit year -
%m— 2-digit month (01-12) -
%d— 2-digit day -
%B— Full month name (January, February, etc.) -
%b— Abbreviated month name (Jan, Feb, etc.) -
%A— Full day name (Monday, Tuesday, etc.) -
%H— 2-digit hour (00-23) -
%M— 2-digit minute -
%S— 2-digit second
Examples:
<!-- Long date format -->
{{ event.start_time | date: "%B %d, %Y" }}
<!-- Output: April 13, 2026 -->
<!-- Date and time -->
{{ event.start_time | date: "%m/%d/%Y at %I:%M %p" }}
<!-- Output: 04/13/2026 at 02:30 PM -->
<!-- ISO-like format -->
{{ event.start_time | date: "%Y-%m-%d" }}
<!-- Output: 2026-04-13 -->
simple_format
Converts plain text to HTML paragraphs, wrapping content in <p> tags. By default, this filter also converts URLs to clickable links.
Syntax:
{{ variable | simple_format }}
With linking disabled:
{{ variable | simple_format: false }}
Use case: Rendering user-provided text (descriptions, bios, notes) while preserving paragraph structure and converting URLs to links.
Example:
<!-- Input text with newlines and URL -->
Description: "Join us for an event.
Visit https://example.com for details."
{{ event.description | simple_format }}
<!-- Output: -->
<!-- <p>Join us for an event.</p>
<p>Visit <a href="https://example.com">https://example.com</a> for details.</p> -->
<!-- Without automatic linking -->
{{ event.description | simple_format: false }}
<!-- Output: -->
<!-- <p>Join us for an event.</p>
<p>Visit https://example.com for details.</p> -->
url_escape
URL-encodes a string, converting special characters to percent-encoded format (%XX).
Syntax:
{{ variable | url_escape }}
Use case: Preparing strings for use in URLs, query parameters, or API endpoints.
Example:
<!-- Input: "Search Term & Results" -->
{{ event.name | url_escape }}
<!-- Output: Search%20Term%20%26%20Results -->
<!-- In a search URL -->
<a href="/search?q={{ event.name | url_escape }}">View Results</a>
<!-- Output: <a href="/search?q=Search%20Term%20%26%20Results">View Results</a> -->
format_number
Formats a number with thousands delimiters (commas by default). Optionally specifies decimal precision.
Syntax:
{{ variable | format_number }}
With decimal precision:
{{ variable | format_number: precision }}
Examples:
<!-- Input: 1500 -->
{{ event.capacity | format_number }}
<!-- Output: 1,500 -->
<!-- Input: 1234567 -->
{{ attendee.total_events | format_number }}
<!-- Output: 1,234,567 -->
<!-- With decimals (2 decimal places) -->
{{ price | format_number: 2 }}
<!-- Input: 19.5 -->
<!-- Output: 19.50 -->
humanize
Converts underscored or dashed strings into human-readable text by:
-
Replacing underscores/dashes with spaces
-
Capitalizing the first letter
Syntax:
{{ variable | humanize }}
Use case: Displaying technical field names or slugs as readable labels.
Example:
<!-- Input: "event_registration_status" -->
{{ field_name | humanize }}
<!-- Output: Event registration status -->
<!-- Input: "attendee-status-pending" -->
{{ status_slug | humanize }}
<!-- Output: Attendee status pending -->
<!-- In form labels -->
<label>{{ "start_time" | humanize }}</label>
<!-- Output: <label>Start time</label> -->
pluralize
Given a count on the left and a singular word, outputs a full phrase (for example 1 attendee or 5 attendees).
Syntax:
{{ count | pluralize: 'word' }}
Use case: Creating grammatically correct text like “1 attendee” vs. “5 attendees”.
Examples:
{{ event.attendee_count | pluralize: 'attendee' }}
<!-- e.g. "1 attendee" or "5 attendees" -->
For irregular plurals or a custom plural word, use the plural filter below.
plural
Returns the singular or plural label word for a count. Put the singular word on the left of the pipe; pass the integer count as the argument. An optional second argument sets the plural form when it should differ from the default.
Syntax:
{{ 'attendee' | plural: event.attendee_count }}
{{ 'person' | plural: people_count, 'people' }}
Examples:
{{ 'photo' | plural: num_photos }}
{{ 'friend' | plural: the_user.num_people_friends }}
trim
Removes leading and trailing whitespace from a string.
Syntax:
{{ variable | trim }}
Use case: Cleaning up user input or variable content that may have extra spaces.
Example:
<!-- Input: " Event Title " -->
{{ event.name | trim }}
<!-- Output: "Event Title" -->
<!-- Chained with other filters -->
{{ event.description | trim | simple_format }}
recent_time
For times on the current day, uses the long time format. For other days, uses the localized past-date list format.
Syntax:
{{ variable | recent_time }}
Use case: Showing when events were created, updated, or when registrations occurred.
Examples:
{{ event.created_at | recent_time }}
default
Provides a fallback value when the input is blank, nil, or false.
Syntax:
{{ variable | default: 'fallback_value' }}
Use case: Ensuring a meaningful value displays when optional fields are empty.
Examples:
{{ event.location | default: 'Virtual Event' }}
{{ event.name | default: 'Untitled Event' }}
{{ event.location | default: 'TBA' }}
format_currency
Converts a number (typically in cents) to a currency string with symbol and decimal places.
Syntax:
{{ variable | format_currency }}
With specific currency code:
{{ variable | format_currency: 'currency_code' }}
Supported currency codes: ‘usd’ (default), ‘eur’, ‘gbp’, ‘cad’, ‘aud’, and others following ISO 4217 codes.
Examples:
<!-- Input: 1500 (cents) -->
{{ ticket.price | format_currency }}
<!-- Output: $15.00 -->
<!-- EUR currency -->
{{ ticket.price | format_currency: 'eur' }}
<!-- Output: €15.00 -->
<!-- GBP currency -->
{{ ticket.price | format_currency: 'gbp' }}
<!-- Output: £15.00 -->
css_color_to_hex
Converts CSS color formats (rgb or rgba) to hexadecimal notation.
Syntax:
{{ variable | css_color_to_hex }}
Use case: Converting dynamic color values from the site configuration to hex format for use in different contexts (SVG fill attributes, legacy systems, etc.).
Examples:
<!-- Input: "rgb(255, 0, 0)" — e.g. from theme-driven CSS color strings -->
{{ site.header_background_color | css_color_to_hex }}
<!-- Output: #ff0000 -->
<!-- Input: "rgba(0, 255, 0, 0.5)" -->
{{ site.header_foreground_color | css_color_to_hex }}
<!-- Output: #00ff00 -->
Standard Liquid Filters
Together with the custom filters above, templates can use the standard Liquid 5.12 filters for strings, arrays, math, and date (paired with Localist’s date behavior and site.format where documented).
Common filters:
| Filter | Purpose |
|---|---|
append |
Add a string to the end of a value |
capitalize |
Capitalize the first letter |
downcase / upcase |
Case conversion |
replace / replace_first |
Replace substrings |
split / join |
String ↔ array |
first / last |
Array ends |
size |
Length of string or array |
sort / reverse |
Array ordering |
map |
Pluck a property from each array element |
plus / minus / times / divided_by / modulo |
Math |
See the Liquid documentation for the full filter list.
Common Filter Patterns
Date Formatting with Site Configuration
Use patterns from site.format (see Article 2) with the date filter:
{{ event.start_time | date: site.format.date_long }}
{{ event.start_date | date: site.format.date_time_detailed }}
Currency Display
Convert prices and fees consistently:
<!-- Display price with currency -->
<span class="price">{{ ticket.price | format_currency }}</span>
<!-- In a different currency -->
<span class="price">{{ ticket.price_in_eur | format_currency: 'eur' }}</span>
Text Transformation Chains
Combine multiple filters for complex transformations:
<!-- Sanitize and format user input -->
{{ form.notes | trim | simple_format }}
<!-- Build safe URLs from titles -->
<a href="/search?q={{ event.name | downcase | replace: ' ', '-' | url_escape }}">
{{ event.name | capitalize }}
</a>
<!-- Graceful fallbacks -->
{{ event.location | trim | default: 'Location TBA' }}
Conditional Pluralization
Combine pluralization with dynamic content:
<p>
{{ event.attendee_count }}
{{ event.attendee_count | pluralize: 'person' }}
registered for this event
</p>
<p>Tags: {{ 'photo' | plural: num_photos }}</p>
Recent Activity Formatting
Display timestamps in user-friendly format:
<!-- Show when event was last updated -->
Last updated: {{ event.updated_at | recent_time }}
<!-- Created timestamp -->
Posted {{ event.created_at | recent_time }}
Related Articles
This article is part of a 9-part series on Localist developer theming:
-
Introduction to Localist Developer Theming
-
Site Configuration and Global Objects
-
Events, Instances, and Related Objects
-
Places, Groups, Departments, and Channels
-
Shared Object Types
-
Custom Liquid Tags Reference
-
Custom Liquid Filters Reference
-
Template Variable Reference
-
Forms and User Management