Revise the standard button event types and their triggers and conditions

[arturpragacz]

Summary

This proposal amends the approved proposal #1377 (standard event types for event entities with device class button). It splits the event types into a physical layer (press_start, press_end) and a gesture layer (long_press_start, long_press_end, single_press, multi_press), gives each type one meaning that holds on every device, and removes multi_press_ongoing. On top of them it defines the triggers button.pressed, button.multi_pressed, button.held and button.hold_ended and the condition button.is_held, each with a declared requirement on event_types. Rotary input stays out of scope.

Problem

The first trigger implementation, core#177683, stalled on a question the approved text does not answer, and the Matter (core#177101), isy994 (core#169782) and Lutron Caséta (core#184266) migrations each resolved it differently.

#1377 defines press_end as "released after a brief press (the standard click)". Those are two different facts. Hardware reports presses in three shapes:

Shape	What the device reports	Examples
Edges only	down and up; it cannot count or time anything	Lutron Pico, EnOcean rockers, Hue Tap, Matter MS/MSR-only switches
Resolved gestures only	"single", "double", "hold"; the single is delayed until the device knows it is not a double	Z-Wave Central Scene, HomeKit, BTHome, SmartThings, Tuya, Tasmota, Shelly Gen1, Matter ActionSwitch, HomematicIP, nearly all ZHA quirks
Both	per-press down/up and a resolved count	Matter MSR+MSM, Shelly Gen2, ZHA Philips quirk, deCONZ Hue devices, Flic, Inovelli

In the third shape the release and the single click are two events: the device reports the release immediately, and the single click only after its multi-press window has passed, because only then does it know there was no second press.

Reading press_end as the click forces integrations for these devices to suppress or re-time native events and leaves press_start firing N times per N-press with one press_end. Reading it as the release leaves button.pressed with nothing to listen to on the second shape, which is the majority. The standard needs to name both facts, and the triggers need to know which ones an entity can produce.

Proposal

Event types

The event types form two layers that map onto the three shapes above. Physical types describe the edges of the button. Gesture types describe what the device concluded. A device declares a type in event_types only if the type's meaning holds for every event it will send under that name.

Event type	Layer	Meaning
press_start	physical	The button went down. Declared only if reported for every press.
press_end	physical	Released after a press the device did not classify as long.
long_press_start	gesture	The hold threshold was reached while the button is still down. Exactly once per hold.
long_press_end	gesture	Released after a press the device classified as long.
single_press	gesture	The device concluded that exactly one short press happened: the exclusive single press.
multi_press	gesture	The device finished counting a sequence of two or more presses; a long press never counts. Declared only together with single_press. Data: press_count.

Triggers and conditions

Where a trigger lists fallbacks, it fires on the first type in the list that the entity declares, so the trigger means the same on every device and only the timing follows the hardware. Each trigger carries a static requirement on the entity's event_types; the editor uses it to offer the trigger only for capable entities, and the trigger uses it at runtime.

Trigger	Fires on	Field	Requires in event_types
button.pressed	single_press if declared; else press_end; else press_start. For button and input_button entities: any press.		any of single_press, press_end, press_start
button.multi_pressed	multi_press with count equal to press_count	press_count, default 2	multi_press
button.held	long_press_start if declared; else long_press_end		any of long_press_start, long_press_end
button.hold_ended	long_press_end		long_press_start and long_press_end

Condition	True when	Requires in event_types
button.is_held	the entity's last event_type is long_press_start	long_press_start and long_press_end

hold_ended requires the start as well because it exists to pair with held; on a release-only device both would fire at the same instant.

Deferred, with the same model:

• button.being_held: fires every interval between long_press_start and long_press_end.
• button.pressed_down: fires on press_start.

Rules for integrations

1. Map one native event to one standard event. Do not suppress, delay or synthesize events, and do not run timers or windows.
2. Declare only types whose meaning holds for every event sent under that name. A Matter ActionSwitch sends InitialPress once per sequence, so it does not declare press_start; it keeps initial_press as an extra.
3. If the device resolves press counts, a single is single_press and two or more are multi_press with the count.
4. Declare multi_press only together with single_press. A device that reports a double press but never a resolved single, such as Lutron Caséta MultiTap, keeps its double as an extra type. This keeps button.pressed exclusive wherever button.multi_pressed is offered.
5. A device that reports a single event per press maps it by what that event is. Sent when the button goes down, it is press_start (Hue Tap, Lutron keypads). Sent when the button is released, it is press_end. Reported as a completed press with no edge meaning, for example after the device's own debounce or through a cloud event, it is single_press (Govee, Gentex, HomeKit single-press-only switches). When in doubt, prefer single_press.
6. A hold reported at the threshold is long_press_start; a hold reported after release is long_press_end.
7. One bit of local state is allowed for two things only: classifying an unclassified release as press_end or long_press_end after a hold start was seen, and sending long_press_start once when the device repeats it. Raw repeats may stay as extra types.
8. Integration-specific types remain allowed next to the standard ones.

