Convert number to ordinal: ordinal

The ordinal template filter converts a number into its ordinal string representation. Give it 1 and it returns 1st, give it 2 and it returns 2nd, give it 3 and it returns 3rd, and so on. It correctly handles the special cases for 11th, 12th, and 13th.

This is useful for creating human-readable messages that include rankings or positions. For example, you might want to display “This is the 3rd time the door opened today” in a notificationYou can use notifications to send messages, pictures, and more, to devices. [Learn more], or show “Floor 2nd” on a dashboard. Anywhere you want a number to read naturally in English text, this filter handles it.

Usage

Here’s how to use this template function. Copy any example and adjust it to your setup.

{{ 1 | ordinal }}

1st

Function signature

The signature is a technical summary of this template function. It shows the name of the function, the values (called parameters) it accepts, and what type of data each parameter expects (for example, a piece of text or a number).

Function parameters that have a = with a value after them are optional. If you leave them out, the default value shown is used automatically. Function parameters without a default are required.

ordinal(
    value: int | str,
) -> str

Function parameters

The following parameters can be provided to this function.

Good to know

• English suffixes only. Other languages are not supported.
• Numbers ending in 11, 12, and 13 get th, not st, nd, or rd.
• The result includes the number and the suffix together, like "21st", not just the suffix.

Try it yourself

Ready to test this? Open Developer tools > Template, paste the example into the Template editor, and watch the result update on the right. Edit the values to see how the function adapts to your own entitiesAn entity represents a sensor, actor, or function in Home Assistant. Entities are used to monitor physical properties or to control other entities. An entity is usually part of a device or a service. [Learn more].

More examples

Real scenarios where this function comes up in automations and templates. Copy any example and adapt it to your setup.

Display a counter with ordinal suffix

Show how many times an event has occurred today using a counter helper, with a natural-sounding ordinal format.

{{
  "This is the " ~ (states("counter.door_opens") | int | ordinal)
  ~ " time the door opened today."
}}

This is the 5th time the door opened today.

Show the day of the month as an ordinal

Display the current date in a friendly format with an ordinal day number.

{{
  "Today is the " ~ (now().day | ordinal)
  ~ " of " ~ now().strftime("%B") ~ "."
}}

Today is the 15th of March.

Handle special cases

The filter correctly handles the special English ordinal cases for 11, 12, and 13.

{{ 11 | ordinal }}, {{ 12 | ordinal }}, {{ 13 | ordinal }},
{{ 21 | ordinal }}, {{ 22 | ordinal }}, {{ 23 | ordinal }}

11th, 12th, 13th, 21st, 22nd, 23rd

Still stuck?

The Home Assistant community is quick to help: join Discord for real-time chat, post on the community forum with your template and expected result, or share on our subreddit /r/homeassistant.

Related template functions

These functions work well alongside this one:

• Convert to slug format: slugify - Converts a string to a slug format with an optional separator character.

• URL-encode a value: urlencode - URL-encodes a dictionary of values for use in HTTP requests.