API Reference

Main Module

Bases: Generic[BuilderType]

RouteLit is a class that provides a framework for handling HTTP requests and generating responses in a web application. It manages the routing and view functions that define how the application responds to different requests.

The class maintains a registry of fragment functions and uses a builder pattern to construct responses. It supports both GET and POST requests, handling them differently based on the request method.

Key features: - Session storage management - Fragment registry for reusable view components - Support for both GET and POST request handling - Builder pattern for constructing responses - Support for dependency injection in view functions

The class is designed to be flexible, allowing for custom builder classes and session storage implementations.

Source code in src/routelit/routelit.py

class RouteLit(Generic[BuilderType]):
    """
    RouteLit is a class that provides a framework for handling HTTP requests and generating responses in a web application. It manages the routing and view functions that define how the application responds to different requests.

    The class maintains a registry of fragment functions and uses a builder pattern to construct responses. It supports both GET and POST requests, handling them differently based on the request method.

    Key features:
    - Session storage management
    - Fragment registry for reusable view components
    - Support for both GET and POST request handling
    - Builder pattern for constructing responses
    - Support for dependency injection in view functions

    The class is designed to be flexible, allowing for custom builder classes and session storage implementations.
    """

    def __init__(
        self,
        BuilderClass: Type[BuilderType] = RouteLitBuilder,  # type: ignore[assignment]
        session_storage: Optional[MutableMapping[str, Any]] = None,
        cache_backend: Optional[MutableMapping[str, Any]] = None,
        inject_builder: bool = True,
        request_timeout: float = 60.0,  # timeout for the request to complete in seconds
        importmap: Optional[Dict[str, Any]] = None,
        extra_head_content: Optional[str] = None,
        extra_body_content: Optional[str] = None,
    ):
        self.BuilderClass = BuilderClass
        self.session_storage = session_storage or {}
        self.cache_backend = cache_backend or {}
        self.fragment_registry: Dict[str, Callable[[RouteLitBuilder], Any]] = {}
        self._session_builder_context: contextvars.ContextVar[RouteLitBuilder] = contextvars.ContextVar(
            "session_builder"
        )
        self.inject_builder = inject_builder
        self.request_timeout = request_timeout
        self.cancel_events: Dict[str, asyncio.Event] = {}
        self.importmap = DEFAULT_JS_DEPENDENCIES if importmap is None else {**DEFAULT_JS_DEPENDENCIES, **importmap}
        self.extra_head_content = extra_head_content
        self.extra_body_content = extra_body_content

    def get_extra_head_content(self) -> str:
        return self.extra_head_content or ""

    def get_extra_body_content(self) -> str:
        return self.extra_body_content or ""

    def get_importmap_json(self) -> str:
        return json.dumps({"imports": self.importmap}, indent=2)

    @contextmanager
    def _set_builder_context(self, builder: BuilderType) -> Generator[BuilderType, None, None]:
        """
        Temporarily expose the given builder instance through the
        `self.ui` property using a ContextVar.

        When this helper is used from multiple concurrent asyncio Tasks
        (or when the code it wraps spawns background tasks / threads)
        the logical *Context* in which the token was created can differ
        from the one in which ``reset`` is executed.  In that case
        ``ContextVar.reset`` raises ``ValueError`` with the message
        "Token was created in a different Context".

        This situation is benign for our use-case - the ContextVar has
        already been cleared for the current logical flow - so we simply
        suppress the error to prevent it from bubbling up and crashing the
        request handler.
        """
        token = self._session_builder_context.set(builder)
        try:
            yield builder
        finally:
            # ``reset`` fails if the context has diverged (e.g. different
            # asyncio.Task or thread).  Silently ignore that situation.
            with contextlib.suppress(ValueError):
                self._session_builder_context.reset(token)

    @property
    def ui(self) -> BuilderType:
        """
        The current builder instance.
        Use this in conjunction with `response(..., inject_builder=False)`

        Example:
            ```python
            rl = RouteLit()

            def my_view():
                rl.ui.text("Hello, world!")

            request = ...
            response = rl.response(my_view, request, inject_builder=False)
            ```
        """
        return cast(BuilderType, self._session_builder_context.get())

    def response(
        self,
        view_fn: ViewFn,
        request: RouteLitRequest,
        inject_builder: Optional[bool] = None,
        *args: Any,
        **kwargs: Any,
    ) -> Union[RouteLitResponse, Dict[str, Any]]:
        """Handle the request and return the response.

        Args:
            view_fn (ViewFn): (Callable[[RouteLitBuilder], Any]) The view function to handle the request.
            request (RouteLitRequest): The request object.
            **kwargs (Dict[str, Any]): Additional keyword arguments.

        Returns:
            RouteLitResponse | Dict[str, Any]:
                The response object.
                where Dict[str, Any] is a dictionary that contains the following keys:
                actions (List[Action]), target (Literal["app", "fragment"])

        Example:
            ```python
            from routelit import RouteLit, RouteLitBuilder

            rl = RouteLit()

            def my_view(rl: RouteLitBuilder):
                rl.text("Hello, world!")

            request = ...
            response = rl.response(my_view, request)

            # example with dependency
            def my_view(rl: RouteLitBuilder, name: str):
                rl.text(f"Hello, {name}!")

            request = ...
            response = rl.response(my_view, request, name="John")
            ```
        """
        if request.method == "GET":
            return self.handle_get_request(view_fn, request, **kwargs)
        elif request.method == "POST":
            return self.handle_post_request(view_fn, request, inject_builder, *args, **kwargs)
        else:
            # set custom exception for unsupported request method
            raise ValueError(request.method)

    def handle_get_request(
        self,
        view_fn: ViewFn,
        request: RouteLitRequest,
        **kwargs: Any,
    ) -> RouteLitResponse:
        """ "
        Handle a GET request.
        If the session state is present, it will be cleared.
        The head title and description can be passed as kwargs.
        Example:
        ```python
        return routelit_adapter.response(build_signup_view, head_title="Signup", head_description="Signup page")
        ```

        Args:
            request (RouteLitRequest): The request object.
            **kwargs (Dict[str, Any]): Additional keyword arguments.
                head_title (Optional[str]): The title of the head.
                head_description (Optional[str]): The description of the head.

        Returns:
            RouteLitResponse: The response object.
        """
        session_keys = request.get_session_keys()
        (
            ui_key,
            state_key,
            fragment_addresses_key,
            fragment_params_key,
            view_tasks_key,
        ) = session_keys
        view_tasks_key = build_view_task_key(view_fn, request.fragment_id, session_keys)
        if view_tasks_key in self.cancel_events:
            # send cancel event to the view task beforehand
            self.cancel_events[view_tasks_key].set()

        if state_key in self.session_storage:
            self.session_storage.pop(ui_key, None)
            self.session_storage.pop(state_key, None)
            self.session_storage.pop(fragment_addresses_key, None)
            self.session_storage.pop(fragment_params_key, None)
        return RouteLitResponse(
            elements=[],
            head=Head(
                title=kwargs.get("head_title"),
                description=kwargs.get("head_description"),
            ),
        )

    def _get_prev_keys(self, request: RouteLitRequest, session_keys: SessionKeys) -> Tuple[bool, SessionKeys]:
        maybe_event = request.ui_event
        if maybe_event and maybe_event["type"] == "navigate":
            new_session_keys = request.get_session_keys(use_referer=True)
            return True, new_session_keys
        return False, session_keys

    def _write_session_state(
        self,
        *,
        session_keys: SessionKeys,
        prev_root_element: RouteLitElement,
        prev_fragments: MutableMapping[str, List[int]],
        root_element: RouteLitElement,
        session_state: MutableMapping[str, Any],
        fragments: MutableMapping[str, List[int]],
        fragment_id: Optional[str] = None,
    ) -> None:
        if fragment_id and (fragment_address := prev_fragments.get(fragment_id, [])) and len(fragment_address) > 0:
            fragment_element = root_element
            new_element = set_element_at_address(prev_root_element, fragment_address, fragment_element)
        else:
            new_element = root_element

        ui_key, state_key, fragment_addresses_key, _, _vt = session_keys
        self.session_storage[ui_key] = new_element
        self.session_storage[state_key] = session_state
        self.session_storage[fragment_addresses_key] = {**prev_fragments, **fragments}

    def __write_session_state(
        self,
        session_keys: SessionKeys,
        transition_params: BuilderTranstionParams,
        builder: RouteLitBuilder,
        fragment_id: Optional[str],
    ) -> None:
        self._write_session_state(
            session_keys=session_keys,
            prev_root_element=transition_params.root_element,
            prev_fragments=transition_params.fragments,
            root_element=builder.root_element,
            session_state=builder.session_state.get_data(),
            fragments=builder.get_fragments(),
            fragment_id=fragment_id,
        )

    def _get_prev_elements_at_fragment(
        self,
        session_keys: SessionKeys,
        fragment_id: Optional[str],
    ) -> Tuple[RouteLitElement, Optional[RouteLitElement]]:
        """
        Returns the previous elements of the full page and the previous elements of the fragment if address is provided.
        """
        prev_root_element = self.session_storage.get(session_keys.ui_key, RouteLitElement.create_root_element())
        if fragment_id:
            fragment_address = self.session_storage.get(session_keys.fragment_addresses_key, {}).get(fragment_id, [])
            fragment_element = get_element_at_address(prev_root_element, fragment_address)
            return prev_root_element, fragment_element
        return prev_root_element, None

    def _handle_if_form_event(self, request: RouteLitRequest, session_keys: SessionKeys) -> bool:
        event = request.ui_event
        if event and event.get("type") != "submit" and (form_id := event.get("formId")):
            session_state = self.session_storage.get(session_keys.state_key, {})
            events = session_state.get(f"__events4later_{form_id}", {})
            events[event["componentId"]] = event
            self.session_storage[session_keys.state_key] = {
                **session_state,
                f"__events4later_{form_id}": events,
            }
            return True
        return False

    def _check_if_form_event(self, request: RouteLitRequest, session_keys: SessionKeys) -> None:
        if self._handle_if_form_event(request, session_keys):
            raise EmptyReturnException()

    def _handle_build_params(self, request: RouteLitRequest, session_keys: SessionKeys) -> BuilderTranstionParams:
        self._maybe_clear_session_state(request, session_keys)
        is_navigation_event, prev_session_keys = self._get_prev_keys(request, session_keys)
        prev_root_element, maybe_prev_fragment_element = self._get_prev_elements_at_fragment(
            prev_session_keys, request.fragment_id
        )
        if is_navigation_event:
            self._clear_session_state(prev_session_keys)
        prev_session_state = self.session_storage.get(prev_session_keys.state_key, {})
        prev_fragments = self.session_storage.get(prev_session_keys.fragment_addresses_key, {})
        return BuilderTranstionParams(
            root_element=prev_root_element,
            maybe_fragment_element=maybe_prev_fragment_element,
            session_state=prev_session_state,
            fragments=prev_fragments,
        )

    @staticmethod
    def _build_post_response(
        prev_root_element: RouteLitElement,
        root_element: RouteLitElement,
        fragment_id: Optional[str],
    ) -> ActionsResponse:
        target: Literal["app", "fragment"] = "app" if fragment_id is None else "fragment"
        actions = compare_single_elements(prev_root_element, root_element, target=target)
        return ActionsResponse(actions=actions, target=target)

    def _handle_builder_view_end(
        self,
        builder: RouteLitBuilder,
        session_keys: SessionKeys,
        transition_params: BuilderTranstionParams,
        fragment_id: Optional[str],
    ) -> ActionsResponse:
        self._write_session_state(
            session_keys=session_keys,
            prev_root_element=transition_params.root_element,
            prev_fragments=transition_params.fragments,
            root_element=builder.root_element,
            session_state=builder.session_state.get_data(),
            fragments=builder.get_fragments(),
            fragment_id=fragment_id,
        )
        real_prev_root_element = transition_params.maybe_fragment_element or transition_params.root_element
        return self._build_post_response(real_prev_root_element, builder.root_element, fragment_id)

    def handle_post_request(
        self,
        view_fn: ViewFn,
        request: RouteLitRequest,
        inject_builder: Optional[bool] = None,
        *args: Any,
        **kwargs: Any,
    ) -> Dict[str, Any]:
        inject_builder = self.inject_builder if inject_builder is None else inject_builder
        app_view_fn = view_fn
        session_keys = request.get_session_keys()
        try:
            self._check_if_form_event(request, session_keys)
            fragment_id = request.fragment_id
            if fragment_id and fragment_id in self.fragment_registry:
                view_fn = self.fragment_registry[fragment_id]
            transition_params = self._handle_build_params(request, session_keys)
            builder = self.BuilderClass(
                request,
                session_state=PropertyDict(transition_params.session_state),
                fragments=transition_params.fragments,
                initial_fragment_id=fragment_id,
            )
            new_args = (builder, *args) if inject_builder else args
            with self._set_builder_context(builder):
                view_fn(*new_args, **kwargs)
            builder.on_end()
            resp = self._handle_builder_view_end(builder, session_keys, transition_params, fragment_id)
            return asdict(resp)
        except RerunException as e:
            self.session_storage[session_keys.state_key] = e.state
            actual_view_fn = app_view_fn if e.scope == "app" else view_fn
            return self.handle_post_request(actual_view_fn, request, inject_builder, *args, **kwargs)
        except EmptyReturnException:
            # No need to return anything
            return asdict(ActionsResponse(actions=[], target="app"))

    async def _cancel_and_wait_view_task(self, view_task_key: str) -> None:
        """Cancel the view task and wait for it to be cleaned up."""
        if view_task_key not in self.cancel_events:
            return
        self.cancel_events[view_task_key].set()
        # Wait for cleanup
        while view_task_key in self.cancel_events:
            await asyncio.sleep(0.05)

    async def handle_post_request_async_stream(
        self,
        view_fn: ViewFn,
        request: RouteLitRequest,
        inject_builder: Optional[bool] = None,
        *args: Any,
        **kwargs: Any,
    ) -> ActionGenerator:
        inject_builder = self.inject_builder if inject_builder is None else inject_builder
        app_view_fn = view_fn
        session_keys = request.get_session_keys()
        if self._handle_if_form_event(request, session_keys):
            return  # no action needed
        fragment_id = request.fragment_id
        view_tasks_key = build_view_task_key(view_fn, fragment_id, session_keys)
        # Maybe cancel any existing view tasks for this key and wait for cleanup
        await self._cancel_and_wait_view_task(view_tasks_key)

        if fragment_id and fragment_id in self.fragment_registry:
            view_fn = self.fragment_registry[fragment_id]
        transition_params = self._handle_build_params(request, session_keys)

        loop = asyncio.get_running_loop()

        async def run_view_process(
            local_view_fn: ViewFn,
            transition_params: BuilderTranstionParams,
            local_fragment_id: Optional[str],
        ) -> ActionGenerator:
            event_queue: asyncio.Queue[Action] = asyncio.Queue()
            cancel_event = asyncio.Event()
            self.cancel_events[view_tasks_key] = cancel_event
            prev_root_element = transition_params.maybe_fragment_element or transition_params.root_element
            builder = self.BuilderClass(
                request,
                session_state=PropertyDict(transition_params.session_state, cancel_event=cancel_event),
                fragments=transition_params.fragments,
                initial_fragment_id=local_fragment_id,
                prev_root_element=prev_root_element,
                event_queue=event_queue,
                loop=loop,
                cancel_event=cancel_event,
                should_rerun_event=asyncio.Event(),
            )
            run_view_async = self._build_run_view_async(local_view_fn, builder, inject_builder, args, kwargs)
            view_task = asyncio.create_task(run_view_async(), name="rl_view_fn")
            start_time = time.monotonic()

            try:

                def handle_view_task_done(task: asyncio.Task) -> None:
                    if task.done():
                        with contextlib.suppress(asyncio.CancelledError, Exception):
                            _ = task.exception()
                    builder.handle_view_task_done()

                view_task.add_done_callback(handle_view_task_done)
                yield FreshBoundaryAction(
                    address=[-1],
                    target="app" if local_fragment_id is None else "fragment",
                )

                while True:
                    try:
                        self._check_if_view_task_failed(view_task)
                        if time.monotonic() - start_time > self.request_timeout:
                            raise StopException("View task timeout")
                        if cancel_event.is_set():
                            await view_task  # should raise asyncio.CancelledError
                            break
                        action = await asyncio.wait_for(event_queue.get(), timeout=0.5)

                        event_queue.task_done()
                        if isinstance(action, Exception):
                            raise action
                        if isinstance(action, ViewTaskDoneAction):
                            builder.on_end()
                            continue
                        if isinstance(action, RerunAction):
                            raise RerunException(
                                builder.session_state.get_data(),
                                scope=action.target or "app",
                            )
                        yield action
                        if isinstance(action, LastAction):
                            break
                    except asyncio.TimeoutError:
                        # ignore on purpose small timeout from event_queue.get()
                        pass
                builder.on_end()
                self.__write_session_state(session_keys, transition_params, builder, local_fragment_id)
            except (StopException, asyncio.CancelledError):
                self.__write_session_state(
                    session_keys,
                    transition_params,
                    builder,
                    local_fragment_id,
                )
            except EmptyReturnException:
                # No need to return anything
                pass
            except RerunException as e:
                (maybe_fragment_element, actual_view_fn, new_fragment_id) = (
                    (None, app_view_fn, None)
                    if e.scope == "app"
                    else (
                        transition_params.maybe_fragment_element,
                        local_view_fn,
                        local_fragment_id,
                    )
                )

                _transition_params = BuilderTranstionParams(
                    root_element=transition_params.root_element,
                    maybe_fragment_element=maybe_fragment_element,
                    session_state=e.state,
                    fragments=builder.get_fragments(),
                )
                cancel_event.set()
                await self._cancel_view_task(view_task)
                async for action in run_view_process(
                    actual_view_fn,
                    _transition_params,
                    new_fragment_id,
                ):
                    yield action
            finally:
                await self._cancel_view_task(view_task)
                self.cancel_events.pop(view_tasks_key, None)

        with warnings.catch_warnings():
            warnings.simplefilter("ignore", RuntimeWarning)
            try:
                async for action in run_view_process(view_fn, transition_params, fragment_id):
                    yield action
            except GeneratorExit:
                print("🔌 HTTP connection closed by client")
                raise

    async def handle_post_request_async_stream_jsonl(
        self,
        view_fn: ViewFn,
        request: RouteLitRequest,
        inject_builder: Optional[bool] = None,
        *args: Any,
        **kwargs: Any,
    ) -> AsyncGenerator[str, None]:
        async_gen = self.handle_post_request_async_stream(view_fn, request, inject_builder, *args, **kwargs)
        async for action in async_gen:
            yield json.dumps(asdict(action), default=json_default) + "\n"

    def handle_post_request_stream_jsonl(
        self,
        view_fn: ViewFn,
        request: RouteLitRequest,
        inject_builder: Optional[bool] = None,
        *args: Any,
        **kwargs: Any,
    ) -> Generator[str, None, None]:
        async_gen = self.handle_post_request_async_stream(view_fn, request, inject_builder, *args, **kwargs)
        for action in async_to_sync_generator(async_gen):
            yield json.dumps(asdict(action), default=json_default) + "\n"

    def handle_post_request_stream(
        self,
        view_fn: ViewFn,
        request: RouteLitRequest,
        inject_builder: Optional[bool] = None,
        *args: Any,
        **kwargs: Any,
    ) -> Generator[Action, None, None]:
        async_gen = self.handle_post_request_async_stream(view_fn, request, inject_builder, *args, **kwargs)
        yield from async_to_sync_generator(async_gen)

    def get_builder_class(self) -> Type[RouteLitBuilder]:
        return self.BuilderClass

    def _clear_session_state(self, session_keys: SessionKeys) -> None:
        self.session_storage.pop(session_keys.state_key, None)
        self.session_storage.pop(session_keys.ui_key, None)
        self.session_storage.pop(session_keys.fragment_addresses_key, None)
        self.session_storage.pop(session_keys.fragment_params_key, None)

    def _maybe_clear_session_state(self, request: RouteLitRequest, session_keys: SessionKeys) -> None:
        if request.get_query_param("__routelit_clear_session_state"):
            self._clear_session_state(session_keys)
            raise EmptyReturnException()

    def client_assets(self) -> List[ViteComponentsAssets]:
        """
        Render the vite assets for BuilderClass components.
        This function will return a list of ViteComponentsAssets.
        This should be called by the web framework to render the assets.
        """
        assets = []
        for static_path in self.BuilderClass.get_client_resource_paths():
            vite_assets = get_vite_components_assets(static_path["package_name"])
            assets.append(vite_assets)

        return assets

    def default_client_assets(self) -> ViteComponentsAssets:
        return get_vite_components_assets("routelit")

    def _register_fragment(self, key: str, fragment: Callable[[RouteLitBuilder], Any]) -> None:
        self.fragment_registry[key] = fragment

    def _preprocess_fragment_params(
        self, fragment_key: str, args: Tuple[Any, ...], kwargs: Dict[str, Any]
    ) -> Tuple[BuilderType, bool, Tuple[Any, ...], Dict[str, Any]]:
        is_builder_1st_arg = args is not None and len(args) > 0 and isinstance(args[0], RouteLitBuilder)
        rl: BuilderType = cast(RouteLitBuilder, args[0]) if is_builder_1st_arg else self.ui  # type: ignore[assignment]
        if is_builder_1st_arg:
            args = args[1:]
        is_fragment_request = rl.request.fragment_id is not None
        session_keys = rl.request.get_session_keys()
        if not is_fragment_request:
            fragment_params_by_key = {
                fragment_key: {
                    "args": args,
                    "kwargs": kwargs,
                }
            }
            all_fragment_params = self.session_storage.get(session_keys.fragment_params_key, {})
            self.session_storage[session_keys.fragment_params_key] = {
                **all_fragment_params,
                **fragment_params_by_key,
            }
        else:
            fragment_params = self.session_storage.get(session_keys.fragment_params_key, {}).get(fragment_key, {})
            args = fragment_params.get("args", [])
            kwargs = fragment_params.get("kwargs", {})

        return rl, is_builder_1st_arg, args, kwargs

    def fragment(self, key: Optional[str] = None) -> Callable[[ViewFn], ViewFn]:
        """
        Decorator to register a fragment.

        Args:
            key: The key to register the fragment with.

        Returns:
            The decorator function.

        Example:
            ```python
            from routelit import RouteLit, RouteLitBuilder

            rl = RouteLit()

            @rl.fragment()
            def my_fragment(ui: RouteLitBuilder):
                ui.text("Hello, world!")

            @rl.fragment()
            def my_fragment2():
                ui = rl.ui
                ui.text("Hello, world!")
            ```
        """

        def decorator_fragment(view_fn: ViewFn) -> ViewFn:
            fragment_key = key or view_fn.__name__

            @functools.wraps(view_fn)
            def wrapper(*args: Any, **kwargs: Any) -> Any:
                rl, is_builder_1st_arg, args, kwargs = self._preprocess_fragment_params(fragment_key, args, kwargs)

                with rl._fragment(fragment_key):
                    res = view_fn(rl, *args, **kwargs) if is_builder_1st_arg else view_fn(*args, **kwargs)
                    return res

            self._register_fragment(fragment_key, wrapper)
            return wrapper

        return decorator_fragment

    def _x_overlay_decor(
        self,
        builder_fn: Callable[[RouteLitBuilder], Callable[..., RouteLitBuilder]],
        overlay_type: str = "dialog",
    ) -> Callable[..., Callable[[ViewFn], ViewFn]]:
        def overlay_decor(*args: Any, **kwargs: Any) -> Callable[[ViewFn], ViewFn]:
            def decorator_overlay(view_fn: ViewFn) -> ViewFn:
                key = args[0] if len(args) > 0 else None
                fragment_key = key if isinstance(key, str) else view_fn.__name__
                overlay_key = f"{fragment_key}-{overlay_type}"
                overlay_upper_kwargs = kwargs

                @functools.wraps(view_fn)
                def wrapper(*args: Any, **kwargs: Any) -> Any:
                    rl, is_builder_1st_arg, args, kwargs = self._preprocess_fragment_params(fragment_key, args, kwargs)
                    with rl._fragment(fragment_key), builder_fn(rl)(overlay_key, **overlay_upper_kwargs):
                        res = view_fn(rl, *args, **kwargs) if is_builder_1st_arg else view_fn(*args, **kwargs)
                        return res

                self._register_fragment(fragment_key, wrapper)
                return wrapper

            return decorator_overlay

        return overlay_decor

    def _x_dialog_decor(
        self,
        builder_fn: Callable[[RouteLitBuilder], Callable[..., RouteLitBuilder]],
    ) -> Callable[..., Callable[[ViewFn], ViewFn]]:
        """Backward compatibility wrapper for _x_overlay_decor with dialog type."""
        return self._x_overlay_decor(builder_fn, overlay_type="dialog")

    def dialog(self, key: Optional[str] = None, **kwargs: Any) -> Callable[[ViewFn], ViewFn]:
        """Decorator to register a dialog.

        Args:
            key (Optional[str]): The key to register the dialog with.

        Returns:
            The decorator function.

        Example:
            ```python
            from routelit import RouteLit, RouteLitBuilder

            rl = RouteLit()

            @rl.dialog()
            def my_dialog(ui: RouteLitBuilder):
                ui.text("Hello, world!")

            def my_main_view(ui: RouteLitBuilder):
                if ui.button("Open dialog"):
                    my_dialog(ui)

            @rl.dialog()
            def my_dialog2():
                ui = rl.ui
                ui.text("Hello, world!")

            def my_main_view2():
                ui = rl.ui
                if ui.button("Open dialog"):
                    my_dialog2()
            ```
        """

        def dialog_builder(
            rl: RouteLitBuilder,
        ) -> Callable[..., RouteLitBuilder]:
            return rl._dialog

        return self._x_dialog_decor(dialog_builder)(key, **kwargs)

    def create_overlay_decorator(
        self, overlay_type: str, builder_method_name: Optional[str] = None
    ) -> Callable[..., Callable[[ViewFn], ViewFn]]:
        """Generic method to create custom overlay decorators.

        Args:
            overlay_type (str): The type of overlay (e.g., "popup", "sidebar", "sheet", etc.)
            builder_method_name (Optional[str]): The name of the builder method to use. Defaults to overlay_type or "_dialog"

        Returns:
            A decorator function for the specified overlay type.

        Example:
            ```python
            rl = RouteLit()

            # Create a custom overlay decorator
            popup = rl.create_overlay_decorator("popup", "popup")
            sheet = rl.create_overlay_decorator("sheet", "drawer")  # Use drawer method for sheet

            @popup()
            def my_popup(ui: RouteLitBuilder):
                ui.text("Hello from popup!")

            @sheet()
            def my_sheet(ui: RouteLitBuilder):
                ui.text("Hello from sheet!")
            ```
        """

        def overlay_decorator(key: Optional[str] = None, **kwargs: Any) -> Callable[[ViewFn], ViewFn]:
            def overlay_builder(
                rl: RouteLitBuilder,
            ) -> Callable[..., RouteLitBuilder]:
                method_name = builder_method_name or overlay_type
                if hasattr(rl, method_name):
                    return getattr(rl, method_name)  # type: ignore[no-any-return]
                else:
                    # Fallback to _dialog method
                    return rl._dialog

            return self._x_overlay_decor(overlay_builder, overlay_type=overlay_type)(key, **kwargs)

        return overlay_decorator

    def _build_run_view_async(
        self,
        view_fn: Callable[[RouteLitBuilder], Union[None, Awaitable[None]]],
        builder: BuilderType,
        inject_builder: bool,
        args: Tuple[Any, ...],
        kwargs: Dict[Any, Any],
    ) -> Callable[[], Coroutine[Any, Any, None]]:
        async def run_view_async() -> None:
            new_args = (builder, *args) if inject_builder else args
            with self._set_builder_context(builder):
                coro = (
                    view_fn(*new_args, **kwargs)
                    if asyncio.iscoroutinefunction(view_fn)
                    else asyncio.to_thread(view_fn, *new_args, **kwargs)
                )
                await coro

        return run_view_async

    def cache_data(
        self, func: Optional[Callable[..., Any]] = None
    ) -> Union[Callable[[Callable[..., Any]], Callable[..., Any]], Callable[..., Any]]:
        """
        Decorator to cache function results based on input parameters.
        Parameters starting with underscore are excluded from cache key generation.
        Supports both synchronous and asynchronous functions.

        Can be used with or without parentheses:
        @rl.cache_data() or @rl.cache_data

        Args:
            func: The function to be decorated (when used without parentheses)

        Returns:
            The decorated function that caches its results

        Example:
            ```python
            rl = RouteLit()

            @rl.cache_data()
            def expensive_computation(x, y, _debug=False):
                return x + y  # _debug parameter is excluded from cache key

            @rl.cache_data  # Also works without parentheses
            def another_function(a, b, _internal=None):
                return a * b

            @rl.cache_data()
            async def async_computation(x, y, _debug=False):
                return x + y  # Works with async functions too

            # First call will execute the function
            result1 = expensive_computation(1, 2, _debug=True)

            # Second call with same x, y but different _debug will return cached result
            result2 = expensive_computation(1, 2, _debug=False)  # Returns cached result

            # Call with different x, y will execute function again
            result3 = expensive_computation(2, 3, _debug=True)  # Executes function

            # Async functions work the same way
            result4 = await async_computation(1, 2, _debug=True)
            result5 = await async_computation(1, 2, _debug=False)  # Returns cached result
            ```
        """

        def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
            # Check if the function is async
            is_async = inspect.iscoroutinefunction(func)

            def _get_cache_key(*args: Any, **kwargs: Any) -> str:
                """Helper function to generate cache key from arguments."""
                # Get function signature to identify parameter names
                sig = inspect.signature(func)
                bound_args = sig.bind(*args, **kwargs)
                bound_args.apply_defaults()

                # Filter out parameters that start with underscore
                cache_params = {}
                for param_name, param_value in bound_args.arguments.items():
                    if not param_name.startswith("_"):
                        cache_params[param_name] = param_value

                # Generate cache key from function name and filtered parameters
                cache_key_data = {"func_name": func.__name__, "params": cache_params}
                return hashlib.md5(json.dumps(cache_key_data, sort_keys=True, default=str).encode()).hexdigest()  # noqa: S324; type: ignore[hashlib-insecure-hash-function]

            if is_async:

                @functools.wraps(func)
                async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
                    cache_key = _get_cache_key(*args, **kwargs)

                    # Check if result is already cached
                    if cache_key in self.cache_backend:
                        return self.cache_backend[cache_key]

                    # Execute async function and cache result
                    result = await func(*args, **kwargs)
                    self.cache_backend[cache_key] = result
                    return result

                return async_wrapper
            else:

                @functools.wraps(func)
                def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
                    cache_key = _get_cache_key(*args, **kwargs)

                    # Check if result is already cached
                    if cache_key in self.cache_backend:
                        return self.cache_backend[cache_key]

                    # Execute function and cache result
                    result = func(*args, **kwargs)
                    self.cache_backend[cache_key] = result
                    return result

                return sync_wrapper

        # Handle both @cache_data and @cache_data() usage patterns
        if func is None:
            return decorator
        else:
            return decorator(func)

    @staticmethod
    def _check_if_view_task_failed(view_task: asyncio.Task) -> None:
        if view_task.done() and view_task.exception() is not None:
            exception = view_task.exception()
            raise exception  # type: ignore[misc]

    @staticmethod
    async def _cancel_view_task(
        view_task: asyncio.Task, timeout: float = 2.0, suppress_cancel_error: bool = True
    ) -> None:
        if not view_task.done():
            view_task.cancel()
            if suppress_cancel_error:
                with contextlib.suppress(asyncio.CancelledError):
                    await asyncio.wait_for(view_task, timeout=timeout)
            else:
                await asyncio.wait_for(view_task, timeout=timeout)