Indicative mapping

The table shows how the main sources would map under the rules above, based on protocol documentation and the current integration code. It is illustrative, not prescriptive: integration authors should verify how their devices actually report, in particular whether a hold arrives at the threshold or after release, before migrating.

Click to expand

Source	Native → standard
Matter Switch	InitialPress→press_start (not on ActionSwitch); ShortRelease→press_end; LongPress→long_press_start; LongRelease→long_press_end; MultiPressComplete(1)→single_press; MultiPressComplete(n ≥ 2)→multi_press n
Shelly Gen2	btn_down→press_start; btn_up→press_end or long_press_end by rule 7; single_push→single_press; double/triple_push→multi_press 2/3; long_push→long_press_start
Shelly Gen1, Shelly BLU, BTHome, Xiaomi BLE	single→single_press; double/triple→multi_press 2/3; long after release→long_press_end
Hue v2	initial_press→press_start; short_release→press_end; long_press→long_press_start; long_release→long_press_end; repeat→extra. Hue Tap: initial_press→press_start
Z-Wave Central Scene	KeyPressed→single_press; KeyPressed2x..5x→multi_press 2..5; KeyHeldDown→long_press_start once; KeyReleased→long_press_end
ZHA quirks, deCONZ	codes meaning the down edge→press_start; short_release codes→press_end; codes meaning a resolved single→single_press; double..quintuple→multi_press 2..5; long_press→long_press_start; long_release→long_press_end
HomeKit, SmartThings, Tuya, Tasmota	single→single_press; double/N→multi_press 2/N; hold→long_press_start or long_press_end by rule 6
HomematicIP, Homematic	short→press_end; long start→long_press_start; long stop→long_press_end
Lutron Caséta	Pico Press/Release→press_start/press_end; keypad Press (no release)→press_start; LongHold→long_press_start; MultiTap→extra (rule 4)
isy994 / Insteon	On/Off→single_press; Fast On/Off→multi_press 2; Fade Up/Down→long_press_start; Fade Stop→long_press_end
Govee, Gentex, demo	press→single_press

Frontend

The target selector needs to filter entities by the content of the event_types attribute: "contains any of" for pressed and held, "contains all of" for hold_ended and is_held. #1377 already noted this as required work.

Changes relative to #1377

Click to expand

• press_end was both the release and the click. It is now the physical release only, and resolved singles map to a new type, single_press. Devices that detect multi-press report the two as separate events.
• A device with one event per press maps it by what the event is (press_start, press_end or single_press) instead of always to press_end.
• multi_press_end with multi_press_count is renamed multi_press with press_count, same meaning. The pair with single_press reads as one concept and matches the trigger names.
• A count of 0 is not part of the standard; Matter drops it. Aborted sequences are not useful to users.
• multi_press_ongoing is removed. It is produced only by Matter switches without the ActionSwitch flag, and the only device that needs it is a rotary one. Matter may keep it as an extra type.
• long_press_start is sent exactly once per hold. Z-Wave, Hue and Homematic repeat the hold event; consumers should not have to dedupe.
• A single-event hold maps by timing: at the threshold it is long_press_start, after release it is long_press_end. Standardize event types for button event entities #1377 mapped it to long_press_start regardless, but Shelly BLU and others report it after release.
• New constraints on integrations: a type is declared only if its meaning holds for every event; multi_press only together with single_press; no timers or synthesized events.
• Triggers: pressed gains fallbacks, double pressed becomes multi_pressed with a count, hold started becomes held with a fallback, hold_ended requires both hold types, the condition is is_held, and each carries a requirement on event_types; being_held and pressed_down are deferred.

Out of scope

Rotary input, as in #1377. Dials and wheels need their own device class and vocabulary. That includes the IKEA BILRESA wheel, which reaches Home Assistant as a Matter multi-press switch and was the only real consumer of multi_press_ongoing.

