Support FunctionVar handlers in EventChain rendering

Allow EventChain to accept frontend FunctionVar handlers alongside
EventSpec, EventVar, and EventCallback values.

When a chain contains FunctionVars, keep backend events grouped through
addEvents(...) and invoke frontend functions inline with the trigger
arguments so mixed chains preserve execution order and DOM event
actions like preventDefault and stopPropagation.

Wrap inline arrow functions before emitting VarOperationCall JS so
direct invocation renders valid JavaScript, add unit coverage for
pure/mixed event-chain formatting and creation, and move upload
exception docs to the helper that actually raises them to satisfy
darglint.

Author: FarhanAliRaza

reflex/app.py

@@ -1931,11 +1931,6 @@ async def upload_file(request: Request):
         Returns:
             StreamingResponse yielding newline-delimited JSON of StateUpdate
             emitted by the upload handler.
-
-        Raises:
-            UploadValueError: if there are no args with supported annotation.
-            UploadTypeError: if a background task is used as the handler.
-            HTTPException: when the request does not include token / handler headers.
         """
         from reflex.utils.exceptions import UploadTypeError, UploadValueError
 
@@ -1960,6 +1955,11 @@ async def _create_upload_event() -> Event:
 
             Returns:
                 The upload event backed by the original temp files.
+
+            Raises:
+                UploadValueError: If there are no uploaded files or supported annotations.
+                UploadTypeError: If a background task is used as the handler.
+                HTTPException: If the request is missing token or handler headers.
             """
             files = form_data.getlist("files")
             if not files:

reflex/event.py

@@ -449,8 +449,8 @@ def __call__(self, *args, **kwargs) -> EventSpec:
 class EventChain(EventActionsMixin):
     """Container for a chain of events that will be executed in order."""
 