ui property

The current builder instance. Use this in conjunction with response(..., inject_builder=False)

Example

rl = RouteLit()

def my_view():
    rl.ui.text("Hello, world!")

request = ...
response = rl.response(my_view, request, inject_builder=False)

cache_data(func=None)

Decorator to cache function results based on input parameters. Parameters starting with underscore are excluded from cache key generation. Supports both synchronous and asynchronous functions.

Can be used with or without parentheses: @rl.cache_data() or @rl.cache_data

Parameters:

Name	Type	Description	Default
func	Optional[Callable[..., Any]]	The function to be decorated (when used without parentheses)	None

Returns:

Type	Description
Union[Callable[[Callable[..., Any]], Callable[..., Any]], Callable[..., Any]]	The decorated function that caches its results

Example

rl = RouteLit()

@rl.cache_data()
def expensive_computation(x, y, _debug=False):
    return x + y  # _debug parameter is excluded from cache key

@rl.cache_data  # Also works without parentheses
def another_function(a, b, _internal=None):
    return a * b

@rl.cache_data()
async def async_computation(x, y, _debug=False):
    return x + y  # Works with async functions too

# First call will execute the function
result1 = expensive_computation(1, 2, _debug=True)

# Second call with same x, y but different _debug will return cached result
result2 = expensive_computation(1, 2, _debug=False)  # Returns cached result

# Call with different x, y will execute function again
result3 = expensive_computation(2, 3, _debug=True)  # Executes function

# Async functions work the same way
result4 = await async_computation(1, 2, _debug=True)
result5 = await async_computation(1, 2, _debug=False)  # Returns cached result

Source code in src/routelit/routelit.py

def cache_data(
    self, func: Optional[Callable[..., Any]] = None
) -> Union[Callable[[Callable[..., Any]], Callable[..., Any]], Callable[..., Any]]:
    """
    Decorator to cache function results based on input parameters.
    Parameters starting with underscore are excluded from cache key generation.
    Supports both synchronous and asynchronous functions.

    Can be used with or without parentheses:
    @rl.cache_data() or @rl.cache_data

    Args:
        func: The function to be decorated (when used without parentheses)

    Returns:
        The decorated function that caches its results

    Example:
        ```python
        rl = RouteLit()

        @rl.cache_data()
        def expensive_computation(x, y, _debug=False):
            return x + y  # _debug parameter is excluded from cache key

        @rl.cache_data  # Also works without parentheses
        def another_function(a, b, _internal=None):
            return a * b

        @rl.cache_data()
        async def async_computation(x, y, _debug=False):
            return x + y  # Works with async functions too

        # First call will execute the function
        result1 = expensive_computation(1, 2, _debug=True)

        # Second call with same x, y but different _debug will return cached result
        result2 = expensive_computation(1, 2, _debug=False)  # Returns cached result

        # Call with different x, y will execute function again
        result3 = expensive_computation(2, 3, _debug=True)  # Executes function

        # Async functions work the same way
        result4 = await async_computation(1, 2, _debug=True)
        result5 = await async_computation(1, 2, _debug=False)  # Returns cached result
        ```
    """

    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
        # Check if the function is async
        is_async = inspect.iscoroutinefunction(func)

        def _get_cache_key(*args: Any, **kwargs: Any) -> str:
            """Helper function to generate cache key from arguments."""
            # Get function signature to identify parameter names
            sig = inspect.signature(func)
            bound_args = sig.bind(*args, **kwargs)
            bound_args.apply_defaults()

            # Filter out parameters that start with underscore
            cache_params = {}
            for param_name, param_value in bound_args.arguments.items():
                if not param_name.startswith("_"):
                    cache_params[param_name] = param_value

            # Generate cache key from function name and filtered parameters
            cache_key_data = {"func_name": func.__name__, "params": cache_params}
            return hashlib.md5(json.dumps(cache_key_data, sort_keys=True, default=str).encode()).hexdigest()  # noqa: S324; type: ignore[hashlib-insecure-hash-function]

        if is_async:

            @functools.wraps(func)
            async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
                cache_key = _get_cache_key(*args, **kwargs)

                # Check if result is already cached
                if cache_key in self.cache_backend:
                    return self.cache_backend[cache_key]

                # Execute async function and cache result
                result = await func(*args, **kwargs)
                self.cache_backend[cache_key] = result
                return result

            return async_wrapper
        else:

            @functools.wraps(func)
            def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
                cache_key = _get_cache_key(*args, **kwargs)

                # Check if result is already cached
                if cache_key in self.cache_backend:
                    return self.cache_backend[cache_key]

                # Execute function and cache result
                result = func(*args, **kwargs)
                self.cache_backend[cache_key] = result
                return result

            return sync_wrapper

    # Handle both @cache_data and @cache_data() usage patterns
    if func is None:
        return decorator
    else:
        return decorator(func)