[davidrecordon]

@arturpragacz thanks for writing this up! The proposed Lutron mapping matches what I tested on an RA3 system directly:

• Picos send Press and Release for every tap (another tester saw the same on a Caséta bridge)
• Sunnata keypads send a single Press when the button goes down

Happy to update home-assistant/core#184266 to this mapping once it's settled 😄

[abmantis]

The previous proposal focused on a consistent logical model at the entity-level, with triggers consuming that directly. This one focuses on passing a bit more "raw" events from integrations, making the triggers work around them.
I would prefer to still have a consistent set of events (and having triggers just follow them). Event entities are user-facing too, so we should try to make them consistent.

I like the addition of the "physical" events, but I like the consistent "logical" events that the original proposal defined.

I'm splitting the comment in the original proposal sections to make it easier to follow:

Problem section

Reading press_end as the click forces integrations for these devices to suppress or re-time native events and leaves press_start firing N times per N-press with one press_end.

This part regarding the original proposal is not correct. In that proposal, press_start was intended to fire once (on the first event). press_end will also fire once (for a single-click event). press_start would always have one (and only one) matching end event: press_end, long_press_end, or multi_press_end.

Reading it as the release leaves button.pressed with nothing to listen to on the second shape,

This assumption is also incorrect: button.pressed listens for press_end. The second-shape integrations would fire press_end on the single event. They would not fire press_start.

Event types section

• press_end is described as Released after a press the device did not classify as long.. Does that mean that it does not fire when long_press_end fires? That conflicts with the physical/gesture split.
• multi_press_ongoing is gone from this proposal. It contained the multi_press_count that allowed the user to track multi presses. We should keep this functionality (even if through a different event).

Triggers and conditions section

• Having one trigger mix up different event types is confusing and will make it much harder to explain to the user what/when the triggers work.
• pressed and pressed_down is confusing. For me the old trigger names were clearer.

Rules for integrations section

Declare multi_press only together with single_press. A device that reports a double press but never a resolved single, such as Hue double_short_release or Lutron Caséta MultiTap, keeps its double as an extra type. This keeps button.pressed exclusive wherever button.multi_pressed is offered.

This is another limitation that the previous proposal did not have. If the device only reports double_short_press, it would just fire multi_press_end. The user will still be able to use the multi press trigger.

[arturpragacz]

Thanks for the detailed read. I'll follow your sections.

General framing

The previous proposal focused on having integrations provide a consistent set of events. This one focuses on passing "raw" events from integrations, making the triggers work around them.

This is the wrong way round. #1377 had a consistent list of names, but the meaning behind a name depended on the device. This proposal is the one with consistent events: six types, each with one meaning, and the same meaning on every device. Nothing is passed through raw; a type is declared only if the device can honour that meaning for every event it sends under the name. In #1377:

• press_end was the immediate physical release on Hue, Lutron and Matter without multi-press, and the delayed resolved single on Z-Wave, HomeKit and Matter with multi-press. Same name, different timing, different exclusivity.
• long_press_start was "at the threshold" on Hue and Z-Wave and "after release" on Shelly BLU and BTHome.

Both proposals let a device produce only a subset of the types. What changes here is that the subset is chosen by what the device actually reports, and the fallback from "resolved single" to "release" is written once, in the trigger, instead of being re-implemented differently in every integration. This is not a theoretical concern: the three migrations written against #1377 so far (Matter, isy994, Lutron Caséta) each resolved it differently.

I would prefer to still have a consistent set of events (and having triggers just follow them). Event entities are user-facing too, so we should try to make them consistent.

Consistency for a user-facing entity means that press_end in the event log means the same thing on every device, and that is what this proposal delivers. The triggers do just follow the events; the fallback is a static list of types the trigger listens to.

That said, there is a variant that gets closer to what you describe: the base event entity could derive single_press itself, after press_end on devices that declare no single_press, and after press_start on devices that declare neither. Then button.pressed follows exactly one type, the selector filters on one type, every button shows the same press_end then single_press sequence that Matter or Shelly already show natively, and the integration rules do not change. It does not extend to holds, so held would keep its fallback; closing that gap too would need yet another derived type and another trigger, which would add substantial complexity to both the events and the triggers for very little gain. With that limitation in mind, I'm open to it.

Problem section

In that proposal, press_start was intended to fire once (on the first event).

