Replace using a regex pattern: regex_replace

The regex_replace template filter replaces all occurrences of a regular expression (regex) pattern in a string with a replacement value. A regular expression is a special text pattern that describes what you are looking for; regex_replace finds every part of the string that matches and swaps it out. This works like a find-and-replace tool, but with the power of patterns instead of fixed text.

This is useful when you need to clean up or transform text from sensorsSensors return information about a thing, for instance the level of water in a tank. [Learn more] and other sources. For example, you might want to strip unwanted characters from a sensor value, reformat a phone number, remove units from a measurement string so you can convert it to a number, or clean up device names for display on a dashboard.

Usage

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

{{ "Hello 123 World 456" | regex_replace("\\d+", "N") }}

Hello N World N

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.

regex_replace(
    value: str,
    find: str = "",
    replace: str = "",
    ignorecase: bool = False,
) -> str

Function parameters

The following parameters can be provided to this function.

Removing matched text

Pass an empty string as the replacement to remove all matches from the string.

{{ "Temperature: 23.5 C" | regex_replace("[^0-9.]", "") }}

23.5

Case-insensitive replacement

Set ignorecase to true to match and replace regardless of upper or lowercase letters.

{{
  "Error: DEVICE offline"
  | regex_replace("error", "Warning", ignorecase=true)
}}

Warning: DEVICE offline

Good to know

• Replaces every occurrence, not just the first one.
• Backreferences in the replacement use \1, \2, and so on, to refer to capturing groups from the pattern.
• Passing an empty replacement deletes every match from the string.

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.

Strip units from a sensor value

Remove non-numeric characters from a sensor state so you can use it as a number.

{{ states("sensor.wind_speed") | regex_replace("[^0-9.]", "") | float }}

15.3

Clean up a device name for display

Remove unwanted prefixes or suffixes from a device name.

{{
  "MQTT - Living Room Sensor [v2]"
  | regex_replace("^MQTT - ", "")
  | regex_replace("\\s*\\[.*\\]$", "")
}}

Living Room Sensor

Mask sensitive information

Replace digits in a phone number or account number for display purposes.

{{ "+1-555-123-4567" | regex_replace("\\d(?=\\d{4})", "*") }}

+*-***-***-4567

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:

• Match a regex pattern: regex_match - Tests if a string matches a regular expression pattern at the beginning.

• Search for a regex pattern: regex_search - Searches for a regular expression pattern anywhere in a string.

• Find all regex matches: regex_findall - Finds all occurrences of a regular expression pattern in a string and returns them as a list.

• Find regex match at index: regex_findall_index - Finds all occurrences of a regex pattern and returns the match at a specific index.