client_assets()

Render the vite assets for BuilderClass components. This function will return a list of ViteComponentsAssets. This should be called by the web framework to render the assets.

Source code in src/routelit/routelit.py

def client_assets(self) -> List[ViteComponentsAssets]:
    """
    Render the vite assets for BuilderClass components.
    This function will return a list of ViteComponentsAssets.
    This should be called by the web framework to render the assets.
    """
    assets = []
    for static_path in self.BuilderClass.get_client_resource_paths():
        vite_assets = get_vite_components_assets(static_path["package_name"])
        assets.append(vite_assets)

    return assets

create_overlay_decorator(overlay_type, builder_method_name=None)

Generic method to create custom overlay decorators.

Parameters:

Name	Type	Description	Default
overlay_type	str	The type of overlay (e.g., "popup", "sidebar", "sheet", etc.)	required
builder_method_name	Optional[str]	The name of the builder method to use. Defaults to overlay_type or "_dialog"	None

Returns:

Type	Description
Callable[..., Callable[[ViewFn], ViewFn]]	A decorator function for the specified overlay type.

Example

rl = RouteLit()

# Create a custom overlay decorator
popup = rl.create_overlay_decorator("popup", "popup")
sheet = rl.create_overlay_decorator("sheet", "drawer")  # Use drawer method for sheet

@popup()
def my_popup(ui: RouteLitBuilder):
    ui.text("Hello from popup!")

@sheet()
def my_sheet(ui: RouteLitBuilder):
    ui.text("Hello from sheet!")

Source code in src/routelit/routelit.py

def create_overlay_decorator(
    self, overlay_type: str, builder_method_name: Optional[str] = None
) -> Callable[..., Callable[[ViewFn], ViewFn]]:
    """Generic method to create custom overlay decorators.

    Args:
        overlay_type (str): The type of overlay (e.g., "popup", "sidebar", "sheet", etc.)
        builder_method_name (Optional[str]): The name of the builder method to use. Defaults to overlay_type or "_dialog"

    Returns:
        A decorator function for the specified overlay type.

    Example:
        ```python
        rl = RouteLit()

        # Create a custom overlay decorator
        popup = rl.create_overlay_decorator("popup", "popup")
        sheet = rl.create_overlay_decorator("sheet", "drawer")  # Use drawer method for sheet

        @popup()
        def my_popup(ui: RouteLitBuilder):
            ui.text("Hello from popup!")

        @sheet()
        def my_sheet(ui: RouteLitBuilder):
            ui.text("Hello from sheet!")
        ```
    """

    def overlay_decorator(key: Optional[str] = None, **kwargs: Any) -> Callable[[ViewFn], ViewFn]:
        def overlay_builder(
            rl: RouteLitBuilder,
        ) -> Callable[..., RouteLitBuilder]:
            method_name = builder_method_name or overlay_type
            if hasattr(rl, method_name):
                return getattr(rl, method_name)  # type: ignore[no-any-return]
            else:
                # Fallback to _dialog method
                return rl._dialog

        return self._x_overlay_decor(overlay_builder, overlay_type=overlay_type)(key, **kwargs)

    return overlay_decorator

dialog(key=None, **kwargs)

Decorator to register a dialog.

Parameters:

Name	Type	Description	Default
key	Optional[str]	The key to register the dialog with.	None

Returns:

Type	Description
Callable[[ViewFn], ViewFn]	The decorator function.

Example

from routelit import RouteLit, RouteLitBuilder

rl = RouteLit()

@rl.dialog()
def my_dialog(ui: RouteLitBuilder):
    ui.text("Hello, world!")

def my_main_view(ui: RouteLitBuilder):
    if ui.button("Open dialog"):
        my_dialog(ui)

@rl.dialog()
def my_dialog2():
    ui = rl.ui
    ui.text("Hello, world!")

def my_main_view2():
    ui = rl.ui
    if ui.button("Open dialog"):
        my_dialog2()

Source code in src/routelit/routelit.py

def dialog(self, key: Optional[str] = None, **kwargs: Any) -> Callable[[ViewFn], ViewFn]:
    """Decorator to register a dialog.

    Args:
        key (Optional[str]): The key to register the dialog with.

    Returns:
        The decorator function.

    Example:
        ```python
        from routelit import RouteLit, RouteLitBuilder

        rl = RouteLit()

        @rl.dialog()
        def my_dialog(ui: RouteLitBuilder):
            ui.text("Hello, world!")

        def my_main_view(ui: RouteLitBuilder):
            if ui.button("Open dialog"):
                my_dialog(ui)

        @rl.dialog()
        def my_dialog2():
            ui = rl.ui
            ui.text("Hello, world!")

        def my_main_view2():
            ui = rl.ui
            if ui.button("Open dialog"):
                my_dialog2()
        ```
    """

    def dialog_builder(
        rl: RouteLitBuilder,
    ) -> Callable[..., RouteLitBuilder]:
        return rl._dialog

    return self._x_dialog_decor(dialog_builder)(key, **kwargs)

fragment(key=None)

Decorator to register a fragment.

Parameters:

Name	Type	Description	Default
key	Optional[str]	The key to register the fragment with.	None

Returns:

Type	Description
Callable[[ViewFn], ViewFn]	The decorator function.

Example

from routelit import RouteLit, RouteLitBuilder

rl = RouteLit()

@rl.fragment()
def my_fragment(ui: RouteLitBuilder):
    ui.text("Hello, world!")

@rl.fragment()
def my_fragment2():
    ui = rl.ui
    ui.text("Hello, world!")

Source code in src/routelit/routelit.py

def fragment(self, key: Optional[str] = None) -> Callable[[ViewFn], ViewFn]:
    """
    Decorator to register a fragment.

    Args:
        key: The key to register the fragment with.

    Returns:
        The decorator function.

    Example:
        ```python
        from routelit import RouteLit, RouteLitBuilder

        rl = RouteLit()

        @rl.fragment()
        def my_fragment(ui: RouteLitBuilder):
            ui.text("Hello, world!")

        @rl.fragment()
        def my_fragment2():
            ui = rl.ui
            ui.text("Hello, world!")
        ```
    """

    def decorator_fragment(view_fn: ViewFn) -> ViewFn:
        fragment_key = key or view_fn.__name__

        @functools.wraps(view_fn)
        def wrapper(*args: Any, **kwargs: Any) -> Any:
            rl, is_builder_1st_arg, args, kwargs = self._preprocess_fragment_params(fragment_key, args, kwargs)

            with rl._fragment(fragment_key):
                res = view_fn(rl, *args, **kwargs) if is_builder_1st_arg else view_fn(*args, **kwargs)
                return res

        self._register_fragment(fragment_key, wrapper)
        return wrapper

    return decorator_fragment

handle_get_request(view_fn, request, **kwargs)

" Handle a GET request. If the session state is present, it will be cleared. The head title and description can be passed as kwargs. Example:

return routelit_adapter.response(build_signup_view, head_title="Signup", head_description="Signup page")

Parameters:

Name	Type	Description	Default
request	RouteLitRequest	The request object.	required
**kwargs	Dict[str, Any]	Additional keyword arguments. head_title (Optional[str]): The title of the head. head_description (Optional[str]): The description of the head.	{}

Returns:

Name	Type	Description
RouteLitResponse	RouteLitResponse	The response object.

Source code in src/routelit/routelit.py

def handle_get_request(
    self,
    view_fn: ViewFn,
    request: RouteLitRequest,
    **kwargs: Any,
) -> RouteLitResponse:
    """ "
    Handle a GET request.
    If the session state is present, it will be cleared.
    The head title and description can be passed as kwargs.
    Example:
    ```python
    return routelit_adapter.response(build_signup_view, head_title="Signup", head_description="Signup page")
    ```

    Args:
        request (RouteLitRequest): The request object.
        **kwargs (Dict[str, Any]): Additional keyword arguments.
            head_title (Optional[str]): The title of the head.
            head_description (Optional[str]): The description of the head.

    Returns:
        RouteLitResponse: The response object.
    """
    session_keys = request.get_session_keys()
    (
        ui_key,
        state_key,
        fragment_addresses_key,
        fragment_params_key,
        view_tasks_key,
    ) = session_keys
    view_tasks_key = build_view_task_key(view_fn, request.fragment_id, session_keys)
    if view_tasks_key in self.cancel_events:
        # send cancel event to the view task beforehand
        self.cancel_events[view_tasks_key].set()

    if state_key in self.session_storage:
        self.session_storage.pop(ui_key, None)
        self.session_storage.pop(state_key, None)
        self.session_storage.pop(fragment_addresses_key, None)
        self.session_storage.pop(fragment_params_key, None)
    return RouteLitResponse(
        elements=[],
        head=Head(
            title=kwargs.get("head_title"),
            description=kwargs.get("head_description"),
        ),
    )

response(view_fn, request, inject_builder=None, *args, **kwargs)

Handle the request and return the response.

Parameters:

Name	Type	Description	Default
view_fn	ViewFn	(Callable[[RouteLitBuilder], Any]) The view function to handle the request.	required
request	RouteLitRequest	The request object.	required
**kwargs	Dict[str, Any]	Additional keyword arguments.	{}

Returns:

Type	Description
Union[RouteLitResponse, Dict[str, Any]]	RouteLitResponse | Dict[str, Any]: The response object. where Dict[str, Any] is a dictionary that contains the following keys: actions (List[Action]), target (Literal["app", "fragment"])

Example

from routelit import RouteLit, RouteLitBuilder

rl = RouteLit()

def my_view(rl: RouteLitBuilder):
    rl.text("Hello, world!")

request = ...
response = rl.response(my_view, request)

# example with dependency
def my_view(rl: RouteLitBuilder, name: str):
    rl.text(f"Hello, {name}!")

request = ...
response = rl.response(my_view, request, name="John")

Source code in src/routelit/routelit.py

def response(
    self,
    view_fn: ViewFn,
    request: RouteLitRequest,
    inject_builder: Optional[bool] = None,
    *args: Any,
    **kwargs: Any,
) -> Union[RouteLitResponse, Dict[str, Any]]:
    """Handle the request and return the response.

    Args:
        view_fn (ViewFn): (Callable[[RouteLitBuilder], Any]) The view function to handle the request.
        request (RouteLitRequest): The request object.
        **kwargs (Dict[str, Any]): Additional keyword arguments.

    Returns:
        RouteLitResponse | Dict[str, Any]:
            The response object.
            where Dict[str, Any] is a dictionary that contains the following keys:
            actions (List[Action]), target (Literal["app", "fragment"])

    Example:
        ```python
        from routelit import RouteLit, RouteLitBuilder

        rl = RouteLit()

        def my_view(rl: RouteLitBuilder):
            rl.text("Hello, world!")

        request = ...
        response = rl.response(my_view, request)

        # example with dependency
        def my_view(rl: RouteLitBuilder, name: str):
            rl.text(f"Hello, {name}!")

        request = ...
        response = rl.response(my_view, request, name="John")
        ```
    """
    if request.method == "GET":
        return self.handle_get_request(view_fn, request, **kwargs)
    elif request.method == "POST":
        return self.handle_post_request(view_fn, request, inject_builder, *args, **kwargs)
    else:
        # set custom exception for unsupported request method
        raise ValueError(request.method)

Builder Module

ColumnsGap = Literal['none', 'small', 'medium', 'large'] module-attribute

The gap between the columns.

TextInputType = Literal['text', 'number', 'email', 'password', 'search', 'tel', 'url', 'date', 'time', 'datetime-local', 'month', 'week'] module-attribute

The type of the text input.

VerticalAlignment = Literal['top', 'center', 'bottom'] module-attribute

The vertical alignment of the elements.

RouteLitBuilder

Source code in src/routelit/builder.py