The approved text does not say that. It defines press_start as "Button physically pressed down", and a double press has two of those. Every implementation written against #1377 reads it that way: the Matter PR (home-assistant/core#177101) maps InitialPress to press_start on every press and MultiPressComplete(1) to multi_press_end with count 1, and the Lutron PR fires press_start/press_end per tap. The "once per sequence" reading was never written down, which is exactly why home-assistant/core#177683 stalled.

Making it fire once has a real cost. On Matter with multi-press, Shelly Gen2, Hue, deCONZ and Flic the integration would have to track "sequence in progress", drop every ShortRelease/btn_up, drop every InitialPress after the first, and emit press_end only when the device's multi-press window closes. The physical release stops being a standard event at all. Your own suggestion in home-assistant/core#177683 to keep Shelly btn_down/btn_up as non-standard types is this cost made visible. This proposal keeps them standard, as the physical layer.

button.pressed listens for press_end. The second-shape integrations would fire press_end on the single event.

Yes, and that is the dual meaning from the framing section: your comment applies the release reading to Hue-style devices and the click reading to Z-Wave-style devices. Under this proposal button.pressed fires at exactly the same moments as under #1377, on single_press where the device resolves singles and on press_end otherwise. Nothing is lost for the trigger; what is gained is that press_end means the same thing for every integration.

Event types section

Does press_end not fire when long_press_end fires?

Correct. press_end and long_press_end are exclusive, exactly as in #1377 ("released after a brief press" vs "released after a long hold") and in Matter (ShortRelease vs LongRelease). A release has to be one or the other, or button.pressed would fire at the end of every hold. There is no conflict with the split: "physical" means the type describes an edge of the button rather than a conclusion about the sequence, not that the edge is unclassified.

multi_press_ongoing is gone. We should keep this functionality.

The functionality it supports is rotary input, which is out of scope. An intermediate count is useful when each press is a step and the user wants to act on every step, which is what a wheel does: the IKEA BILRESA reports its rotation as a Matter multi-press sequence, and it was the only concrete consumer raised in #1377. For a real button nobody acts on "two presses so far"; the count users need is the final one, and multi_press delivers it. On the producing side, only Matter switches without the ActionSwitch flag can emit it. No other protocol reports intermediate counts, and Matter 1.4 itself dropped the event for ActionSwitch devices. Matter keeps multi_press_ongoing as an extra type, so nothing is lost, and when rotary gets its own device class the event can be defined there with the meaning it actually has. Adding a standard type later is not breaking; removing one later is.

Triggers and conditions section

Having one trigger mix up different event types is confusing.

It does not mix meanings. The trigger has one meaning: the button was pressed once. The fallback list is how that meaning is delivered on hardware that cannot resolve singles; the alternative is the same fallback hidden inside each integration, which is what #1377 produced. Users never see event types in the trigger UI, and the description is one sentence: "Fires when the button is pressed once." That it comes a little later on devices that detect double presses is a note for the docs, not something the user has to configure or understand.

pressed and pressed_down is confusing. The old trigger names were clearer.

These are not new names. Both button.pressed and button.pressed_down were already defined in #1377, and this proposal keeps them as they were. button.pressed is not really open for renaming anyway: it already exists in core for button and input_button entities, and automations use it today, so even if button.single_clicked would read better, the name is fixed. The names that are new here (multi_pressed, held, hold_ended, is_held) fill in what #1377 explicitly left open. I'm happy to bikeshed any of the names, but that is a detail; what matters in this proposal is the model.

Rules for integrations section

If the device only reports double_short_press, it would just fire multi_press_end.

This is an edge case: devices that report a double press but never a resolved single are rare. In the survey behind this proposal the Lutron Pico is the only one; every other multi-press source reports the single too. And the rule exists for the user, not the integration. Take a Pico with MultiTap declared as multi_press, and an automation that toggles a light on button.pressed and activates a scene on button.multi_pressed. A double tap sends Press and Release for each tap plus MultiTap, so the light toggles twice and the scene runs. #1377 has the same problem; its trigger table assumes the single and the double are exclusive, which this device cannot deliver. The rule just makes that explicit: wherever multi_pressed is offered, pressed is exclusive, and the editor can rely on it.

The device's double is still exposed as its own type and still usable through the generic event trigger. The only way to offer multi_pressed on such a device is for the integration to synthesize the single with a timer, which is not a good user experience, and #1377 did not want it either.