-    events: Sequence["EventSpec | EventVar | EventCallback"] = dataclasses.field(
-        default_factory=list
+    events: Sequence["EventSpec | EventVar | FunctionVar | EventCallback"] = (
+        dataclasses.field(default_factory=list)
     )
 
     args_spec: Callable | Sequence[Callable] | None = dataclasses.field(default=None)
@@ -483,6 +483,8 @@ def create(
         if isinstance(value, Var):
             if isinstance(value, EventChainVar):
                 return value
+            if isinstance(value, FunctionVar):
+                return value
             if isinstance(value, EventVar):
                 value = [value]
             elif safe_issubclass(value._var_type, (EventChain, EventSpec)):
@@ -505,23 +507,26 @@ def create(
 
         # If the input is a list of event handlers, create an event chain.
         if isinstance(value, list):
-            events: list[EventSpec | EventVar] = []
+            events: list[EventSpec | EventVar | FunctionVar] = []
             for v in value:
                 if isinstance(v, (EventHandler, EventSpec)):
                     # Call the event handler to get the event.
                     events.append(call_event_handler(v, args_spec, key=key))
+                elif isinstance(v, (EventVar, FunctionVar)):
+                    events.append(v)
                 elif isinstance(v, Callable):
                     # Call the lambda to get the event chain.
                     result = call_event_fn(v, args_spec, key=key)
                     if isinstance(result, Var):
+                        if isinstance(result, (EventVar, FunctionVar)):
+                            events.append(result)
+                            continue
                         msg = (
                             f"Invalid event chain: {v}. Cannot use a Var-returning "
                             "lambda inside an EventChain list."
                         )
                         raise ValueError(msg)
                     events.extend(result)
-                elif isinstance(v, EventVar):
-                    events.append(v)
                 else:
                     msg = f"Invalid event: {v}"
                     raise ValueError(msg)
@@ -2077,12 +2082,15 @@ def create(
         sig = inspect.signature(arg_spec)  # pyright: ignore [reportArgumentType]
         if sig.parameters:
             arg_def = tuple(f"_{p}" for p in sig.parameters)
-            arg_def_expr = LiteralVar.create([Var(_js_expr=arg) for arg in arg_def])
+            arg_vars = tuple(Var(_js_expr=arg) for arg in arg_def)
+            arg_def_expr = LiteralVar.create(list(arg_vars))
+            call_args = arg_vars
         else:
             # add a default argument for addEvents if none were specified in value.args_spec
             # used to trigger the preventDefault() on the event.
             arg_def = ("...args",)
             arg_def_expr = Var(_js_expr="args")
+            call_args = (Var(_js_expr="...args"),)
 
         if value.invocation is None:
             invocation = FunctionStringVar.create(
@@ -2099,16 +2107,73 @@ def create(
             msg = f"EventChain invocation must be a FunctionVar, got {invocation!s} of type {invocation._var_type!s}."
             raise ValueError(msg)
 
+        has_function_var = any(isinstance(e, FunctionVar) for e in value.events)
+
+        if not has_function_var:
+            return_expr = invocation.call(
+                LiteralVar.create([LiteralVar.create(event) for event in value.events]),
+                arg_def_expr,
+                value.event_actions,
+            )
+        else:
+            statement_js: list[str] = []
+            statement_var_data: list[VarData | None] = []
+            queueable_group: list[EventSpec | EventVar | EventCallback] = []
+
+            if value.event_actions.get("preventDefault") or value.event_actions.get(
+                "stopPropagation"
+            ):
+                statement_js.append(
+                    "const _reflex_dom_event = "
+                    f"{arg_def_expr}.filter((o) => o?.preventDefault !== undefined)[0];"
+                )
+                if value.event_actions.get("preventDefault"):
+                    statement_js.append(
+                        "if (_reflex_dom_event?.preventDefault) "
+                        "{_reflex_dom_event.preventDefault();}"
+                    )
+                if value.event_actions.get("stopPropagation"):
+                    statement_js.append(
+                        "if (_reflex_dom_event?.stopPropagation) "
+                        "{_reflex_dom_event.stopPropagation();}"
+                    )
+
+            def flush_queueable_group() -> None:
+                if not queueable_group:
+                    return
+                queue_call = invocation.call(
+                    LiteralVar.create([
+                        LiteralVar.create(event) for event in queueable_group
+                    ]),
+                    arg_def_expr,
+                    {},
+                )
+                statement_js.append(f"{queue_call!s};")
+                statement_var_data.append(queue_call._get_all_var_data())
+                queueable_group.clear()
+
+            for event in value.events:
+                if isinstance(event, FunctionVar):
+                    flush_queueable_group()
+                    function_call = event.call(*call_args)
+                    statement_js.append(f"{function_call!s};")
+                    statement_var_data.append(function_call._get_all_var_data())
+                else:
+                    queueable_group.append(event)
+
+            flush_queueable_group()
+
+            return_expr = Var(
+                _js_expr=f"{{{''.join(statement_js)}}}",
+                _var_data=VarData.merge(*statement_var_data),
+            )
+
         return cls(
             _js_expr="",
             _var_type=EventChain,
             _var_data=_var_data,
             _args=FunctionArgs(arg_def),
-            _return_expr=invocation.call(
-                LiteralVar.create([LiteralVar.create(event) for event in value.events]),
-                arg_def_expr,
-                value.event_actions,
-            ),
+            _return_expr=return_expr,
             _var_value=value,
         )
 

reflex/vars/function.py

@@ -239,7 +239,11 @@ def _cached_var_name(self) -> str:
         Returns:
             The name of the var.
         """
-        return f"({self._func!s}({', '.join([str(LiteralVar.create(arg)) for arg in self._args])}))"
+        func_expr = str(self._func)
+        if "=>" in func_expr and not format.is_wrapped(func_expr, "("):
+            func_expr = format.wrap(func_expr, "(")
+
+        return f"({func_expr}({', '.join([str(LiteralVar.create(arg)) for arg in self._args])}))"
 
     @cached_property_no_lock
     def _cached_get_all_var_data(self) -> VarData | None:

tests/units/test_event.py

@@ -32,6 +32,12 @@ def make_var(value) -> Var:
     return Var(_js_expr=value)
 
 
+def make_timeout_logger():
+    return rx.vars.FunctionStringVar.create(
+        "(...args) => { setTimeout(() => console.log('Timeout reached!', args), 1000); }"
+    ).to(EventChain)
+
+
 def test_create_event():
     """Test creating an event."""
     event = Event(token="token", name="state.do_thing", payload={"arg": "value"})
@@ -668,6 +674,41 @@ def _args_spec() -> tuple:
     assert "to bool" in str(err.value)
 
 
+def test_event_chain_create_allows_plain_function_var():
+    """Plain FunctionVars should be usable as frontend event handlers."""
+    frontend_handler = make_timeout_logger()
+
+    assert EventChain.create(frontend_handler, args_spec=lambda: ()) is frontend_handler
+
+
+def test_event_chain_create_allows_function_var_in_list():
+    """FunctionVars should be allowed inside EventChain lists."""
+    frontend_handler = make_timeout_logger()
+
+    chain = EventChain.create([frontend_handler], args_spec=lambda: ())
+
+    assert isinstance(chain, EventChain)
+    assert chain.events == [frontend_handler]
+
+
+def test_button_accepts_mixed_event_handler_and_function_var():
+    """Components should accept mixed backend/frontend event chains."""
+
+    class MixedState(BaseState):
+        @event
+        def do_a_thing(self):
+            pass
+
+    log_after_timeout = make_timeout_logger()
+
+    button = rx.button(
+        "Do both",
+        on_click=[MixedState.do_a_thing, log_after_timeout],
+    )
+
+    assert isinstance(button.event_triggers["on_click"], EventChain)
+
+
 def test_decentralized_event_with_args():
     """Test the decentralized event."""
 

tests/units/utils/test_format.py

@@ -20,6 +20,7 @@
 from reflex.utils import format
 from reflex.utils.serializers import serialize_figure
 from reflex.vars.base import LiteralVar, Var
+from reflex.vars.function import FunctionStringVar
 from reflex.vars.object import ObjectVar
 
 pytest.importorskip("pydantic")
@@ -41,6 +42,88 @@ def mock_event(arg):
     pass
 
 
+def mock_event_two(arg):
+    pass
+
+
+def make_timeout_logger():
+    return FunctionStringVar.create(
+        "(...args) => { setTimeout(() => console.log('Timeout reached!', args), 1000); }"
+    ).to(EventChain)
+
+
+def test_format_prop_event_chain_pure_eventspec_grouped():
+    """Pure EventSpec chains should still collapse to one addEvents call."""
+    chain = EventChain(
+        events=[
+            EventSpec(handler=EventHandler(fn=mock_event)),
+            EventSpec(handler=EventHandler(fn=mock_event_two)),
+        ],
+        args_spec=lambda e: [e],
+    )
+
+    assert format.format_prop(LiteralVar.create(chain)) == (
+        '((_e) => (addEvents([(ReflexEvent("mock_event", ({  }), ({  }))), '
+        '(ReflexEvent("mock_event_two", ({  }), ({  })))], [_e], ({  }))))'
+    )
+
+
+def test_format_prop_event_chain_pure_function_var():
+    """Pure FunctionVar chains should render as direct frontend calls."""
+    log_after_timeout = make_timeout_logger()
+    chain = EventChain(
+        events=[log_after_timeout],
+        args_spec=lambda e: [e],
+    )
+
+    assert format.format_prop(LiteralVar.create(chain)) == (
+        "((_e) => {(((...args) => { setTimeout(() => console.log('Timeout reached!', "
+        "args), 1000); })(_e));})"
+    )
+
+
+def test_format_prop_event_chain_mixed_queue_and_function():
+    """Mixed chains should alternate addEvents and direct calls in order."""
+    log_after_timeout = make_timeout_logger()
+    chain = EventChain(
+        events=[
+            EventSpec(handler=EventHandler(fn=mock_event)),
+            log_after_timeout,
+            EventSpec(handler=EventHandler(fn=mock_event_two)),
+        ],
+        args_spec=lambda e: [e],
+    )
+
+    assert format.format_prop(LiteralVar.create(chain)) == (
+        '((_e) => {(addEvents([(ReflexEvent("mock_event", ({  }), ({  })))], '
+        "[_e], ({  })));(((...args) => { setTimeout(() => console.log('Timeout reached!', "
+        'args), 1000); })(_e));(addEvents([(ReflexEvent("mock_event_two", '
+        "({  }), ({  })))], [_e], ({  })));})"
+    )
+
+
+def test_format_prop_event_chain_mixed_with_event_actions():
+    """Mixed chains should preserve DOM event actions on the wrapper callback."""
+    log_after_timeout = make_timeout_logger()
+    chain = EventChain(
+        events=[
+            EventSpec(handler=EventHandler(fn=mock_event)),
+            log_after_timeout,
+        ],
+        args_spec=lambda e: [e],
+        event_actions={"preventDefault": True, "stopPropagation": True},
+    )
+
+    assert format.format_prop(LiteralVar.create(chain)) == (
+        "((_e) => {const _reflex_dom_event = [_e].filter((o) => "
+        "o?.preventDefault !== undefined)[0];if (_reflex_dom_event?.preventDefault) "
+        "{_reflex_dom_event.preventDefault();}if (_reflex_dom_event?.stopPropagation) "
+        '{_reflex_dom_event.stopPropagation();}(addEvents([(ReflexEvent("mock_event", '
+        "({  }), ({  })))], [_e], ({  })));(((...args) => { setTimeout(() => "
+        "console.log('Timeout reached!', args), 1000); })(_e));})"
+    )
+
+
 @pytest.mark.parametrize(
     ("input", "output"),
     [