class RouteLitBuilder:
    static_assets_targets: ClassVar[List[AssetTarget]] = []

    def __init__(
        self,
        request: RouteLitRequest,
        session_state: PropertyDict,
        fragments: MutableMapping[str, List[int]],
        prev_root_element: Optional[RouteLitElement] = None,
        cancel_event: Optional[asyncio.Event] = None,
        should_rerun_event: Optional[asyncio.Event] = None,
        initial_fragment_id: Optional[str] = None,
        initial_target: Optional[BuilderTarget] = None,
        event_queue: Optional[asyncio.Queue] = None,
        loop: Optional[asyncio.AbstractEventLoop] = None,
        parent_element: Optional[RouteLitElement] = None,
        parent_builder: Optional["RouteLitBuilder"] = None,
        last_fragment_address: Optional[List[int]] = None,
    ):
        self.request = request
        self.initial_fragment_id = initial_fragment_id
        self.last_fragment_address = last_fragment_address
        self.initial_target = (
            initial_target if initial_target is not None else "app" if initial_fragment_id is None else "fragment"
        )
        self.fragments = fragments
        self.prev_root_element = prev_root_element
        self.has_prev_diff = False
        self._event_queue = event_queue
        self._loop = loop
        self.cancel_event = cancel_event
        self.head: Optional[Head] = None
        self._parent_element = parent_element or RouteLitElement.create_root_element()
        self._root_element = self._parent_element
        self.session_state = session_state
        self.parent_builder = parent_builder
        self.active_child_builder: Optional[RouteLitBuilder] = None
        self._prev_active_child_builder: Optional[RouteLitBuilder] = None
        self.q_by_name: Dict[str, int] = {}
        self.should_rerun_event = should_rerun_event
        if self._root_element.name == RouteLitElement.ROOT_ELEMENT_NAME and initial_fragment_id is None:
            self._on_init()

    def _on_init(self) -> None:
        pass

    def get_request(self) -> RouteLitRequest:
        return self.request

    def _get_prefix(self) -> str:
        return self.active_child_builder._get_prefix() if self.active_child_builder else self._parent_element.key

    def _schedule_event(self, event_data: Action) -> bool:
        """
        Schedule an event to be put in the queue from sync context
        Returns True if the event was scheduled, False otherwise.
        """

        if not (self._event_queue and self._loop):
            # Nothing to do - no queue/loop configured.
            return False

        # Guard against scheduling onto a closed loop (can happen during
        # teardown).
        if self._loop.is_closed():
            return False

        self._loop.call_soon_threadsafe(self._event_queue.put_nowait, event_data)
        return True

    @property
    def elements(self) -> List[RouteLitElement]:
        return self._root_element.get_children()

    @property
    def root_element(self) -> RouteLitElement:
        if self.initial_fragment_id and self._root_element.children:
            return self._root_element.children[0]
        return self._root_element

    @property
    def elements_count(self) -> int:
        return len(self.elements)

    @property
    def address(self) -> List[int]:
        return self._root_element.address or []

    def _get_next_address(self) -> List[int]:
        if self.active_child_builder:
            return self.active_child_builder._get_next_address()
        else:
            return [*self.address, self.elements_count]

    def _get_last_address(self) -> List[int]:
        if self.active_child_builder:
            return self.active_child_builder._get_last_address()
        else:
            return [*self.address, self.elements_count - 1]

    def _build_nested_builder(self, element: RouteLitElement) -> "RouteLitBuilder":
        if element.address is None:
            element.address = self._get_last_address()
        prev_root_element = (
            self.prev_root_element
            if self.prev_root_element and self.prev_root_element.key == element.key
            else get_element_at_address(self.prev_root_element, element.address)
            if self.prev_root_element
            else None
        )
        last_fragment_address = element.address if element.name == "fragment" else self.last_fragment_address
        builder = self.__class__(
            self.request,
            fragments=self.fragments,
            event_queue=self._event_queue,
            loop=self._loop,
            cancel_event=self.cancel_event,
            session_state=self.session_state,
            parent_element=element,
            parent_builder=self,
            initial_target=self.initial_target,
            prev_root_element=prev_root_element,
            should_rerun_event=self.should_rerun_event,
            last_fragment_address=last_fragment_address,
        )
        return builder

    def _get_parent_form_id(self) -> Optional[str]:
        if self._parent_element and self._parent_element.name == "form":
            return self._parent_element.key
        if self.active_child_builder:
            return self.active_child_builder._get_parent_form_id()
        if self._prev_active_child_builder:
            return self._prev_active_child_builder._get_parent_form_id()
        return None

    def _new_text_id(self, name: str) -> str:
        prefix = self._get_prefix()
        q_by_name = self.active_child_builder.q_by_name if self.active_child_builder else self.q_by_name
        if name in q_by_name:
            q_by_name[name] += 1
        else:
            q_by_name[name] = 1
        key = f"{prefix}_{name}_{q_by_name[name]}"
        return key

    def _new_widget_id(self, name: str, label: str) -> str:
        hashed = hashlib.sha256(label.encode()).hexdigest()[:8]
        prefix = self._get_prefix()
        return f"{prefix}_{name}_{hashed}"

    def _maybe_get_event(self, component_id: str) -> Optional[RouteLitEvent]:
        event = self.request.ui_event
        if (
            event
            and event.get("type") == "submit"
            and (event_form_id := event.get("formId"))
            and self.session_state.get("__ignore_submit") != event_form_id
            and (form_id := self._get_parent_form_id())
            and event_form_id == form_id
        ):
            events = self.session_state.get(f"__events4later_{form_id}", {})
            self.session_state.pop(f"__events4later_{form_id}", None)
            self.session_state[f"__events_{form_id}"] = events
            self.session_state["__ignore_submit"] = form_id
            self.rerun(scope="app", clear_event=False)

        if event and event.get("componentId") == component_id:
            return event
        if (
            (form_id := self._get_parent_form_id())
            and (events := self.session_state.get(f"__events_{form_id}", {}))
            and component_id in events
        ):
            _event: RouteLitEvent = events[component_id]
            events.pop(component_id, None)
            self.session_state[f"__events_{form_id}"] = events
            return _event
        return None

    def _get_event_value(self, component_id: str, event_type: str, attribute: Optional[str] = None) -> Tuple[bool, Any]:
        """
        Check if the last event is of the given type and component_id.
        If attribute is not None, check if the event has the given attribute.
        Returns a tuple of (has_event, event_data).
        """
        event = self._maybe_get_event(component_id)
        if event is not None and event.get("type") == event_type:
            if attribute is None:
                return True, event["data"]
            else:
                return True, event["data"].get(attribute)
        return False, None

    def _append_element(self, element: RouteLitElement) -> None:
        """
        Append an element to the current builder.
        Returns the index of the element in the builder.
        Do not use this method directly, use the other methods instead, unless you are creating a custom element.
        """
        if self.active_child_builder:
            self.active_child_builder._append_element(element)
            return

        # do not append elements if the builder should rerun (when streaming)
        if self.should_rerun_event and self.should_rerun_event.is_set():
            return

        if self.cancel_event and self.cancel_event.is_set():
            raise StopException("Builder cancelled")

        element.props = remove_none_values(element.props)
        self._parent_element.append_child(element)

        if element.name == "fragment" and element.key != self.initial_fragment_id and element.address is not None:
            self.fragments[element.key] = element.address

        # skip sending action for fragment as root
        if self.initial_target == "fragment" and element.name == "fragment" and self.initial_fragment_id is not None:
            return

        # skip the first address for fragment as root
        address = self._get_last_address()[1:] if self.initial_target == "fragment" else self._get_last_address()

        # check if the element is the same as the previous one
        if (
            self.prev_root_element is not None
            and self.prev_root_element.children is not None
            and len(address) > 0
            and address[-1] < len(self.prev_root_element.children)
            and (prev_element := self.prev_root_element.children[address[-1]])
            and prev_element.key == element.key
            and prev_element.props == element.props
        ):
            self._schedule_event(NoChangeAction(address=address, target=self.initial_target))
            return

        new_element = element.to_dict()
        if element.name == "fragment" and self.last_fragment_address is not None and element.address is not None:
            new_element["address"] = element.address[len(self.last_fragment_address) - 1 :]

        self._schedule_event(
            SetAction(
                element=new_element,
                key=element.key,
                address=address,
                target=self.initial_target,
            )
        )

    def _add_non_widget(self, element: RouteLitElement) -> RouteLitElement:
        self._append_element(element)
        return element

    def _add_widget(self, element: RouteLitElement) -> None:
        self._append_element(element)

    def create_element(
        self,
        name: str,
        key: Optional[str] = None,
        props: Optional[Dict[str, Any]] = None,
        children: Optional[List[RouteLitElement]] = None,
        address: Optional[List[int]] = None,
        virtual: Optional[bool] = None,
        **kwargs: Any,
    ) -> RouteLitElement:
        return RouteLitElement(
            key=key or hashlib.sha256(name.encode()).hexdigest()[:8],
            name=name,
            props={**(props or {}), **kwargs},
            children=children,
            address=address,
            virtual=virtual,
        )

    def _create_element(
        self,
        name: str,
        key: str,
        props: Optional[Dict[str, Any]] = None,
        children: Optional[List[RouteLitElement]] = None,
        address: Optional[List[int]] = None,
        virtual: Optional[bool] = None,
    ) -> RouteLitElement:
        element = RouteLitElement(
            key=key,
            name=name,
            props=props or {},
            children=children,
            address=address,
            virtual=virtual,
        )
        self._add_widget(element)
        return element

    def _fragment(self, key: Optional[str] = None) -> "RouteLitBuilder":
        key = key or self._new_text_id("fragment")
        fragment = self._create_element(
            name="fragment",
            key=key,
            props={"id": key},
            address=self._get_next_address(),
            virtual=True,
        )
        return self._build_nested_builder(fragment)

    def _x_file_input(
        self,
        element_type: str,
        key: str,
        *,
        multiple_attr: str = "multiple",
        multiple: Optional[bool] = False,
        on_change: Optional[Callable[[Union[IOBase, List[IOBase]]], None]] = None,
        **kwargs: Any,
    ) -> Union[IOBase, List[IOBase], None]:
        value = self.session_state.get(key)
        has_changed, maybe_files = self._get_event_value(key, "change", "files")
        if has_changed:
            if multiple is not True and isinstance(maybe_files, list):
                # Single file mode (multiple=False or multiple=None/default)
                value = maybe_files[0] if len(maybe_files) > 0 else None
            else:
                value = maybe_files
            self.session_state[key] = value
            if on_change:
                on_change(value)
        # ensure the value is seeked to the beginning
        if value is not None and isinstance(value, IOBase):
            value.seek(0)
        if value is not None and isinstance(value, list):
            for file in value:
                file.seek(0)
        self._create_element(
            name=element_type,
            key=key,
            props={"id": key, multiple_attr: multiple, **kwargs},
        )
        return cast(Union[IOBase, List[IOBase]], value)

    @overload
    def file_input(
        self,
        label: str,
        *,
        key: Optional[str] = None,
        accept_multiple_files: Literal[True],
        accept: Optional[str] = None,
        on_change: Optional[Callable[[List[IOBase]], None]] = None,
        **kwargs: Any,
    ) -> Optional[List[IOBase]]: ...

    @overload
    def file_input(
        self,
        label: str,
        *,
        key: Optional[str] = None,
        accept_multiple_files: Literal[False] = ...,
        accept: Optional[str] = None,
        on_change: Optional[Callable[[IOBase], None]] = None,
        **kwargs: Any,
    ) -> Optional[IOBase]: ...

    def file_input(  # type: ignore[misc]
        self,
        label: str,
        *,
        key: Optional[str] = None,
        accept_multiple_files: Optional[bool] = None,
        accept: Optional[str] = None,
        on_change: Optional[Callable[[Union[IOBase, List[IOBase]]], None]] = None,
        **kwargs: Any,
    ) -> Union[IOBase, List[IOBase], None]:
        """
        Creates a file input component.
        You'll get the bytes of the uploaded file (BytesIO object).
        Useful for handling files in memory. Not suitable for large files.

        Args:
            label (str): The label of the file input.
            key (Optional[str]): The key of the file input.
            accept_multiple_files (Optional[bool]): Whether to accept multiple files.
            accept (Optional[str]): The accept attribute of the file input.
            kwargs (Dict[str, Any]): The keyword arguments to pass to the file input.

        Returns:
            Optional[IOBase|List[IOBase]]: The file input component.

        Example:
            ```python
            # Multiple files
            files = ui.file_input("Files", accept_multiple_files=True, accept="text/plain, .txt")
            if files:
                for file in files:
                    ui.text(file.read().decode("utf-8"))

            # Single file
            single_file = ui.file_input("Single File", accept_multiple_files=False, accept="text/plain, .txt")
            if single_file:
                ui.text(single_file.read().decode("utf-8"))

            # Handling images
            import base64
            image = ui.file_input("Image", accept="image/png")
            if image:
                ui.image(src=f"data:image/png;base64,{base64.b64encode(image.read()).decode('utf-8')}", width=128)
            if image and ui.button("Save image"):
                with open("image.png", "wb") as f:
                    f.write(image.read())
                    ui.text("Image saved")

            def on_file_change(value: Union[IOBase, List[IOBase]]):
                ui.text(f"File changed: {value}")
            file_input = ui.file_input("File", on_change=on_file_change)
            ```
        """
        return self._x_file_input(
            "input-file",
            key or self._new_widget_id("input-file", label),
            multiple=accept_multiple_files,
            label=label,
            accept=accept,
            on_change=on_change,
            **kwargs,
        )

    def _x_dialog(
        self,
        element_type: str,
        key: str,
        *,
        on_close: Optional[Callable[[], Optional[bool]]] = None,
        **kwargs: Any,
    ) -> "RouteLitBuilder":
        is_closed, _ = self._get_event_value(key, "close")
        if is_closed:
            should_rerun = True
            if on_close and (result := on_close()) is not None:
                should_rerun = result
            if should_rerun:
                self.rerun(scope="app")
        dialog = self._create_element(
            name=element_type,
            key=key,
            props={"id": key, **kwargs},
            virtual=True,
        )
        return self._build_nested_builder(dialog)

    def _create_builder_element(
        self,
        name: str,
        key: str,
        props: Optional[Dict[str, Any]] = None,
        address: Optional[List[int]] = None,
        virtual: Optional[bool] = None,
    ) -> "RouteLitBuilder":
        element = self._create_element(
            name=name,
            key=key,
            props=props or {},
            address=address,
            virtual=virtual,
        )
        return self._build_nested_builder(element)

    def _dialog(self, key: Optional[str] = None, **kwargs: Any) -> "RouteLitBuilder":
        return self._x_dialog(
            "dialog",
            key or self._new_text_id("dialog"),
            open=True,
            closable=True,
            **kwargs,
        )

    def form(self, key: str) -> "RouteLitBuilder":
        """
        Creates a form area that do not process the inputs values contained in it until the form is submitted.
        Use `button(..., event_name="submit")` or `form_submit_button()` to submit the form.

        Args:
            key (str): The key of the form.

        Returns:
            RouteLitBuilder: A builder for the form.

        Example:
            ```python
            with ui.form("login"):
                username = ui.text_input("Username")
                password = ui.text_input("Password", type="password")
                is_submitted = ui.form_submit_button("Login") # or ui.button("Login", event_name="submit")
                if is_submitted:
                    ui.text(f"Login successful for {username}")
            ```
        """
        form = self._create_element(
            name="form",
            key=key,
            props={"id": key},
            virtual=True,
        )
        return self._build_nested_builder(form)

    def link(
        self,
        href: str,
        text: str = "",
        *,
        replace: bool = False,
        is_external: bool = False,
        key: Optional[str] = None,
        rl_element_type: str = "link",
        rl_text_attr: str = "text",
        rl_virtual: Optional[bool] = None,
        **kwargs: Any,
    ) -> RouteLitElement:
        """
        Creates a link component. Use this to navigate to a different page.

        Args:
            href (str): The href of the link.
            text (str): The text of the link.
            replace (bool): Whether to replace the current page from the history.
            is_external (bool): Whether the link is external to the current app.
            key (Optional[str]): The key of the link.
            kwargs (Dict[str, Any]): The keyword arguments to pass to the link.

        Example:
            ```python
            ui.link("/signup", text="Signup")
            ui.link("/login", text="Login", replace=True)
            ui.link("https://www.google.com", text="Google", is_external=True)
            ```
        """
        new_element = self._create_element(
            name=rl_element_type,
            key=key or self._new_text_id(rl_element_type),
            props={
                "href": href,
                "replace": replace,
                "isExternal": is_external,
                rl_text_attr: text,
                **kwargs,
            },
            virtual=rl_virtual,
        )
        return new_element

    def link_area(
        self,
        href: str,
        replace: bool = False,
        is_external: bool = False,
        key: Optional[str] = None,
        className: Optional[str] = None,
        **kwargs: Any,
    ) -> "RouteLitBuilder":
        """
        Creates a link area component. Use this element which is a container of other elements.

        Args:
            href (str): The href of the link.
            replace (bool): Whether to replace the current page.
            is_external (bool): Whether the link is external.
            key (Optional[str]): The key of the link area.
            className (Optional[str]): The class name of the link area.
            kwargs (Dict[str, Any]): The keyword arguments to pass to the link area.

        Example:
            ```python
            with ui.link_area("https://www.google.com"):
                with ui.flex(direction="row", gap="small"):
                    ui.image("https://www.google.com/favicon.ico", width="24px", height="24px")
                    ui.text("Google")
            ```
        """
        link_element = self.link(
            href,
            replace=replace,
            is_external=is_external,
            key=key,
            className=f"rl-no-link-decoration {className or ''}",
            **kwargs,
        )
        return self._build_nested_builder(link_element)

    def container(self, key: Optional[str] = None, height: Optional[str] = None, **kwargs: Any) -> "RouteLitBuilder":
        """
        Creates a container component.

        Args:
            key (Optional[str]): The key of the container.
            height (Optional[str]): The height of the container.
            kwargs (Dict[str, Any]): The keyword arguments to pass to the container.

        Example:
            ```python
            with ui.container(height="100px"):
                ui.text("Container")
            ```
        """
        container = self._create_element(
            name="container",
            key=key or self._new_text_id("container"),
            props={"style": {"height": height}, **kwargs},
        )
        return self._build_nested_builder(container)

    def markdown(
        self,
        body: str,
        *,
        allow_unsafe_html: bool = False,
        key: Optional[str] = None,
        **kwargs: Any,
    ) -> None:
        """
        Creates a markdown component.

        Args:
            body (str): The body of the markdown.
            allow_unsafe_html (bool): Whether to allow unsafe HTML.
            key (Optional[str]): The key of the markdown.

        Example:
            ```python
            ui.markdown("**Bold** *italic* [link](https://www.google.com)")
            ```
        """
        self._create_element(
            name="markdown",
            key=key or self._new_text_id("markdown"),
            props={"body": body, "allowUnsafeHtml": allow_unsafe_html, **kwargs},
        )

    def text(self, body: str, key: Optional[str] = None, **kwargs: Any) -> None:
        """
        Creates a text component.

        Args:
            body (str): The body of the text.
            key (Optional[str]): The key of the text.

        Example:
            ```python
            ui.text("Text")
            ```
        """
        self.markdown(body, allow_unsafe_html=False, key=key, **kwargs)

    def title(self, body: str, key: Optional[str] = None, **kwargs: Any) -> None:
        """
        Creates a title component.

        Args:
            body (str): The body of the title.
            key (Optional[str]): The key of the title.

        Example:
            ```python
            ui.title("Title")
            ```
        """
        self._create_element(
            name="title",
            key=key or self._new_text_id("title"),
            props={"children": body, **kwargs},
        )

    def header(self, body: str, key: Optional[str] = None, **kwargs: Any) -> None:
        """
        Creates a header component.

        Args:
            body (str): The body of the header.
            key (Optional[str]): The key of the header.

        Example:
            ```python
            ui.header("Header")
            ```
        """
        self._create_element(
            name="header",
            key=key or self._new_text_id("header"),
            props={"children": body, **kwargs},
        )

    def subheader(self, body: str, key: Optional[str] = None, **kwargs: Any) -> None:
        """
        Creates a subheader component.

        Args:
            body (str): The body of the subheader.
            key (Optional[str]): The key of the subheader.

        Example:
            ```python
            ui.subheader("Subheader")
            ```
        """
        self._create_element(
            name="subheader",
            key=key or self._new_text_id("subheader"),
            props={"children": body, **kwargs},
        )

    def image(self, src: str, *, key: Optional[str] = None, **kwargs: Any) -> None:
        """
        Creates an image component.

        Args:
            src (str): The source of the image.
            key (Optional[str]): The key of the image.
            kwargs (Dict[str, Any]): The keyword arguments to pass to the image.

        Example:
            ```python
            ui.image("https://www.google.com/favicon.ico", alt="Google", width="24px", height="24px")
            ```
        """
        self._create_element(
            name="image",
            key=key or self._new_text_id("image"),
            props={"src": src, **kwargs},
        )

    def expander(self, title: str, *, is_open: Optional[bool] = None, key: Optional[str] = None) -> "RouteLitBuilder":
        """
        Creates an expander component that can be used as both a context manager and a regular function call.

        Args:
            title (str): The title of the expander.
            is_open (Optional[bool]): Whether the expander is open.
            key (Optional[str]): The key of the expander.

        Returns:
            RouteLitBuilder: A builder for the expander.

        Example:
            ```python
            def build_index_view(ui: RouteLitBuilder):
                # Context manager style
                with ui.expander("Title"):
                    ui.text("Content")

                with ui.expander("Title", is_open=True) as exp0:
                    exp0.text("Content")

                # Function call style
                exp = ui.expander("Title")
                exp.text("Content")
            ```
        """
        new_key = key or self._new_widget_id("expander", title)
        new_element = self._create_element(
            name="expander",
            key=new_key,
            props={"title": title, "open": is_open},
        )
        return self._build_nested_builder(new_element)

    def columns(
        self,
        spec: Union[int, List[int]],
        *,
        key: Optional[str] = None,
        vertical_alignment: VerticalAlignment = "top",
        columns_gap: ColumnsGap = "small",
    ) -> List["RouteLitBuilder"]:
        """Creates a flexbox layout with several columns with the given spec.

        Args:
            spec (int | List[int]): The specification of the columns. Can be an integer or a list of integers.
            key (Optional[str]): The key of the container.
            vertical_alignment (VerticalAlignment): The vertical alignment of the columns: "top", "center", "bottom".
            columns_gap (ColumnsGap): The gap between the columns: "none", "small", "medium", "large".

        Returns:
            List[RouteLitBuilder]: A list of builders for the columns.

        Example:
            ```python
            # 2 columns with equal width
            col1, col2 = ui.columns(2)

            # usage inline
            col1.text("Column 1")
            col2.text("Column 2")

            # usage as context manager
            with col1:
                ui.text("Column 1")
            with col2:
                ui.text("Column 2")

            # usage with different widths
            col1, col2, col3 = ui.columns([2, 1, 1])
            col1.text("Column 1")
            col2.text("Column 2")
            col3.text("Column 3")
            ```
        """
        if isinstance(spec, int):
            spec = [1] * spec
        container_key = key or self._new_text_id("container")
        container = self._create_element(
            name="container",
            key=container_key,
            props={
                "className": "rl-flex rl-flex-row",
                "style": {
                    "alignItems": verticalAlignmentMap.get(vertical_alignment, "top"),
                    "columnGap": columnsGapMap.get(columns_gap, "small"),
                },
            },
        )
        container_builder = self._build_nested_builder(container)
        with container_builder:
            element_builders = []
            for column_spec in spec:
                column = self._create_element(
                    name="container",
                    key=self._new_text_id("col"),
                    props={"style": {"flex": column_spec}},
                )
                element_builders.append(self._build_nested_builder(column))
        return element_builders

    def flex(
        self,
        direction: Literal["row", "col"] = "col",
        wrap: Literal["wrap", "nowrap"] = "nowrap",
        justify_content: Literal["start", "end", "center", "between", "around", "evenly"] = "start",
        align_items: Literal["normal", "start", "end", "center", "baseline", "stretch"] = "normal",
        align_content: Literal["normal", "start", "end", "center", "between", "around", "evenly"] = "normal",
        gap: Optional[str] = None,
        key: Optional[str] = None,
        **kwargs: Any,
    ) -> "RouteLitBuilder":
        """
        Creates a flex container with the given direction, wrap, justify content, align items, align content, gap, and key.

        Args:
            direction (Literal["row", "col"]): The direction of the flex.
            wrap (Literal["wrap", "nowrap"]): The wrap of the flex.
            justify_content (Literal["start", "end", "center", "between", "around", "evenly"]): The justify content of the flex.
            align_items (Literal["normal", "start", "end", "center", "baseline", "stretch"]): The align items of the flex.
            align_content (Literal["normal", "start", "end", "center", "between", "around", "evenly"]): The align content of the flex.
            gap (Optional[str]): The gap of the flex.
            key (Optional[str]): The key of the flex.
            kwargs (Dict[str, Any]): The keyword arguments to pass to the flex.

        Returns:
            RouteLitBuilder: A builder for the flex.

        Example:
            ```python
            with ui.flex(direction="row", wrap="wrap", justify_content="center", align_items="center", align_content="center", gap="10px"):
                ui.text("Flex item 1")
                ui.text("Flex item 2")
                ui.text("Flex item 3")
            ```
        """
        container = self._create_element(
            name="flex",
            key=key or self._new_text_id("flex"),
            props={
                "direction": direction,
                "flexWrap": wrap,
                "justifyContent": justify_content,
                "alignItems": align_items,
                "alignContent": align_content,
                "gap": gap,
                **kwargs,
            },
        )
        return self._build_nested_builder(container)

    def _x_button(
        self,
        element_type: str,
        text: str,
        *,
        event_name: Literal["click", "submit"] = "click",
        key: Optional[str] = None,
        on_click: Optional[Callable[[], None]] = None,
        rl_virtual: Optional[bool] = None,
        **kwargs: Any,
    ) -> bool:
        button = self._create_element(
            name=element_type,
            key=key or self._new_widget_id(element_type, text),
            props={
                "children": text,
                "rlEventName": event_name,
                **kwargs,
            },
            virtual=rl_virtual,
        )
        is_clicked, _ = self._get_event_value(button.key, event_name)
        if is_clicked and on_click:
            on_click()
        return is_clicked

    def button(
        self,
        text: str,
        *,
        key: Optional[str] = None,
        on_click: Optional[Callable[[], None]] = None,
        **kwargs: Any,
    ) -> bool:
        """
        Creates a button with the given text, key, on click, and keyword arguments.

        Args:
            text (str): The text of the button.
            key (Optional[str]): The key of the button.
            on_click (Optional[Callable[[], None]]): The function to call when the button is clicked.
            kwargs (Dict[str, Any]): The keyword arguments to pass to the button.

        Returns:
            bool: Whether the button was clicked.

        Example:
            ```python
            is_clicked = ui.button("Click me", on_click=lambda: print("Button clicked"))
            if is_clicked:
                ui.text("Button clicked")
            ```
        """
        return self._x_button("button", text, event_name="click", key=key, on_click=on_click, **kwargs)

    def form_submit_button(
        self,
        text: str,
        *,
        key: Optional[str] = None,
        on_click: Optional[Callable[[], None]] = None,
        **kwargs: Any,
    ) -> bool:
        """
        Creates a form submit button with the given text, key, on click, and keyword arguments.

        Args:
            text (str): The text of the button.
            key (Optional[str]): The key of the button.
            on_click (Optional[Callable[[], None]]): The function to call when the button is clicked.
            kwargs (Dict[str, Any]): The keyword arguments to pass to the button.

        Returns:
            bool: Whether the button was clicked.

        Example:
            ```python
            with ui.form(key="form_key"):
                is_submitted = ui.form_submit_button("Submit", on_click=lambda: print("Form submitted"))
                if is_submitted:
                    ui.text("Form submitted")
            ```
        """
        return self._x_button("button", text, event_name="submit", key=key, on_click=on_click, **kwargs)

    def _x_input(
        self,
        element_type: str,
        key: str,
        *,
        value: Optional[Any] = None,
        on_change: Optional[Callable[[Any], None]] = None,
        event_name: str = "change",
        event_value_attr: str = "value",
        value_attr: str = "defaultValue",
        rl_format_func: Optional[Callable[[Any], Any]] = None,
        **kwargs: Any,
    ) -> Optional[Union[str, Any]]:
        new_value: Any = self.session_state.get(key, value)
        has_changed, event_value = self._get_event_value(key, event_name, event_value_attr)
        if has_changed:
            new_value = event_value
            if rl_format_func:
                new_value = rl_format_func(new_value)
            self.session_state[key] = new_value
            if on_change:
                on_change(new_value)
        self._create_element(
            name=element_type,
            key=key,
            props={
                value_attr: new_value,
                **kwargs,
            },
        )
        return new_value

    def _x_radio_select(
        self,
        element_type: str,
        key: str,
        *,
        options: List[Union[RLOption, str, Dict[str, Any]]],
        value: Optional[Any] = None,
        on_change: Optional[Callable[[Any], None]] = None,
        format_func: Optional[Callable[[Any], str]] = None,
        options_attr: str = "options",
        **kwargs: Any,
    ) -> Any:
        new_value = self.session_state.get(key, value)
        has_changed, event_value = self._get_event_value(key, "change", "value")
        if has_changed:
            new_value = event_value
            self.session_state[key] = new_value
            if on_change:
                on_change(new_value)
        new_options = format_options(options, format_func)
        self._create_element(
            name=element_type,
            key=key,
            props={
                "value": new_value,
                options_attr: new_options,
                **kwargs,
            },
        )
        return new_value

    def text_input(
        self,
        label: str,
        *,
        type: TextInputType = "text",
        value: Optional[str] = None,
        key: Optional[str] = None,
        on_change: Optional[Callable[[str], None]] = None,
        **kwargs: Any,
    ) -> Optional[str]:
        """
        Creates a text input with the given label and value.

        Args:
            label (str): The label of the text input.
            type (TextInputType): The type of the text input.
            value (Optional[str]): The value of the text input.
            key (Optional[str]): The key of the text input.
            on_change (Optional[Callable[[str], None]]): The function to call when the value changes. The function will be called with the new value.
            kwargs (Dict[str, Any]): The keyword arguments to pass to the text input.

        Returns:
            str: The text value of the text input.

        Example:
            ```python
            name = ui.text_input("Name", value="John", on_change=lambda value: print(f"Name changed to {value}"))
            ui.text(f"Name is {name}")
            ```
        """
        return self._x_input(
            "single-text-input",
            key or self._new_widget_id("text-input", label),
            value=value,
            on_change=on_change,
            type=type,
            label=label,
            **kwargs,
        )

    def hr(self, key: Optional[str] = None, **kwargs: Any) -> None:
        """
        Creates a horizontal rule.
        """
        self._create_element(name="hr", key=key or self._new_text_id("hr"), props=kwargs)

    def textarea(
        self,
        label: str,
        *,
        value: Optional[str] = None,
        key: Optional[str] = None,
        on_change: Optional[Callable[[str], None]] = None,
        **kwargs: Any,
    ) -> Optional[str]:
        """
        Creates a textarea with the given label and value.

        Args:
            label (str): The label of the textarea.
            value (Optional[str]): The value of the textarea.
            key (Optional[str]): The key of the textarea.
            on_change (Optional[Callable[[str], None]]): The function to call when the value changes. The function will be called with the new value.
            kwargs (Dict[str, Any]): The keyword arguments to pass to the textarea.

        Returns:
            str: The text value of the textarea.

        Example:
            ```python
            text = ui.textarea("Text", value="Hello, world!", on_change=lambda value: print(f"Text changed to {value}"))
            ui.text(f"Text is {text}")
            ```
        """
        return self._x_input(
            "single-textarea",
            key or self._new_widget_id("textarea", label),
            value=value,
            on_change=on_change,
            label=label,
            **kwargs,
        )

    def radio(
        self,
        label: str,
        options: List[Union[RLOption, str, Dict[str, Any]]],
        *,
        value: Optional[Any] = None,
        key: Optional[str] = None,
        on_change: Optional[Callable[[Any], None]] = None,
        flex_direction: Literal["row", "col"] = "col",
        format_func: Optional[Callable[[Any], str]] = None,
        **kwargs: Any,
    ) -> Any:
        """
        Creates a radio group with the given label and options.

        Args:
            label (str): The label of the radio group.
            options (List[RLOption | str | Dict[str, Any]]): The options of the radio group. Each option can be a string or a dictionary with the following keys:
                - label: The label of the option.
                - value: The value of the option.
                - caption: The caption of the option.
                - disabled: Whether the option is disabled.
            value (str | int | None): The value of the radio group.
            key (str | None): The key of the radio group.
            on_change (Callable[[str | int | None], None] | None): The function to call when the value changes. The function will be called with the new value.
            kwargs (Dict[str, Any]): The keyword arguments to pass to the radio group.

        Returns:
            str | int | None: The value of the selected radio option.

        Example:
            ```python
            value = ui.radio(
                "Radio",
                options=["Option 1", {"label": "Option 2", "value": "option2"}, {"label": "Option 3", "value": "option3", "disabled": True}],
                value="Option 1",
                on_change=lambda value: print(f"Radio value changed to {value}"),
            )
            ui.text(f"Radio value is {value}")
            ```
        """
        return self._x_radio_select(
            "radio",
            key or self._new_widget_id("radio", label),
            options=options,
            value=value,
            on_change=on_change,
            label=label,
            format_func=format_func,
            flexDirection=flex_direction,
            **kwargs,
        )

    def select(
        self,
        label: str,
        options: List[Union[RLOption, str, Dict[str, Any]]],
        *,
        value: Any = "",
        key: Optional[str] = None,
        on_change: Optional[Callable[[Any], None]] = None,
        format_func: Optional[Callable[[Any], str]] = None,
        **kwargs: Any,
    ) -> Any:
        """
        Creates a select dropdown with the given label and options.

        Args:
            label (str): The label of the select dropdown.
            options (List[RLOption | str | Dict[str, Any]]): The options of the select dropdown. Each option can be a string or a dictionary with the following keys: (label, value, disabled)
                - label: The label of the option.
                - value: The value of the option.
                - disabled: Whether the option is disabled.
            value (str | int): The value of the select dropdown.
            key (str | None): The key of the select dropdown.
            on_change (Callable[[str | int | None], None] | None): The function to call when the value changes. The function will be called with the new value.
            format_func (Callable[[Any], str] | None): The function to format the options.
            kwargs (Dict[str, Any]): The keyword arguments to pass to the select dropdown.

        Returns:
            Any: The value of the select dropdown.

        Example:
            ```python
            value = ui.select(
                "Select",
                options=[
                    "Option 1",
                    {"label": "Option 2", "value": "option2"},
                    {"label": "Option 3", "value": "option3", "disabled": True},
                ],
                value="Option 1",
                on_change=lambda value: print(f"Select value changed to {value}"),
            )
            ui.text(f"Select value is {value}")
            ```
        """
        return self._x_radio_select(
            "select",
            key or self._new_widget_id("select", label),
            options=options,
            value=value,
            on_change=on_change,
            format_func=format_func,
            label=label,
            **kwargs,
        )

    def _x_checkbox(
        self,
        element_type: str,
        key: str,
        *,
        checked: bool = False,
        on_change: Optional[Callable[[bool], None]] = None,
        checked_attr: str = "checked",
        **kwargs: Any,
    ) -> bool:
        value_key = key
        default_key = f"__{key}_default"

        current_value = self.session_state.get(key)
        previous_default = self.session_state.get(f"__{key}_default")

        # Initialize or update if default changed
        if current_value is None:
            # First time - use the checked parameter
            self.session_state[value_key] = checked
            self.session_state[default_key] = checked
            current_value = checked
        elif previous_default != checked:
            # Default value changed - update to new default
            self.session_state[value_key] = checked
            self.session_state[default_key] = checked
            current_value = checked

        # Handle user interaction events
        has_changed, event_value = self._get_event_value(key, "change", "checked")
        if has_changed:
            new_value = bool(event_value) if event_value is not None else False
            self.session_state[value_key] = new_value
            if on_change:
                on_change(new_value)
            current_value = new_value

        self._create_element(
            name=element_type,
            key=key,
            props={
                checked_attr: current_value,
                **kwargs,
            },
        )
        return bool(current_value)

    def checkbox(
        self,
        label: str,
        *,
        checked: bool = False,
        key: Optional[str] = None,
        on_change: Optional[Callable[[bool], None]] = None,
        **kwargs: Any,
    ) -> bool:
        """
        Creates a checkbox with the given label and value.

        Args:
            label (str): The label of the checkbox.
            checked (bool): Whether the checkbox is checked.
            key (str | None): The key of the checkbox.
            on_change (Callable[[bool], None] | None): The function to call when the value changes.
            kwargs (Dict[str, Any]): The keyword arguments to pass to the checkbox.

        Returns:
            bool: Whether the checkbox is checked.

        Example:
            ```python
            is_checked = ui.checkbox("Check me", on_change=lambda checked: print(f"Checkbox is {'checked' if checked else 'unchecked'}"))
            if is_checked:
                ui.text("Checkbox is checked")
            ```
        """
        return self._x_checkbox(
            "single-checkbox",
            key or self._new_widget_id("checkbox", label),
            checked=checked,
            on_change=on_change,
            label=label,
            **kwargs,
        )

    def _x_checkbox_group(
        self,
        element_type: str,
        key: str,
        *,
        options: List[Union[RLOption, str, Dict[str, Any]]],
        format_func: Optional[Callable[[Any], str]] = None,
        value: Optional[List[Any]] = None,
        on_change: Optional[Callable[[List[Any]], None]] = None,
        value_attr: str = "value",
        options_attr: str = "options",
        **kwargs: Any,
    ) -> List[Any]:
        new_value: List[Any] = self.session_state.get(key, value) or []
        if not isinstance(new_value, list):
            new_value = value or []
        has_changed, event_value = self._get_event_value(key, "change", "value")
        if has_changed:
            new_value = event_value if isinstance(event_value, list) else []
            self.session_state[key] = new_value
            if on_change:
                on_change(new_value)
        new_options = format_options(options, format_func)
        self._create_element(
            name=element_type,
            key=key,
            props={
                value_attr: new_value,
                options_attr: new_options,
                **kwargs,
            },
        )
        return new_value

    def checkbox_group(
        self,
        label: str,
        options: List[Union[RLOption, str, Dict[str, Any]]],
        *,
        value: Optional[List[Any]] = None,
        key: Optional[str] = None,
        on_change: Optional[Callable[[List[Any]], None]] = None,
        format_func: Optional[Callable[[Any], str]] = None,
        flex_direction: Literal["row", "col"] = "col",
        **kwargs: Any,
    ) -> List[Any]:
        """
        Creates a checkbox group with the given label and options.

        Args:
            label (str): The label of the checkbox group.
            options (List[RLOption | str | Dict[str, Any]]): The options of the checkbox group. Each option can be a string or a dictionary with the following keys: label, value, caption (optional), disabled (optional).
            value (List[str | int] | None): The value of the checkbox group.
            key (str | None): The key of the checkbox group.
            on_change (Callable[[List[str | int]], None] | None): The function to call when the value changes.
            format_func (Callable[[Any], str] | None): The function to format the options.
            flex_direction (Literal["row", "col"]): The direction of the checkbox group: "row", "col".
            kwargs (Dict[str, Any]): The keyword arguments to pass to the checkbox group.

        Returns:
            List[str | int]: The value of the checkbox group.

        Example:
            ```python
            selected_options = ui.checkbox_group(
                "Checkbox Group",
                options=[
                    "Option 1",
                    {"label": "Option 2", "value": "option2"},
                    {"label": "Option 3", "value": "option3", "disabled": True},
                ],
                value=["Option 1"],
                on_change=lambda value: print(f"Checkbox group value changed to {value}"),
            )
            ui.text(f"Selected options: {', '.join(selected_options) if selected_options else 'None'}")
            ```
        """
        return self._x_checkbox_group(
            "checkbox-group",
            key or self._new_widget_id("checkbox-group", label),
            label=label,
            options=options,
            value=value,
            on_change=on_change,
            format_func=format_func,
            flexDirection=flex_direction,
            **kwargs,
        )

    def rerun(self, scope: RerunType = "auto", clear_event: bool = True) -> None:
        """
        Reruns the current page. Use this to rerun the app or the fragment depending on the context.

        Args:
            scope (RerunType): The scope of the rerun. "auto" will rerun the app or the fragment depending on the context, "app" will rerun the entire app
            clear_event (bool): Whether to clear the event.

        Example:
            ```python
            counter = ui.session_state.get("counter", 0)
            ui.text(f"Counter is {counter}")
            should_increase = ui.button("Increment")
            if should_increase:
                ui.session_state["counter"] = counter + 1
                ui.rerun()
            ```
        """
        if self.should_rerun_event:
            self.should_rerun_event.set()
        if clear_event:
            self.request.clear_event()
        if scope == "app":
            self.request.clear_fragment_id()
        target = "app" if scope == "app" else self.initial_target
        # when running in stream mode, we need to schedule the rerun action to the event queue
        # so that the rerun action would be got with event queue loop can be cancelled
        if self._schedule_event(RerunAction(address=[-1], target=target)):
            return
        raise RerunException(self.session_state.get_data(), scope=scope)

    def get_head(self) -> Head:
        if self.head is None:
            self.head = Head()
        return self.head

    def set_page_config(self, page_title: Optional[str] = None, page_description: Optional[str] = None) -> None:
        """
        Sets the page title and description.

        Args:
            page_title (str | None): The title of the page.
            page_description (str | None): The description of the page.
        """
        self.head = Head(title=page_title, description=page_description)
        self._create_element(
            name="head",
            key="__head__",
            props={
                "title": page_title,
                "description": page_description,
            },
        )

    def __enter__(self) -> "RouteLitBuilder":
        # When using with builder.element():
        # Make parent builder redirect to this one
        if self.parent_builder:
            self._prev_active_child_builder = self.parent_builder.active_child_builder
            self.parent_builder.active_child_builder = self
        return self

    def __exit__(self, exc_type: Any, exc_value: Any, traceback: Any) -> None:
        # Reset parent's active child when exiting context
        if self.parent_builder:
            if self._prev_active_child_builder:
                self.parent_builder.active_child_builder = self._prev_active_child_builder
                self._prev_active_child_builder = None
            else:
                self.parent_builder.active_child_builder = None

    def __call__(self, *args: Any, **kwds: Any) -> "RouteLitBuilder":
        return self

    @property
    def parent_element(self) -> RouteLitElement:
        return self._parent_element

    def get_fragments(self) -> MutableMapping[str, List[int]]:
        return self.fragments

    def handle_view_task_done(self) -> None:
        self._schedule_event(
            ViewTaskDoneAction(
                address=[-1],
                target=self.initial_target,
            )
        )

    def on_end(self) -> None:
        self.session_state.pop("__ignore_submit", None)
        if self.should_rerun_event and self.should_rerun_event.is_set():
            return  # skip the last action when should_rerun is True
        self._schedule_event(
            LastAction(
                address=None,
                target=self.initial_target,
            )
        )

    @classmethod
    def get_client_resource_paths(cls) -> List[AssetTarget]:
        static_assets_targets = []
        for c in cls.__mro__:
            if hasattr(c, "static_assets_targets") and isinstance(c.static_assets_targets, list):
                static_assets_targets.extend(c.static_assets_targets)
        # Remove duplicates while preserving order (works with unhashable types like dictionaries)
        seen = []
        result = []
        for item in static_assets_targets:
            if item not in seen:
                seen.append(item)
                result.append(item)
        return result

