Shuffle

The shuffle function provides an easy way to randomly shuffle any list of items. Either fully random, or with a seed to make the randomization reproducable.

shuffle(
    items: list[Any],
    seed: [None, int, float, str] = None
) -> list[Any]

The items parameter can be a list of anything. The items in the list will be randomly shuffled and returned.

Examples¶

Using shuffle as a function¶

1
{{ shuffle([1, 2, 3]) }}

Returns:

[2, 3, 1]

Calling the function above multiple times will always return the list in a different random order.

Using shuffle as a filter¶

1
{{ [1, 2, 3] | shuffle }}

Returns:

[3, 2, 1]

Using a seed¶

A seed can be used to initialize the random number generator. The same seed will always result in the same randomization, like a randomization with a memory. This is useful if you want to have more reproducable control over the randomization.

Example:

1
{{ shuffle([1, 2, 3], seed=1) }}

Returns:

[2, 3, 1]

Calling the function above multiple times will always return the list in the same random order.

The seed can, of course, also be used when using shuffle as a filter:

1
{{ [1, 2, 3] | shuffle(seed=1) }}

Returns:

[2, 3, 1]

Shuffle anything¶

The examples above use a list of numbers that get shuffled, but shuffle can be used on any list of items.

1
{{ shuffle(["Not", "your", "homie", 1, 2, 3]) }}

Returns:

["homie", 2, "Not", 3, 1, "your"]

Features requests, ideas, and support¶

If you have an idea on how to further enhance the Home Assistant template engine, for example, by adding a new template function; feel free to let us know in our discussion forums.

Are you stuck using this new feature? Or maybe you’ve run into a bug? Please check the Support page on where to go for help.