How can we help?

Article 6 in the Developer Theming series documenting Liquid template variables for Localist Events theming.

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.title | url_escape }}
<!-- Output: Search%20Term%20%26%20Results -->

<!-- In a search URL -->
<a href="/search?q={{ event.title | 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

Appends a word based on a count value, returning a singular or plural form.

Syntax:

{{ count | pluralize: 'word' }}

Use case: Creating grammatically correct text like “1 attendee” vs. “5 attendees”.

Examples:

<!-- Input: 1 -->
{{ event.attendee_count | pluralize: 'attendee' }}
<!-- Output: 1 attendee -->

<!-- Input: 5 -->
{{ event.attendee_count | pluralize: 'attendee' }}
<!-- Output: 5 attendees -->

<!-- With different singular/plural pairs -->
{{ item_count | pluralize: 'person has registered' }}
<!-- Input: 1 -->
<!-- Output: 1 person has registered -->

<!-- Input: 3 -->
<!-- Output: 3 persons has registered (note: "person" doesn't pluralize with this filter) -->

Note: The pluralize filter appends ‘s’ to the provided word for plural. For irregular plurals (child → children, person → people), use the plural filter instead.

plural

Renders singular or plural text based on a count, providing full control over both forms.

Syntax:

{{ count | plural: 'singular_form, plural_form' }}

Use case: Handling irregular plurals or complex phrases where simple suffixing won’t work.

Examples:

<!-- Input: 1 -->
{{ event.attendee_count | plural: 'attendee, attendees' }}
<!-- Output: attendee -->

<!-- Input: 5 -->
{{ event.attendee_count | plural: 'attendee, attendees' }}
<!-- Output: attendees -->

<!-- Irregular plurals -->
{{ person_count | plural: 'person, people' }}
<!-- Input: 1 -->
<!-- Output: person -->

<!-- Input: 3 -->
<!-- Output: people -->

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.title | trim }}
<!-- Output: "Event Title" -->

<!-- Chained with other filters -->
{{ event.description | trim | simple_format }}

recent_time

Displays recent timestamps in a human-friendly format. Times from “today” show as “Today HH:MM”, while older dates display in standard date format.

Syntax:

{{ variable | recent_time }}

Use case: Showing when events were created, updated, or when registrations occurred.

Examples:

<!-- If created today at 2:30 PM -->
{{ event.created_at | recent_time }}
<!-- Output: Today 14:30 -->

<!-- If created yesterday -->
{{ event.created_at | recent_time }}
<!-- Output: Apr 12, 2026 -->

<!-- If created last week -->
{{ event.created_at | recent_time }}
<!-- Output: Apr 06, 2026 -->

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:

<!-- If event.venue is blank -->
{{ event.venue | default: 'Virtual Event' }}
<!-- Output: Virtual Event -->

<!-- With title that exists -->
{{ event.title | default: 'Untitled Event' }}
<!-- Output: [the actual title] -->

<!-- Chaining defaults -->
{{ event.location | default: event.venue | 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)" -->
{{ site.primary_color | css_color_to_hex }}
<!-- Output: #ff0000 -->

<!-- Input: "rgba(0, 255, 0, 0.5)" -->
{{ site.accent_color | css_color_to_hex }}
<!-- Output: #00ff00 (alpha channel ignored in hex conversion) -->

Standard Liquid Filters

In addition to the custom filters above, Localist templates support all standard Liquid filters. These include:

For the complete list of standard Liquid filters and detailed documentation, refer to the Liquid documentation.

Common Filter Patterns

Date Formatting with Site Configuration

Many themes use site.date_format to apply consistent date styling across templates:

<!-- Define format in site config as: "%B %d, %Y" -->
{{ event.start_time | date: site.date_format }}

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.title | downcase | replace: ' ', '-' | url_escape }}">
  {{ event.title | capitalize }}
</a>

<!-- Graceful fallbacks -->
{{ event.location | trim | default: event.venue | default: 'Location TBA' }}

Conditional Pluralization

Combine pluralization with dynamic content:

<!-- Show attendee count with proper grammar -->
<p>{{ event.attendee_count | plural: 'attendee, attendees' }} registered</p>

<!-- Include count in sentence -->
<p>
  {{ event.attendee_count }}
  {{ event.attendee_count | pluralize: 'person' }}
  registered for this event
</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 an 8-part series on Localist developer theming:

1. Introduction to Localist Developer Theming
2. Site Configuration and Global Objects
3. Events, Instances, and Related Objects
4. Places, Groups, Departments, and Channels
5. Custom Liquid Tags Reference
6. Custom Liquid Filters Reference
7. Template Variable Reference
8. Forms and User Management