button(text, *, key=None, on_click=None, **kwargs)

Creates a button with the given text, key, on click, and keyword arguments.

Parameters:

Name	Type	Description	Default
text	str	The text of the button.	required
key	Optional[str]	The key of the button.	None
on_click	Optional[Callable[[], None]]	The function to call when the button is clicked.	None
kwargs	Dict[str, Any]	The keyword arguments to pass to the button.	{}

Returns:

Name	Type	Description
bool	bool	Whether the button was clicked.

Example

is_clicked = ui.button("Click me", on_click=lambda: print("Button clicked"))
if is_clicked:
    ui.text("Button clicked")

Source code in src/routelit/builder.py

def button(
    self,
    text: str,
    *,
    key: Optional[str] = None,
    on_click: Optional[Callable[[], None]] = None,
    **kwargs: Any,
) -> bool:
    """
    Creates a button with the given text, key, on click, and keyword arguments.

    Args:
        text (str): The text of the button.
        key (Optional[str]): The key of the button.
        on_click (Optional[Callable[[], None]]): The function to call when the button is clicked.
        kwargs (Dict[str, Any]): The keyword arguments to pass to the button.

    Returns:
        bool: Whether the button was clicked.

    Example:
        ```python
        is_clicked = ui.button("Click me", on_click=lambda: print("Button clicked"))
        if is_clicked:
            ui.text("Button clicked")
        ```
    """
    return self._x_button("button", text, event_name="click", key=key, on_click=on_click, **kwargs)

