Nex.Helpers (nex_core v0.4.3)

Common formatting helpers automatically imported into all Nex page and component modules.

These functions are available in any module that uses use Nex — no explicit import needed.

Available Helpers

format_number/1 — Format integers with k/M suffix (e.g. 12345 → "12.3k")
format_date/1 — Format dates/datetimes to human-readable string
time_ago/1 — Relative time string (e.g. "3 days ago")
truncate/3 — Truncate strings with ellipsis
pluralize/3 — Singular/plural based on count
clsx/1 — Build CSS classes from lists
class/2 — Build CSS classes with template support
attrs/1 — Build HTML attributes conditionally

Summary

Types

date_input()

Functions

attrs(attrs)

Builds HTML attributes from a keyword list, filtering out nil/false values.

class(template, values)

Builds CSS classes with template support.

clsx(list)

Builds a CSS class string from a list of values, filtering out falsy entries.

format_date(d)

Formats a date or datetime to a human-readable string.

format_number(n)

Formats a number with k/M suffix for compact display.

pluralize(count, singular, plural)

Returns the singular or plural form of a word based on count.

time_ago(d)

Returns a relative time string from a past datetime.

truncate(str, length, opts \\ [])

Truncates a string to the given length, appending an ellipsis if truncated.

Types

date_input()

@type date_input() :: Date.t() | NaiveDateTime.t() | DateTime.t() | String.t() | nil

Functions

attrs(attrs)

@spec attrs([{atom() | String.t(), term()}]) :: String.t()

Builds HTML attributes from a keyword list, filtering out nil/false values.

Examples

attrs([class: "btn", disabled: false, data_action: "submit"])
# => "class="btn" data-action="submit""

attrs([id: "my-form", required: true])
# => "id="my-form" required"

class(template, values)

@spec class(String.t(), [String.t() | nil | false]) :: String.t()

Builds CSS classes with template support.

Similar to clsx/1 but supports nested templates with the & placeholder.

Examples

class("btn &", ["btn-primary", "btn-large"])
# => "btn-primary btn-large"

class("item active-&1", ["active", "disabled"])
# => "item active-active"

class("btn &-state", ["success", "large"])
# => "btn success-state btn large-state"

clsx(list)

@spec clsx([String.t() | {String.t(), boolean()} | nil | false]) :: String.t()

Builds a CSS class string from a list of values, filtering out falsy entries.

Accepts strings, {class, condition} tuples, and ignores nil/false.

Examples

clsx(["btn", "btn-primary"])                    # => "btn btn-primary"
clsx(["btn", nil, false, "active"])             # => "btn active"
clsx(["btn", {"btn-active", true}, {"hidden", false}])  # => "btn btn-active"
clsx([])                                        # => ""

format_date(d)

@spec format_date(date_input()) :: String.t()

Formats a date or datetime to a human-readable string.

Accepts %Date{}, %NaiveDateTime{}, %DateTime{}, or an ISO 8601 string.

Examples

format_date(~D[2026-02-19])             # => "Feb 19, 2026"
format_date(~N[2026-02-19 10:30:00])    # => "Feb 19, 2026"
format_date("2026-02-19T10:30:00Z")     # => "Feb 19, 2026"
format_date(nil)                         # => ""

format_number(n)

@spec format_number(integer() | float() | nil) :: String.t()

Formats a number with k/M suffix for compact display.

Examples

format_number(500)      # => "500"
format_number(1_200)    # => "1.2k"
format_number(45_000)   # => "45.0k"
format_number(1_500_000) # => "1.5M"

pluralize(count, singular, plural)

@spec pluralize(integer(), String.t(), String.t()) :: String.t()

Returns the singular or plural form of a word based on count.

Examples

pluralize(1, "item", "items")   # => "1 item"
pluralize(5, "item", "items")   # => "5 items"
pluralize(0, "item", "items")   # => "0 items"

time_ago(d)

@spec time_ago(date_input()) :: String.t()

Returns a relative time string from a past datetime.

Examples

time_ago(DateTime.add(DateTime.utc_now(), -30, :second))  # => "just now"
time_ago(DateTime.add(DateTime.utc_now(), -90, :second))  # => "2 minutes ago"
time_ago(DateTime.add(DateTime.utc_now(), -3600 * 5, :second)) # => "5 hours ago"
time_ago(DateTime.add(DateTime.utc_now(), -86400 * 3, :second)) # => "3 days ago"

truncate(str, length, opts \\ [])

@spec truncate(String.t() | nil, pos_integer(), keyword()) :: String.t()

Truncates a string to the given length, appending an ellipsis if truncated.

Options

:omission - String appended when truncated (default: "...")

Examples

truncate("Hello, world!", 8)              # => "Hello..."
truncate("Hello", 10)                     # => "Hello"
truncate("Hello, world!", 8, omission: "…") # => "Hello, …"
truncate(nil, 10)                         # => ""