Remap a value between ranges: remap

The remap template function maps a value from one numeric range to another. Give it a value and its original range, plus the target range, and it returns the proportionally mapped result. For example, a value of 50 in the range 0-100 maps to 127.5 in the range 0-255.

This is useful whenever you need to convert a sensorSensors return information about a thing, for instance the level of water in a tank. [Learn more] reading from one scale to another. For example, you might remap a 0-100% brightness value to the 0-255 range a light expects, convert a temperature from one unit range to another, or map a 0-1023 analog sensor reading to a meaningful percentage. The optional steps and edges parameters give you fine-grained control over quantization and out-of-bounds behavior.

Usage

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

{{ remap(50, 0, 100, 0, 255) }}

127.5

{{ 50 | remap(0, 100, 0, 255) }}

127.5

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.

remap(
    value: Any,
    in_min: Any,
    in_max: Any,
    out_min: Any,
    out_max: Any,
    *,
    steps: int = 0,
    edges: str = "none",
) -> float

Function parameters

The following parameters can be provided to this function.

Edge handling options

The edges parameter determines what happens when the input value falls outside the input range.

• none (default): Values outside the input range are extrapolated linearly. A value of 120 in a 0-100 input range maps proportionally beyond the output range.
• clamp: Values are constrained to the input range boundaries before mapping. A value of 120 in a 0-100 input range is treated as 100.
• wrap: Values wrap cyclically. A value of 120 in a 0-100 input range wraps to 20 before mapping.
• mirror: Values reflect back into the range. A value of 120 in a 0-100 input range mirrors to 80 before mapping.

{{ remap(120, 0, 100, 0, 255, edges="clamp") }}

255.0

Using steps for quantized output

The steps parameter divides the output into discrete intervals. This is useful when you need the result to snap to specific levels rather than being a continuous value.

{{ remap(33, 0, 100, 0, 255, steps=4) }}

63.75

Good to know

• By default, out-of-range inputs are extrapolated beyond the output range. Pass edges="clamp" to limit the result to the output range.
• The output ranges can go in reverse, which produces an inverted mapping.
• With steps, the output is quantized to discrete intervals, which is useful for dimmer steps or discrete sensor levels.

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.

Remapping a sensor percentage to brightness

Convert a 0-100% sensor value to the 0-255 brightness range a light expects.

{{
  remap(
    states("sensor.ambient_light_pct") | float,
    0, 100, 0, 255
  )
}}

127.5

Remapping with wrap edge handling

Wrap out-of-range values cyclically. This keeps the output cycling smoothly.

{{ remap(450, 0, 360, 0, 100, edges="wrap") }}

25.0

Remapping with mirror edge handling

Mirror out-of-range values back into the range for a ping-pong effect.

{{ remap(120, 0, 100, 0, 255, edges="mirror") }}

204.0

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:

• Clamp (constrain) a value: clamp - Constrains a value between a minimum and maximum bound.

• Wrap a value cyclically: wrap - Wraps a value cyclically within a range.