checkbox(label, *, checked=False, key=None, on_change=None, **kwargs)

Creates a checkbox with the given label and value.

Parameters:

Name	Type	Description	Default
label	str	The label of the checkbox.	required
checked	bool	Whether the checkbox is checked.	False
key	str | None	The key of the checkbox.	None
on_change	Callable[[bool], None] | None	The function to call when the value changes.	None
kwargs	Dict[str, Any]	The keyword arguments to pass to the checkbox.	{}

Returns:

Name	Type	Description
bool	bool	Whether the checkbox is checked.

Example

is_checked = ui.checkbox("Check me", on_change=lambda checked: print(f"Checkbox is {'checked' if checked else 'unchecked'}"))
if is_checked:
    ui.text("Checkbox is checked")

Source code in src/routelit/builder.py

def checkbox(
    self,
    label: str,
    *,
    checked: bool = False,
    key: Optional[str] = None,
    on_change: Optional[Callable[[bool], None]] = None,
    **kwargs: Any,
) -> bool:
    """
    Creates a checkbox with the given label and value.

    Args:
        label (str): The label of the checkbox.
        checked (bool): Whether the checkbox is checked.
        key (str | None): The key of the checkbox.
        on_change (Callable[[bool], None] | None): The function to call when the value changes.
        kwargs (Dict[str, Any]): The keyword arguments to pass to the checkbox.

    Returns:
        bool: Whether the checkbox is checked.

    Example:
        ```python
        is_checked = ui.checkbox("Check me", on_change=lambda checked: print(f"Checkbox is {'checked' if checked else 'unchecked'}"))
        if is_checked:
            ui.text("Checkbox is checked")
        ```
    """
    return self._x_checkbox(
        "single-checkbox",
        key or self._new_widget_id("checkbox", label),
        checked=checked,
        on_change=on_change,
        label=label,
        **kwargs,
    )

checkbox_group(label, options, *, value=None, key=None, on_change=None, format_func=None, flex_direction='col', **kwargs)

Creates a checkbox group with the given label and options.

Parameters:

Name	Type	Description	Default
label	str	The label of the checkbox group.	required
options	List[RLOption | str | Dict[str, Any]]	The options of the checkbox group. Each option can be a string or a dictionary with the following keys: label, value, caption (optional), disabled (optional).	required
value	List[str | int] | None	The value of the checkbox group.	None
key	str | None	The key of the checkbox group.	None
on_change	Callable[[List[str | int]], None] | None	The function to call when the value changes.	None
format_func	Callable[[Any], str] | None	The function to format the options.	None
flex_direction	Literal['row', 'col']	The direction of the checkbox group: "row", "col".	'col'
kwargs	Dict[str, Any]	The keyword arguments to pass to the checkbox group.	{}

Returns:

Type	Description
List[Any]	List[str | int]: The value of the checkbox group.

Example

selected_options = ui.checkbox_group(
    "Checkbox Group",
    options=[
        "Option 1",
        {"label": "Option 2", "value": "option2"},
        {"label": "Option 3", "value": "option3", "disabled": True},
    ],
    value=["Option 1"],
    on_change=lambda value: print(f"Checkbox group value changed to {value}"),
)
ui.text(f"Selected options: {', '.join(selected_options) if selected_options else 'None'}")

Source code in src/routelit/builder.py

def checkbox_group(
    self,
    label: str,
    options: List[Union[RLOption, str, Dict[str, Any]]],
    *,
    value: Optional[List[Any]] = None,
    key: Optional[str] = None,
    on_change: Optional[Callable[[List[Any]], None]] = None,
    format_func: Optional[Callable[[Any], str]] = None,
    flex_direction: Literal["row", "col"] = "col",
    **kwargs: Any,
) -> List[Any]:
    """
    Creates a checkbox group with the given label and options.

    Args:
        label (str): The label of the checkbox group.
        options (List[RLOption | str | Dict[str, Any]]): The options of the checkbox group. Each option can be a string or a dictionary with the following keys: label, value, caption (optional), disabled (optional).
        value (List[str | int] | None): The value of the checkbox group.
        key (str | None): The key of the checkbox group.
        on_change (Callable[[List[str | int]], None] | None): The function to call when the value changes.
        format_func (Callable[[Any], str] | None): The function to format the options.
        flex_direction (Literal["row", "col"]): The direction of the checkbox group: "row", "col".
        kwargs (Dict[str, Any]): The keyword arguments to pass to the checkbox group.

    Returns:
        List[str | int]: The value of the checkbox group.

    Example:
        ```python
        selected_options = ui.checkbox_group(
            "Checkbox Group",
            options=[
                "Option 1",
                {"label": "Option 2", "value": "option2"},
                {"label": "Option 3", "value": "option3", "disabled": True},
            ],
            value=["Option 1"],
            on_change=lambda value: print(f"Checkbox group value changed to {value}"),
        )
        ui.text(f"Selected options: {', '.join(selected_options) if selected_options else 'None'}")
        ```
    """
    return self._x_checkbox_group(
        "checkbox-group",
        key or self._new_widget_id("checkbox-group", label),
        label=label,
        options=options,
        value=value,
        on_change=on_change,
        format_func=format_func,
        flexDirection=flex_direction,
        **kwargs,
    )

columns(spec, *, key=None, vertical_alignment='top', columns_gap='small')

Creates a flexbox layout with several columns with the given spec.

Parameters:

Name	Type	Description	Default
spec	int | List[int]	The specification of the columns. Can be an integer or a list of integers.	required
key	Optional[str]	The key of the container.	None
vertical_alignment	VerticalAlignment	The vertical alignment of the columns: "top", "center", "bottom".	'top'
columns_gap	ColumnsGap	The gap between the columns: "none", "small", "medium", "large".	'small'

Returns:

Type	Description
List[RouteLitBuilder]	List[RouteLitBuilder]: A list of builders for the columns.

Example

# 2 columns with equal width
col1, col2 = ui.columns(2)

# usage inline
col1.text("Column 1")
col2.text("Column 2")

# usage as context manager
with col1:
    ui.text("Column 1")
with col2:
    ui.text("Column 2")

# usage with different widths
col1, col2, col3 = ui.columns([2, 1, 1])
col1.text("Column 1")
col2.text("Column 2")
col3.text("Column 3")

Source code in src/routelit/builder.py

def columns(
    self,
    spec: Union[int, List[int]],
    *,
    key: Optional[str] = None,
    vertical_alignment: VerticalAlignment = "top",
    columns_gap: ColumnsGap = "small",
) -> List["RouteLitBuilder"]:
    """Creates a flexbox layout with several columns with the given spec.

    Args:
        spec (int | List[int]): The specification of the columns. Can be an integer or a list of integers.
        key (Optional[str]): The key of the container.
        vertical_alignment (VerticalAlignment): The vertical alignment of the columns: "top", "center", "bottom".
        columns_gap (ColumnsGap): The gap between the columns: "none", "small", "medium", "large".

    Returns:
        List[RouteLitBuilder]: A list of builders for the columns.

    Example:
        ```python
        # 2 columns with equal width
        col1, col2 = ui.columns(2)

        # usage inline
        col1.text("Column 1")
        col2.text("Column 2")

        # usage as context manager
        with col1:
            ui.text("Column 1")
        with col2:
            ui.text("Column 2")

        # usage with different widths
        col1, col2, col3 = ui.columns([2, 1, 1])
        col1.text("Column 1")
        col2.text("Column 2")
        col3.text("Column 3")
        ```
    """
    if isinstance(spec, int):
        spec = [1] * spec
    container_key = key or self._new_text_id("container")
    container = self._create_element(
        name="container",
        key=container_key,
        props={
            "className": "rl-flex rl-flex-row",
            "style": {
                "alignItems": verticalAlignmentMap.get(vertical_alignment, "top"),
                "columnGap": columnsGapMap.get(columns_gap, "small"),
            },
        },
    )
    container_builder = self._build_nested_builder(container)
    with container_builder:
        element_builders = []
        for column_spec in spec:
            column = self._create_element(
                name="container",
                key=self._new_text_id("col"),
                props={"style": {"flex": column_spec}},
            )
            element_builders.append(self._build_nested_builder(column))
    return element_builders

container(key=None, height=None, **kwargs)

Creates a container component.

Parameters:

Name	Type	Description	Default
key	Optional[str]	The key of the container.	None
height	Optional[str]	The height of the container.	None
kwargs	Dict[str, Any]	The keyword arguments to pass to the container.	{}

Example

with ui.container(height="100px"):
    ui.text("Container")

Source code in src/routelit/builder.py

def container(self, key: Optional[str] = None, height: Optional[str] = None, **kwargs: Any) -> "RouteLitBuilder":
    """
    Creates a container component.

    Args:
        key (Optional[str]): The key of the container.
        height (Optional[str]): The height of the container.
        kwargs (Dict[str, Any]): The keyword arguments to pass to the container.

    Example:
        ```python
        with ui.container(height="100px"):
            ui.text("Container")
        ```
    """
    container = self._create_element(
        name="container",
        key=key or self._new_text_id("container"),
        props={"style": {"height": height}, **kwargs},
    )
    return self._build_nested_builder(container)

expander(title, *, is_open=None, key=None)

Creates an expander component that can be used as both a context manager and a regular function call.

Parameters:

Name	Type	Description	Default
title	str	The title of the expander.	required
is_open	Optional[bool]	Whether the expander is open.	None
key	Optional[str]	The key of the expander.	None

Returns:

Name	Type	Description
RouteLitBuilder	RouteLitBuilder	A builder for the expander.

Example

def build_index_view(ui: RouteLitBuilder):
    # Context manager style
    with ui.expander("Title"):
        ui.text("Content")

    with ui.expander("Title", is_open=True) as exp0:
        exp0.text("Content")

    # Function call style
    exp = ui.expander("Title")
    exp.text("Content")

Source code in src/routelit/builder.py

def expander(self, title: str, *, is_open: Optional[bool] = None, key: Optional[str] = None) -> "RouteLitBuilder":
    """
    Creates an expander component that can be used as both a context manager and a regular function call.

    Args:
        title (str): The title of the expander.
        is_open (Optional[bool]): Whether the expander is open.
        key (Optional[str]): The key of the expander.

    Returns:
        RouteLitBuilder: A builder for the expander.

    Example:
        ```python
        def build_index_view(ui: RouteLitBuilder):
            # Context manager style
            with ui.expander("Title"):
                ui.text("Content")

            with ui.expander("Title", is_open=True) as exp0:
                exp0.text("Content")

            # Function call style
            exp = ui.expander("Title")
            exp.text("Content")
        ```
    """
    new_key = key or self._new_widget_id("expander", title)
    new_element = self._create_element(
        name="expander",
        key=new_key,
        props={"title": title, "open": is_open},
    )
    return self._build_nested_builder(new_element)

file_input(label, *, key=None, accept_multiple_files=None, accept=None, on_change=None, **kwargs)

file_input(
    label: str,
    *,
    key: Optional[str] = None,
    accept_multiple_files: Literal[True],
    accept: Optional[str] = None,
    on_change: Optional[
        Callable[[List[IOBase]], None]
    ] = None,
    **kwargs: Any,
) -> Optional[List[IOBase]]

file_input(
    label: str,
    *,
    key: Optional[str] = None,
    accept_multiple_files: Literal[False] = ...,
    accept: Optional[str] = None,
    on_change: Optional[Callable[[IOBase], None]] = None,
    **kwargs: Any,
) -> Optional[IOBase]

Creates a file input component. You'll get the bytes of the uploaded file (BytesIO object). Useful for handling files in memory. Not suitable for large files.

Parameters:

Name	Type	Description	Default
label	str	The label of the file input.	required
key	Optional[str]	The key of the file input.	None
accept_multiple_files	Optional[bool]	Whether to accept multiple files.	None
accept	Optional[str]	The accept attribute of the file input.	None
kwargs	Dict[str, Any]	The keyword arguments to pass to the file input.	{}

Returns:

Type	Description
Union[IOBase, List[IOBase], None]	Optional[IOBase|List[IOBase]]: The file input component.

Example

# Multiple files
files = ui.file_input("Files", accept_multiple_files=True, accept="text/plain, .txt")
if files:
    for file in files:
        ui.text(file.read().decode("utf-8"))

# Single file
single_file = ui.file_input("Single File", accept_multiple_files=False, accept="text/plain, .txt")
if single_file:
    ui.text(single_file.read().decode("utf-8"))

# Handling images
import base64
image = ui.file_input("Image", accept="image/png")
if image:
    ui.image(src=f"data:image/png;base64,{base64.b64encode(image.read()).decode('utf-8')}", width=128)
if image and ui.button("Save image"):
    with open("image.png", "wb") as f:
        f.write(image.read())
        ui.text("Image saved")

def on_file_change(value: Union[IOBase, List[IOBase]]):
    ui.text(f"File changed: {value}")
file_input = ui.file_input("File", on_change=on_file_change)

Source code in src/routelit/builder.py

def file_input(  # type: ignore[misc]
    self,
    label: str,
    *,
    key: Optional[str] = None,
    accept_multiple_files: Optional[bool] = None,
    accept: Optional[str] = None,
    on_change: Optional[Callable[[Union[IOBase, List[IOBase]]], None]] = None,
    **kwargs: Any,
) -> Union[IOBase, List[IOBase], None]:
    """
    Creates a file input component.
    You'll get the bytes of the uploaded file (BytesIO object).
    Useful for handling files in memory. Not suitable for large files.

    Args:
        label (str): The label of the file input.
        key (Optional[str]): The key of the file input.
        accept_multiple_files (Optional[bool]): Whether to accept multiple files.
        accept (Optional[str]): The accept attribute of the file input.
        kwargs (Dict[str, Any]): The keyword arguments to pass to the file input.

    Returns:
        Optional[IOBase|List[IOBase]]: The file input component.

    Example:
        ```python
        # Multiple files
        files = ui.file_input("Files", accept_multiple_files=True, accept="text/plain, .txt")
        if files:
            for file in files:
                ui.text(file.read().decode("utf-8"))

        # Single file
        single_file = ui.file_input("Single File", accept_multiple_files=False, accept="text/plain, .txt")
        if single_file:
            ui.text(single_file.read().decode("utf-8"))

        # Handling images
        import base64
        image = ui.file_input("Image", accept="image/png")
        if image:
            ui.image(src=f"data:image/png;base64,{base64.b64encode(image.read()).decode('utf-8')}", width=128)
        if image and ui.button("Save image"):
            with open("image.png", "wb") as f:
                f.write(image.read())
                ui.text("Image saved")

        def on_file_change(value: Union[IOBase, List[IOBase]]):
            ui.text(f"File changed: {value}")
        file_input = ui.file_input("File", on_change=on_file_change)
        ```
    """
    return self._x_file_input(
        "input-file",
        key or self._new_widget_id("input-file", label),
        multiple=accept_multiple_files,
        label=label,
        accept=accept,
        on_change=on_change,
        **kwargs,
    )

flex(direction='col', wrap='nowrap', justify_content='start', align_items='normal', align_content='normal', gap=None, key=None, **kwargs)

Creates a flex container with the given direction, wrap, justify content, align items, align content, gap, and key.