Side note: I dropped Hue double_short_release from the proposal's example. The Hue integration does not declare it, and its constant notes the event has never been seen.

[nielsrowinbik]

I will be commenting on the trigger/condition surface as the underlying event layer, while accessible to users, is not intended to be the primary surface for interacting with buttons in things like automations and scripts. I understand and support the reasoning behind changing the event surface. What I don't quite get is why the trigger/condition surface had to change with it.

double pressed becomes multi_pressed with a count

I much prefer the approach @abmantis and I landed on in home-assistant/core#168598, which is to have a button.pressed trigger with a count argument that defaults to 1 (and has named options in the UI). This is much more elegant and allows users switching from a single press to a multi-press to not have to replace one trigger with another.

Furthermore, I don't quite understand the reasoning behind the renaming of button.hold_started to button.held in relationship to the button.being_held trigger from home-assistant/core#168598 (and you deferring that). Besides changing the scope and deferring something being IMO a product decision, I think the choice of button.held conflicts with the name for button.being_held. This is the very reason I initially went for button.hold_started.

I'm open to discussing how these names work together, but I think deferring the button.being_held trigger is the right decision. It's a very common thing to want to automate, and I think the repeat while method we force upon the users now is worse UX.

[arturpragacz]

have a button.pressed trigger with a count argument that defaults to 1

That is close to what button.multi_pressed already does. The only difference is that the single press is a separate trigger. That split makes sense because the two correspond to distinct categories of devices: every button can be pressed, but only some can count presses. button.pressed also covers entirely different domains, button and input_button, where a count has no meaning. And it keeps the frontend filtering simpler as well.

renaming of button.hold_started to button.held

Because on some devices it does not fire at hold start. Devices like the Shelly BLU button or BTHome report a long press only after release, and button.held falls back to long_press_end there so users still get a working hold trigger. Calling that hold_started would be wrong on those devices; held is true on all of them.

deferring the button.being_held trigger

It is defined in the proposal with the same model (fires every interval between long_press_start and long_press_end), so nothing about the event layer or the other triggers stands in its way. It is deferred because the same thing is not hard to build in an automation with the triggers and conditions we do define, using the repeat action. If there turns out to be significant user demand to make that even simpler, the trigger is easy to add on top.

[nielsrowinbik]

have a button.pressed trigger with a count argument that defaults to 1

That is close to what button.multi_pressed already does. The only difference is that the single press is a separate trigger. That split makes sense because the two correspond to distinct categories of devices: every button can be pressed, but only some can count presses. button.pressed also covers entirely different domains, button and input_button, where a count has no meaning. And it keeps the frontend filtering simpler as well.

You're right that some devices only support one press with others support more. In that line of arguing, though, some devices will only support double presses, while other will also support triple/quadruple/etc presses. We're not going to split each trigger off into its own because of this.

Instead, depending on the capabilities of the targeted buttons, the UI can just change (certain count options (or the entire selector) becoming disabled). This would also happen if we were to split off into multi_pressed, so this is discussion purely about the "entrypoint" for the user. I don't want the user to have to swap out one trigger for another if they decide that they want to change from a single press trigger to a multi-press one. That additional friction makes no sense to me in this case. So I would propose to go back to the original button.pressed with count argument, as specced in home-assistant/core#168598.

renaming of button.hold_started to button.held

Because on some devices it does not fire at hold start. Devices like the Shelly BLU button or BTHome report a long press only after release, and button.held falls back to long_press_end there so users still get a working hold trigger. Calling that hold_started would be wrong on those devices; held is true on all of them.

OK, that sounds fair. The only problem I have is the semantic collision with "button.being_held". The two are very similar in name now, and without any context, it's pretty much impossible to tell the difference. But then the being_held trigger is the one that should get a different name.

deferring the button.being_held trigger

[...] It is deferred because the same thing is not hard to build in an automation with the triggers and conditions we do define, using the repeat action.

I am aware of this, obviously. Forcing people into having to think about while loops (that's essentially what a repeat action is in this case) is, however, awful UX for non-programmers. The image that Home Assistant is only for programmers is exactly the image we're trying to shake. We should not defer this change and instead take the opportunity to fix a long-standing UX issue.

If we move forward with the rename of button.hold_started to button.held, which I can get behind, we need a new name for this convenience-trigger. We could go with something like button.while_held or something?

[emontnemery]

The proposal was approved by the core meeting 2026-10-15