Parameters:

Name	Type	Description	Default
direction	Literal['row', 'col']	The direction of the flex.	'col'
wrap	Literal['wrap', 'nowrap']	The wrap of the flex.	'nowrap'
justify_content	Literal['start', 'end', 'center', 'between', 'around', 'evenly']	The justify content of the flex.	'start'
align_items	Literal['normal', 'start', 'end', 'center', 'baseline', 'stretch']	The align items of the flex.	'normal'
align_content	Literal['normal', 'start', 'end', 'center', 'between', 'around', 'evenly']	The align content of the flex.	'normal'
gap	Optional[str]	The gap of the flex.	None
key	Optional[str]	The key of the flex.	None
kwargs	Dict[str, Any]	The keyword arguments to pass to the flex.	{}

Returns:

Name	Type	Description
RouteLitBuilder	RouteLitBuilder	A builder for the flex.

Example

with ui.flex(direction="row", wrap="wrap", justify_content="center", align_items="center", align_content="center", gap="10px"):
    ui.text("Flex item 1")
    ui.text("Flex item 2")
    ui.text("Flex item 3")

Source code in src/routelit/builder.py

def flex(
    self,
    direction: Literal["row", "col"] = "col",
    wrap: Literal["wrap", "nowrap"] = "nowrap",
    justify_content: Literal["start", "end", "center", "between", "around", "evenly"] = "start",
    align_items: Literal["normal", "start", "end", "center", "baseline", "stretch"] = "normal",
    align_content: Literal["normal", "start", "end", "center", "between", "around", "evenly"] = "normal",
    gap: Optional[str] = None,
    key: Optional[str] = None,
    **kwargs: Any,
) -> "RouteLitBuilder":
    """
    Creates a flex container with the given direction, wrap, justify content, align items, align content, gap, and key.

    Args:
        direction (Literal["row", "col"]): The direction of the flex.
        wrap (Literal["wrap", "nowrap"]): The wrap of the flex.
        justify_content (Literal["start", "end", "center", "between", "around", "evenly"]): The justify content of the flex.
        align_items (Literal["normal", "start", "end", "center", "baseline", "stretch"]): The align items of the flex.
        align_content (Literal["normal", "start", "end", "center", "between", "around", "evenly"]): The align content of the flex.
        gap (Optional[str]): The gap of the flex.
        key (Optional[str]): The key of the flex.
        kwargs (Dict[str, Any]): The keyword arguments to pass to the flex.

    Returns:
        RouteLitBuilder: A builder for the flex.

    Example:
        ```python
        with ui.flex(direction="row", wrap="wrap", justify_content="center", align_items="center", align_content="center", gap="10px"):
            ui.text("Flex item 1")
            ui.text("Flex item 2")
            ui.text("Flex item 3")
        ```
    """
    container = self._create_element(
        name="flex",
        key=key or self._new_text_id("flex"),
        props={
            "direction": direction,
            "flexWrap": wrap,
            "justifyContent": justify_content,
            "alignItems": align_items,
            "alignContent": align_content,
            "gap": gap,
            **kwargs,
        },
    )
    return self._build_nested_builder(container)

form(key)

Creates a form area that do not process the inputs values contained in it until the form is submitted. Use button(..., event_name="submit") or form_submit_button() to submit the form.

Parameters:

Name	Type	Description	Default
key	str	The key of the form.	required

Returns:

Name	Type	Description
RouteLitBuilder	RouteLitBuilder	A builder for the form.

Example

with ui.form("login"):
    username = ui.text_input("Username")
    password = ui.text_input("Password", type="password")
    is_submitted = ui.form_submit_button("Login") # or ui.button("Login", event_name="submit")
    if is_submitted:
        ui.text(f"Login successful for {username}")

Source code in src/routelit/builder.py

def form(self, key: str) -> "RouteLitBuilder":
    """
    Creates a form area that do not process the inputs values contained in it until the form is submitted.
    Use `button(..., event_name="submit")` or `form_submit_button()` to submit the form.

    Args:
        key (str): The key of the form.

    Returns:
        RouteLitBuilder: A builder for the form.

    Example:
        ```python
        with ui.form("login"):
            username = ui.text_input("Username")
            password = ui.text_input("Password", type="password")
            is_submitted = ui.form_submit_button("Login") # or ui.button("Login", event_name="submit")
            if is_submitted:
                ui.text(f"Login successful for {username}")
        ```
    """
    form = self._create_element(
        name="form",
        key=key,
        props={"id": key},
        virtual=True,
    )
    return self._build_nested_builder(form)

form_submit_button(text, *, key=None, on_click=None, **kwargs)

Creates a form submit button with the given text, key, on click, and keyword arguments.

Parameters:

Name	Type	Description	Default
text	str	The text of the button.	required
key	Optional[str]	The key of the button.	None
on_click	Optional[Callable[[], None]]	The function to call when the button is clicked.	None
kwargs	Dict[str, Any]	The keyword arguments to pass to the button.	{}

Returns:

Name	Type	Description
bool	bool	Whether the button was clicked.

Example

with ui.form(key="form_key"):
    is_submitted = ui.form_submit_button("Submit", on_click=lambda: print("Form submitted"))
    if is_submitted:
        ui.text("Form submitted")

Source code in src/routelit/builder.py

def form_submit_button(
    self,
    text: str,
    *,
    key: Optional[str] = None,
    on_click: Optional[Callable[[], None]] = None,
    **kwargs: Any,
) -> bool:
    """
    Creates a form submit button with the given text, key, on click, and keyword arguments.

    Args:
        text (str): The text of the button.
        key (Optional[str]): The key of the button.
        on_click (Optional[Callable[[], None]]): The function to call when the button is clicked.
        kwargs (Dict[str, Any]): The keyword arguments to pass to the button.

    Returns:
        bool: Whether the button was clicked.

    Example:
        ```python
        with ui.form(key="form_key"):
            is_submitted = ui.form_submit_button("Submit", on_click=lambda: print("Form submitted"))
            if is_submitted:
                ui.text("Form submitted")
        ```
    """
    return self._x_button("button", text, event_name="submit", key=key, on_click=on_click, **kwargs)

header(body, key=None, **kwargs)

Creates a header component.

Parameters:

Name	Type	Description	Default
body	str	The body of the header.	required
key	Optional[str]	The key of the header.	None

Example

ui.header("Header")

Source code in src/routelit/builder.py

def header(self, body: str, key: Optional[str] = None, **kwargs: Any) -> None:
    """
    Creates a header component.

    Args:
        body (str): The body of the header.
        key (Optional[str]): The key of the header.

    Example:
        ```python
        ui.header("Header")
        ```
    """
    self._create_element(
        name="header",
        key=key or self._new_text_id("header"),
        props={"children": body, **kwargs},
    )

hr(key=None, **kwargs)

Creates a horizontal rule.

Source code in src/routelit/builder.py

def hr(self, key: Optional[str] = None, **kwargs: Any) -> None:
    """
    Creates a horizontal rule.
    """
    self._create_element(name="hr", key=key or self._new_text_id("hr"), props=kwargs)

image(src, *, key=None, **kwargs)

Creates an image component.

Parameters:

Name	Type	Description	Default
src	str	The source of the image.	required
key	Optional[str]	The key of the image.	None
kwargs	Dict[str, Any]	The keyword arguments to pass to the image.	{}

Example

ui.image("https://www.google.com/favicon.ico", alt="Google", width="24px", height="24px")

Source code in src/routelit/builder.py

def image(self, src: str, *, key: Optional[str] = None, **kwargs: Any) -> None:
    """
    Creates an image component.

    Args:
        src (str): The source of the image.
        key (Optional[str]): The key of the image.
        kwargs (Dict[str, Any]): The keyword arguments to pass to the image.

    Example:
        ```python
        ui.image("https://www.google.com/favicon.ico", alt="Google", width="24px", height="24px")
        ```
    """
    self._create_element(
        name="image",
        key=key or self._new_text_id("image"),
        props={"src": src, **kwargs},
    )

link(href, text='', *, replace=False, is_external=False, key=None, rl_element_type='link', rl_text_attr='text', rl_virtual=None, **kwargs)

Creates a link component. Use this to navigate to a different page.

Parameters:

Name	Type	Description	Default
href	str	The href of the link.	required
text	str	The text of the link.	''
replace	bool	Whether to replace the current page from the history.	False
is_external	bool	Whether the link is external to the current app.	False
key	Optional[str]	The key of the link.	None
kwargs	Dict[str, Any]	The keyword arguments to pass to the link.	{}

Example

ui.link("/signup", text="Signup")
ui.link("/login", text="Login", replace=True)
ui.link("https://www.google.com", text="Google", is_external=True)

Source code in src/routelit/builder.py

def link(
    self,
    href: str,
    text: str = "",
    *,
    replace: bool = False,
    is_external: bool = False,
    key: Optional[str] = None,
    rl_element_type: str = "link",
    rl_text_attr: str = "text",
    rl_virtual: Optional[bool] = None,
    **kwargs: Any,
) -> RouteLitElement:
    """
    Creates a link component. Use this to navigate to a different page.

    Args:
        href (str): The href of the link.
        text (str): The text of the link.
        replace (bool): Whether to replace the current page from the history.
        is_external (bool): Whether the link is external to the current app.
        key (Optional[str]): The key of the link.
        kwargs (Dict[str, Any]): The keyword arguments to pass to the link.

    Example:
        ```python
        ui.link("/signup", text="Signup")
        ui.link("/login", text="Login", replace=True)
        ui.link("https://www.google.com", text="Google", is_external=True)
        ```
    """
    new_element = self._create_element(
        name=rl_element_type,
        key=key or self._new_text_id(rl_element_type),
        props={
            "href": href,
            "replace": replace,
            "isExternal": is_external,
            rl_text_attr: text,
            **kwargs,
        },
        virtual=rl_virtual,
    )
    return new_element

link_area(href, replace=False, is_external=False, key=None, className=None, **kwargs)

Creates a link area component. Use this element which is a container of other elements.

Parameters:

Name	Type	Description	Default
href	str	The href of the link.	required
replace	bool	Whether to replace the current page.	False
is_external	bool	Whether the link is external.	False
key	Optional[str]	The key of the link area.	None
className	Optional[str]	The class name of the link area.	None
kwargs	Dict[str, Any]	The keyword arguments to pass to the link area.	{}

Example

with ui.link_area("https://www.google.com"):
    with ui.flex(direction="row", gap="small"):
        ui.image("https://www.google.com/favicon.ico", width="24px", height="24px")
        ui.text("Google")

Source code in src/routelit/builder.py

def link_area(
    self,
    href: str,
    replace: bool = False,
    is_external: bool = False,
    key: Optional[str] = None,
    className: Optional[str] = None,
    **kwargs: Any,
) -> "RouteLitBuilder":
    """
    Creates a link area component. Use this element which is a container of other elements.

    Args:
        href (str): The href of the link.
        replace (bool): Whether to replace the current page.
        is_external (bool): Whether the link is external.
        key (Optional[str]): The key of the link area.
        className (Optional[str]): The class name of the link area.
        kwargs (Dict[str, Any]): The keyword arguments to pass to the link area.

    Example:
        ```python
        with ui.link_area("https://www.google.com"):
            with ui.flex(direction="row", gap="small"):
                ui.image("https://www.google.com/favicon.ico", width="24px", height="24px")
                ui.text("Google")
        ```
    """
    link_element = self.link(
        href,
        replace=replace,
        is_external=is_external,
        key=key,
        className=f"rl-no-link-decoration {className or ''}",
        **kwargs,
    )
    return self._build_nested_builder(link_element)

markdown(body, *, allow_unsafe_html=False, key=None, **kwargs)

Creates a markdown component.

Parameters:

Name	Type	Description	Default
body	str	The body of the markdown.	required
allow_unsafe_html	bool	Whether to allow unsafe HTML.	False
key	Optional[str]	The key of the markdown.	None

Example

ui.markdown("**Bold** *italic* [link](https://www.google.com)")

Source code in src/routelit/builder.py

def markdown(
    self,
    body: str,
    *,
    allow_unsafe_html: bool = False,
    key: Optional[str] = None,
    **kwargs: Any,
) -> None:
    """
    Creates a markdown component.

    Args:
        body (str): The body of the markdown.
        allow_unsafe_html (bool): Whether to allow unsafe HTML.
        key (Optional[str]): The key of the markdown.

    Example:
        ```python
        ui.markdown("**Bold** *italic* [link](https://www.google.com)")
        ```
    """
    self._create_element(
        name="markdown",
        key=key or self._new_text_id("markdown"),
        props={"body": body, "allowUnsafeHtml": allow_unsafe_html, **kwargs},
    )

radio(label, options, *, value=None, key=None, on_change=None, flex_direction='col', format_func=None, **kwargs)

Creates a radio group with the given label and options.

Parameters:

Name	Type	Description	Default
label	str	The label of the radio group.	required
options	List[RLOption | str | Dict[str, Any]]	The options of the radio group. Each option can be a string or a dictionary with the following keys: - label: The label of the option. - value: The value of the option. - caption: The caption of the option. - disabled: Whether the option is disabled.	required
value	str | int | None	The value of the radio group.	None
key	str | None	The key of the radio group.	None
on_change	Callable[[str | int | None], None] | None	The function to call when the value changes. The function will be called with the new value.	None
kwargs	Dict[str, Any]	The keyword arguments to pass to the radio group.	{}

Returns:

Type	Description
Any	str | int | None: The value of the selected radio option.

Example

value = ui.radio(
    "Radio",
    options=["Option 1", {"label": "Option 2", "value": "option2"}, {"label": "Option 3", "value": "option3", "disabled": True}],
    value="Option 1",
    on_change=lambda value: print(f"Radio value changed to {value}"),
)
ui.text(f"Radio value is {value}")

Source code in src/routelit/builder.py

def radio(
    self,
    label: str,
    options: List[Union[RLOption, str, Dict[str, Any]]],
    *,
    value: Optional[Any] = None,
    key: Optional[str] = None,
    on_change: Optional[Callable[[Any], None]] = None,
    flex_direction: Literal["row", "col"] = "col",
    format_func: Optional[Callable[[Any], str]] = None,
    **kwargs: Any,
) -> Any:
    """
    Creates a radio group with the given label and options.

    Args:
        label (str): The label of the radio group.
        options (List[RLOption | str | Dict[str, Any]]): The options of the radio group. Each option can be a string or a dictionary with the following keys:
            - label: The label of the option.
            - value: The value of the option.
            - caption: The caption of the option.
            - disabled: Whether the option is disabled.
        value (str | int | None): The value of the radio group.
        key (str | None): The key of the radio group.
        on_change (Callable[[str | int | None], None] | None): The function to call when the value changes. The function will be called with the new value.
        kwargs (Dict[str, Any]): The keyword arguments to pass to the radio group.

    Returns:
        str | int | None: The value of the selected radio option.

    Example:
        ```python
        value = ui.radio(
            "Radio",
            options=["Option 1", {"label": "Option 2", "value": "option2"}, {"label": "Option 3", "value": "option3", "disabled": True}],
            value="Option 1",
            on_change=lambda value: print(f"Radio value changed to {value}"),
        )
        ui.text(f"Radio value is {value}")
        ```
    """
    return self._x_radio_select(
        "radio",
        key or self._new_widget_id("radio", label),
        options=options,
        value=value,
        on_change=on_change,
        label=label,
        format_func=format_func,
        flexDirection=flex_direction,
        **kwargs,
    )

rerun(scope='auto', clear_event=True)

Reruns the current page. Use this to rerun the app or the fragment depending on the context.

Parameters:

Name	Type	Description	Default
scope	RerunType	The scope of the rerun. "auto" will rerun the app or the fragment depending on the context, "app" will rerun the entire app	'auto'
clear_event	bool	Whether to clear the event.	True

Example

counter = ui.session_state.get("counter", 0)
ui.text(f"Counter is {counter}")
should_increase = ui.button("Increment")
if should_increase:
    ui.session_state["counter"] = counter + 1
    ui.rerun()

Source code in src/routelit/builder.py

def rerun(self, scope: RerunType = "auto", clear_event: bool = True) -> None:
    """
    Reruns the current page. Use this to rerun the app or the fragment depending on the context.

    Args:
        scope (RerunType): The scope of the rerun. "auto" will rerun the app or the fragment depending on the context, "app" will rerun the entire app
        clear_event (bool): Whether to clear the event.

    Example:
        ```python
        counter = ui.session_state.get("counter", 0)
        ui.text(f"Counter is {counter}")
        should_increase = ui.button("Increment")
        if should_increase:
            ui.session_state["counter"] = counter + 1
            ui.rerun()
        ```
    """
    if self.should_rerun_event:
        self.should_rerun_event.set()
    if clear_event:
        self.request.clear_event()
    if scope == "app":
        self.request.clear_fragment_id()
    target = "app" if scope == "app" else self.initial_target
    # when running in stream mode, we need to schedule the rerun action to the event queue
    # so that the rerun action would be got with event queue loop can be cancelled
    if self._schedule_event(RerunAction(address=[-1], target=target)):
        return
    raise RerunException(self.session_state.get_data(), scope=scope)

select(label, options, *, value='', key=None, on_change=None, format_func=None, **kwargs)

Creates a select dropdown with the given label and options.

Parameters:

Name	Type	Description	Default
label	str	The label of the select dropdown.	required
options	List[RLOption | str | Dict[str, Any]]	The options of the select dropdown. Each option can be a string or a dictionary with the following keys: (label, value, disabled) - label: The label of the option. - value: The value of the option. - disabled: Whether the option is disabled.	required
value	str | int	The value of the select dropdown.	''
key	str | None	The key of the select dropdown.	None
on_change	Callable[[str | int | None], None] | None	The function to call when the value changes. The function will be called with the new value.	None
format_func	Callable[[Any], str] | None	The function to format the options.	None
kwargs	Dict[str, Any]	The keyword arguments to pass to the select dropdown.	{}

Returns:

Name	Type	Description
Any	Any	The value of the select dropdown.

Example

value = ui.select(
    "Select",
    options=[
        "Option 1",
        {"label": "Option 2", "value": "option2"},
        {"label": "Option 3", "value": "option3", "disabled": True},
    ],
    value="Option 1",
    on_change=lambda value: print(f"Select value changed to {value}"),
)
ui.text(f"Select value is {value}")

Source code in src/routelit/builder.py

def select(
    self,
    label: str,
    options: List[Union[RLOption, str, Dict[str, Any]]],
    *,
    value: Any = "",
    key: Optional[str] = None,
    on_change: Optional[Callable[[Any], None]] = None,
    format_func: Optional[Callable[[Any], str]] = None,
    **kwargs: Any,
) -> Any:
    """
    Creates a select dropdown with the given label and options.

    Args:
        label (str): The label of the select dropdown.
        options (List[RLOption | str | Dict[str, Any]]): The options of the select dropdown. Each option can be a string or a dictionary with the following keys: (label, value, disabled)
            - label: The label of the option.
            - value: The value of the option.
            - disabled: Whether the option is disabled.
        value (str | int): The value of the select dropdown.
        key (str | None): The key of the select dropdown.
        on_change (Callable[[str | int | None], None] | None): The function to call when the value changes. The function will be called with the new value.
        format_func (Callable[[Any], str] | None): The function to format the options.
        kwargs (Dict[str, Any]): The keyword arguments to pass to the select dropdown.

    Returns:
        Any: The value of the select dropdown.

    Example:
        ```python
        value = ui.select(
            "Select",
            options=[
                "Option 1",
                {"label": "Option 2", "value": "option2"},
                {"label": "Option 3", "value": "option3", "disabled": True},
            ],
            value="Option 1",
            on_change=lambda value: print(f"Select value changed to {value}"),
        )
        ui.text(f"Select value is {value}")
        ```
    """
    return self._x_radio_select(
        "select",
        key or self._new_widget_id("select", label),
        options=options,
        value=value,
        on_change=on_change,
        format_func=format_func,
        label=label,
        **kwargs,
    )

set_page_config(page_title=None, page_description=None)

Sets the page title and description.

Parameters:

Name	Type	Description	Default
page_title	str | None	The title of the page.	None
page_description	str | None	The description of the page.	None

Source code in src/routelit/builder.py

def set_page_config(self, page_title: Optional[str] = None, page_description: Optional[str] = None) -> None:
    """
    Sets the page title and description.

    Args:
        page_title (str | None): The title of the page.
        page_description (str | None): The description of the page.
    """
    self.head = Head(title=page_title, description=page_description)
    self._create_element(
        name="head",
        key="__head__",
        props={
            "title": page_title,
            "description": page_description,
        },
    )

subheader(body, key=None, **kwargs)

Creates a subheader component.

Parameters:

Name	Type	Description	Default
body	str	The body of the subheader.	required
key	Optional[str]	The key of the subheader.	None

Example

ui.subheader("Subheader")

Source code in src/routelit/builder.py

def subheader(self, body: str, key: Optional[str] = None, **kwargs: Any) -> None:
    """
    Creates a subheader component.

    Args:
        body (str): The body of the subheader.
        key (Optional[str]): The key of the subheader.

    Example:
        ```python
        ui.subheader("Subheader")
        ```
    """
    self._create_element(
        name="subheader",
        key=key or self._new_text_id("subheader"),
        props={"children": body, **kwargs},
    )

text(body, key=None, **kwargs)

Creates a text component.

Parameters:

Name	Type	Description	Default
body	str	The body of the text.	required
key	Optional[str]	The key of the text.	None

Example

ui.text("Text")

Source code in src/routelit/builder.py

def text(self, body: str, key: Optional[str] = None, **kwargs: Any) -> None:
    """
    Creates a text component.

    Args:
        body (str): The body of the text.
        key (Optional[str]): The key of the text.

    Example:
        ```python
        ui.text("Text")
        ```
    """
    self.markdown(body, allow_unsafe_html=False, key=key, **kwargs)

text_input(label, *, type='text', value=None, key=None, on_change=None, **kwargs)

Creates a text input with the given label and value.

Parameters:

Name	Type	Description	Default
label	str	The label of the text input.	required
type	TextInputType	The type of the text input.	'text'
value	Optional[str]	The value of the text input.	None
key	Optional[str]	The key of the text input.	None
on_change	Optional[Callable[[str], None]]	The function to call when the value changes. The function will be called with the new value.	None
kwargs	Dict[str, Any]	The keyword arguments to pass to the text input.	{}

Returns:

Name	Type	Description
str	Optional[str]	The text value of the text input.

Example

name = ui.text_input("Name", value="John", on_change=lambda value: print(f"Name changed to {value}"))
ui.text(f"Name is {name}")

Source code in src/routelit/builder.py

def text_input(
    self,
    label: str,
    *,
    type: TextInputType = "text",
    value: Optional[str] = None,
    key: Optional[str] = None,
    on_change: Optional[Callable[[str], None]] = None,
    **kwargs: Any,
) -> Optional[str]:
    """
    Creates a text input with the given label and value.

    Args:
        label (str): The label of the text input.
        type (TextInputType): The type of the text input.
        value (Optional[str]): The value of the text input.
        key (Optional[str]): The key of the text input.
        on_change (Optional[Callable[[str], None]]): The function to call when the value changes. The function will be called with the new value.
        kwargs (Dict[str, Any]): The keyword arguments to pass to the text input.

    Returns:
        str: The text value of the text input.

    Example:
        ```python
        name = ui.text_input("Name", value="John", on_change=lambda value: print(f"Name changed to {value}"))
        ui.text(f"Name is {name}")
        ```
    """
    return self._x_input(
        "single-text-input",
        key or self._new_widget_id("text-input", label),
        value=value,
        on_change=on_change,
        type=type,
        label=label,
        **kwargs,
    )

textarea(label, *, value=None, key=None, on_change=None, **kwargs)

Creates a textarea with the given label and value.

Parameters:

Name	Type	Description	Default
label	str	The label of the textarea.	required
value	Optional[str]	The value of the textarea.	None
key	Optional[str]	The key of the textarea.	None
on_change	Optional[Callable[[str], None]]	The function to call when the value changes. The function will be called with the new value.	None
kwargs	Dict[str, Any]	The keyword arguments to pass to the textarea.	{}

Returns:

Name	Type	Description
str	Optional[str]	The text value of the textarea.

Example

text = ui.textarea("Text", value="Hello, world!", on_change=lambda value: print(f"Text changed to {value}"))
ui.text(f"Text is {text}")

Source code in src/routelit/builder.py

def textarea(
    self,
    label: str,
    *,
    value: Optional[str] = None,
    key: Optional[str] = None,
    on_change: Optional[Callable[[str], None]] = None,
    **kwargs: Any,
) -> Optional[str]:
    """
    Creates a textarea with the given label and value.

    Args:
        label (str): The label of the textarea.
        value (Optional[str]): The value of the textarea.
        key (Optional[str]): The key of the textarea.
        on_change (Optional[Callable[[str], None]]): The function to call when the value changes. The function will be called with the new value.
        kwargs (Dict[str, Any]): The keyword arguments to pass to the textarea.

    Returns:
        str: The text value of the textarea.

    Example:
        ```python
        text = ui.textarea("Text", value="Hello, world!", on_change=lambda value: print(f"Text changed to {value}"))
        ui.text(f"Text is {text}")
        ```
    """
    return self._x_input(
        "single-textarea",
        key or self._new_widget_id("textarea", label),
        value=value,
        on_change=on_change,
        label=label,
        **kwargs,
    )

title(body, key=None, **kwargs)

Creates a title component.

Parameters:

Name	Type	Description	Default
body	str	The body of the title.	required
key	Optional[str]	The key of the title.	None

Example

ui.title("Title")

Source code in src/routelit/builder.py

def title(self, body: str, key: Optional[str] = None, **kwargs: Any) -> None:
    """
    Creates a title component.

    Args:
        body (str): The body of the title.
        key (Optional[str]): The key of the title.

    Example:
        ```python
        ui.title("Title")
        ```
    """
    self._create_element(
        name="title",
        key=key or self._new_text_id("title"),
        props={"children": body, **kwargs},
    )

Domain Module

ActionGenerator = AsyncGenerator[Action, None] module-attribute

Async generator type for Action instances.

COOKIE_SESSION_KEY = 'ROUTELIT_SESSION_ID' module-attribute

The key of the session id in the cookie.

RerunType = Literal['auto', 'app', 'fragment'] module-attribute

"auto" will rerun the fragment if it is called from a fragment otherwise it will rerun the app. "app" will rerun the app.

RouteLitElementGenerator = AsyncGenerator[RouteLitElement, None] module-attribute

Async generator type for RouteLitElement instances.

Action dataclass

Source code in src/routelit/domain.py

@dataclass
class Action:
    address: Optional[List[int]]
    """
      (List[int]) The address is the list of indices to the array tree of elements in the session state
      from the root to the target element.
    """
    target: Optional[Literal["app", "fragment"]]
    """
      (Literal["app", "fragment"]) The target is the target of the action.
      If None, the action is applied to the app.
    """

address instance-attribute

(List[int]) The address is the list of indices to the array tree of elements in the session state from the root to the target element.

target instance-attribute

(Literal["app", "fragment"]) The target is the target of the action. If None, the action is applied to the app.

ActionsResponse dataclass

The actions to be executed by the RouteLit app.

Source code in src/routelit/domain.py

@dataclass
class ActionsResponse:
    """
    The actions to be executed by the RouteLit app.
    """

    actions: List[Action]
    target: Literal["app", "fragment"]

AddAction dataclass

Bases: Action

The action to add an element.

Source code in src/routelit/domain.py

@dataclass
class AddAction(Action):
    """
    The action to add an element.
    """

    element: RouteLitElement
    key: str
    type: Literal["add"] = "add"

FreshBoundaryAction dataclass

Bases: Action

The action to mark the fresh boundary of the app or fragment. It means all elements after this action should be stale. This action should be used when streaming, should be just before the first action.

Source code in src/routelit/domain.py

@dataclass
class FreshBoundaryAction(Action):
    """
    The action to mark the fresh boundary of the app or fragment.
    It means all elements after this action should be stale.
    This action should be used when streaming, should be just before the first action.
    """

    type: Literal["fresh_boundary"] = "fresh_boundary"

LastAction dataclass

Bases: Action

The action to mark that no more actions will be yielded after this action.

Source code in src/routelit/domain.py

@dataclass
class LastAction(Action):
    """
    The action to mark that no more actions will be yielded after this action.
    """

    type: Literal["last"] = "last"

NoChangeAction dataclass

Bases: Action

The action to mark that no change will be made.

Source code in src/routelit/domain.py

@dataclass
class NoChangeAction(Action):
    """
    The action to mark that no change will be made.
    """

    type: Literal["no_change"] = "no_change"

RemoveAction dataclass

Bases: Action

The action to remove an element.

Source code in src/routelit/domain.py

@dataclass
class RemoveAction(Action):
    """
    The action to remove an element.
    """

    key: str
    type: Literal["remove"] = "remove"

RouteLitElement dataclass

The element to be rendered by the RouteLit app.

Source code in src/routelit/domain.py

@dataclass
class RouteLitElement:
    """
    The element to be rendered by the RouteLit app.
    """

    ROOT_ELEMENT_NAME: ClassVar[str] = "RLRoot"

    name: str
    props: Dict[str, Any]
    key: str
    children: Optional[List["RouteLitElement"]] = None
    address: Optional[List[int]] = None
    virtual: Optional[bool] = None

    def to_dict(self) -> Dict[str, Any]:
        return {
            "name": self.name,
            "props": self.props,
            "key": self.key,
            "address": self.address,
            "virtual": self.virtual,
        }

    @staticmethod
    def from_dict(data: Dict[str, Any]) -> "RouteLitElement":
        return RouteLitElement(
            name=data["name"],
            props=data["props"],
            key=data["key"],
            children=data.get("children"),
            address=data.get("address"),
            virtual=data.get("virtual"),
        )

    @staticmethod
    def create_root_element() -> "RouteLitElement":
        return RouteLitElement(
            name=RouteLitElement.ROOT_ELEMENT_NAME,
            props={},
            key="",
            children=[],
            address=None,
            virtual=True,
        )

    def append_child(self, child: "RouteLitElement") -> None:
        if self.children is None:
            self.children = []
        self.children.append(child)

    def get_children(self) -> List["RouteLitElement"]:
        if self.children is None:
            self.children = []
        return self.children

RouteLitEvent

Bases: TypedDict

The event to be executed by the RouteLit app.

Source code in src/routelit/domain.py

class RouteLitEvent(TypedDict):
    """
    The event to be executed by the RouteLit app.
    """

    type: Literal["click", "changed", "navigate"]
    componentId: str
    data: Dict[str, Any]
    formId: Optional[str]
    files: Optional[List[IOBase]]
    """
    The files to be uploaded.
    """

files instance-attribute

The files to be uploaded.

RouteLitRequest

Bases: ABC

The request class for the RouteLit app. This class should be implemented by the web framework you want to integrate with.

Source code in src/routelit/domain.py

class RouteLitRequest(ABC):
    """
    The request class for the RouteLit app.
    This class should be implemented by the web framework you want to integrate with.
    """

    def __init__(self) -> None:
        self._ui_event = self._get_ui_event()
        self._fragment_id = self._get_fragment_id()

    @abstractmethod
    def get_headers(self) -> Dict[str, str]:
        pass

    @abstractmethod
    def get_path_params(self) -> Optional[Mapping[str, Any]]:
        pass

    @abstractmethod
    def get_referrer(self) -> Optional[str]:
        pass

    @abstractmethod
    def is_json(self) -> bool:
        pass

    @abstractmethod
    def is_multipart(self) -> bool:
        pass

    @abstractmethod
    def get_json(self) -> Optional[Dict[str, Any]]:
        pass

    @abstractmethod
    def get_files(self) -> Optional[list[IOBase]]:
        pass

    def _get_internal_referrer(self) -> Optional[str]:
        return self.get_headers().get("X-Referer") or self.get_referrer()

    def _get_ui_event(self) -> Optional[RouteLitEvent]:
        if self.is_json() and (json_data := self.get_json()) and isinstance(json_data, dict):
            return json_data.get("uiEvent")
        if self.is_multipart() and (json_data := self.get_json()) and isinstance(json_data, dict):
            body = json_data.get("uiEvent", {}) or {}
            if "data" not in body:
                body["data"] = {}
            maybe_files = self.get_files()
            body["data"]["files"] = (
                [BytesIO(file.read()) for file in maybe_files] if isinstance(maybe_files, list) else maybe_files
            )
            return cast(RouteLitEvent, body)
        else:
            return None

    @property
    def ui_event(self) -> Optional[RouteLitEvent]:
        return self._ui_event

    def clear_event(self) -> None:
        self._ui_event = None

    @abstractmethod
    def get_query_param(self, key: str) -> Optional[str]:
        pass

    @abstractmethod
    def get_query_param_list(self, key: str) -> List[str]:
        pass

    @abstractmethod
    def get_session_id(self) -> str:
        pass

    @abstractmethod
    def get_pathname(self) -> str:
        pass

    @abstractmethod
    def get_host(self) -> str:
        pass

    @property
    @abstractmethod
    def method(self) -> str:
        pass

    def clear_fragment_id(self) -> None:
        self._fragment_id = None

    def _get_fragment_id(self) -> Optional[str]:
        if not self.is_json():
            return None
        json_data = self.get_json()
        if isinstance(json_data, dict):
            return json_data.get("fragmentId")
        return None

    @property
    def fragment_id(self) -> Optional[str]:
        return self._fragment_id

    def get_host_pathname(self, use_referer: bool = False) -> str:
        if use_referer:
            referrer = self._get_internal_referrer()
            if referrer:
                url = urlparse(referrer)
                if url.netloc and url.path:
                    return url.netloc + url.path
        return self.get_host() + self.get_pathname()

    def get_session_keys(self, use_referer: bool = False) -> SessionKeys:
        session_id = self.get_session_id()
        host_pathname = self.get_host_pathname(use_referer)
        ui_session_key = f"{session_id}:{host_pathname}:ui"
        session_state_key = f"{session_id}:{host_pathname}:state"
        fragment_addresses_key = f"{ui_session_key}:fragments"
        fragment_params_key = f"{ui_session_key}:fragment_params"
        view_tasks_key = f"{ui_session_key}:view_tasks"
        return SessionKeys(
            ui_session_key,
            session_state_key,
            fragment_addresses_key,
            fragment_params_key,
            view_tasks_key,
        )

SessionKeys

Bases: NamedTuple

The keys to the session state of the RouteLit app.

Source code in src/routelit/domain.py

class SessionKeys(NamedTuple):
    """
    The keys to the session state of the RouteLit app.
    """

    ui_key: str
    state_key: str
    fragment_addresses_key: str
    """
      Key to the addresses of the fragments in the session state.
      The address is a List of indices to the array tree of elements in the session state
      from the root to the target element.
    """
    fragment_params_key: str
    """
      Key to the parameters of the fragments in the session state.
    """
    view_tasks_key: str
    """
      Key to the view tasks in the session state.
    """

fragment_addresses_key instance-attribute

Key to the addresses of the fragments in the session state. The address is a List of indices to the array tree of elements in the session state from the root to the target element.

fragment_params_key instance-attribute

Key to the parameters of the fragments in the session state.

view_tasks_key instance-attribute

Key to the view tasks in the session state.

SetAction dataclass

Bases: Action

The action to set an element.

Source code in src/routelit/domain.py

@dataclass
class SetAction(Action):
    """
    The action to set an element.
    """

    address: List[int]
    element: Dict[str, Any]
    key: str
    type: Literal["set"] = "set"

UpdateAction dataclass

Bases: Action

The action to update the props of an element.

Source code in src/routelit/domain.py

@dataclass
class UpdateAction(Action):
    """
    The action to update the props of an element.
    """

    props: Dict[str, Any]
    key: str
    type: Literal["update"] = "update"

ViewTaskDoneAction dataclass

Bases: Action

The action to mark that the task is done.

Source code in src/routelit/domain.py

@dataclass
class ViewTaskDoneAction(Action):
    """
    The action to mark that the task is done.
    """

    type: Literal["task_done"] = "task_done"