Conditional Rendering for HTMX vs Direct Requests

[jaybonthius]

I'm trying to implement endpoints that return:

• Partial HTML for HTMX requests
• Full page HTML for direct browser requests

I'm currently using conditional logic in components to check HX-Request header:

@dataclass
class DemoComponent:
    def htmy(self, context: Context) -> Component:
        request = CurrentRequest.from_context(context)
        is_htmx = "HX-Request" in request.headers

        content = html.div("This is the content of the demo page")

        if is_htmx:
            return content  # Just the content. Will be swapped in by HTMX.
        else:
            return BasePage(content=content)  # Return full page layout.

Is this the intended approach, or does FastHX have a built-in decorator/pattern for automatically handling HTMX vs full page rendering without manual header checking in each component?

The goal is having the same URL work for both HTMX navigation and direct browser access.

By the way: thank you @volfpeter for your work on this library, as well as https://github.com/volfpeter/htmy! I've never had an easier time developing with another stack.

[volfpeter]

Hi,

First of all, thanks for your kind comment! I'm actually considering adding it to the readme as a user testimonial 🙂

Now to the business. Answering such questions is tricky with HTMX, because we're dealing with both the backend, the frontend, and interactions between the two, and a lot of the context (for example API and component architecture) is not available.

Here are some ideas for your code example/use-case:

• This kind of "business logic" is not really something I'd put in a component. I think it belongs to a FastHX ComponentSelector, in your specific case to a custom RequestComponentSelector implementation (similar to ComponentHeader). The only drawback here is that you must use the @page decorator, so the route will never be able to serve JSON.
• An alternative is to always render the full page, and use HX-Select to select what you render when you don't need the full page. I'm not a fan of this pattern though, and it also leads to the unnecessary rendering of a ton of content.

In my projects, I always separate "page" routes (which normally have no business logic, async def page() -> None: ...) and "component" routes (also doesn't have business logic, but only work with HTMX requests). And then of course I have the standard FastAPI REST routes (always wrapped in APIRouter factories) that contain the business logic, decorated with hx() to add the rendering layer. This has several benefits: it results in a multi-purpose API (JSON, HTMX, possibly even MCP); it forces devs to think about separation of concerns, to use components and lazy loading; and so on. This architecture also happens to mostly avoid the problem you are facing (at least in my experience).

I hope I managed to help a bit. If you need more help, my usual recommendation is to get in touch for consulting.

[volfpeter]

I briefly thought about adding a component selector utility for this kind of use-case to the lib, but it's just too specific, and making it generic (e.g. to support not only HTMX or non-HTMX request, but any other, possibly non-binary options) and easy to use is not straightforward.

Having an example implementation (however specific it is) somewhere could be helpful for other users. If you don't mind sharing your version in this discussion, I think it would be a nice contribution.

[jaybonthius]

Sure thing!

I put the component selector in a file called htmy.py (where the fasthx.htmy.HTMY object gets instantiated, like in your Lipsum Chat demo):

class HTMXComponentSelector:
    def __init__(
        self,
        content_factory: Callable[..., Component],
        wrapper_factory: Optional[Callable[[Component], Component]] = None,
    ):
        self.content_factory = content_factory
        self.wrapper_factory = wrapper_factory or (lambda content: page(content))

    def get_component(
        self, request: Request, error: Optional[Exception] = None
    ) -> Callable[..., Component]:
        if error is not None:
            raise error

        is_htmx = "HX-Request" in request.headers
        path_params = getattr(request, "path_params", {})

        if is_htmx:
            return lambda *args, **kwargs: self.content_factory(*args, **kwargs, **path_params)
        else:
            return lambda *args, **kwargs: self.wrapper_factory(
                self.content_factory(*args, **kwargs, **path_params)
            )

So now my route looks like:

@router.get("/demo/{id}", response_model=None)
@htmy.page(HTMXComponentSelector(lambda result, **kwargs: result))
async def demo(id: str, db: AsyncSession = get_db) -> Component:
    return Demo(id, db)

and of course, Demo would have an htmy() method that returns a component.

[jaybonthius]

oh and page in wrapper_factory is a component that is basically my base page.

[volfpeter]

Just to provide more ideas for creating powerful component selectors. The exact implementation would either need to be generic or specific to the templating/rendering engine being used, it may or may not handle errors, and so on, so treat these as pseudocode and implement them as your use-case requires:

@dataclass(frozen=True, slots=True)
class ChainComponentSelector:
    """
    Tries to resolve the component by iterating over a sequence of component selectors,
    returning the result of first one that matches the request.
    """
    selectors: Sequence[ComponentSelector[MyComponentType]]

    def def get_component(self, request: Request, error: Exception | None = None) -> MyComponentType:
        for selector in self.selectors:
            if not isinstance(selector, RequestComponentSelector):
                return selector

            try:
                return selector.get_component(request, error)
            except KeyError:
                ...  # Try the next one

        raise KeyError("component not found")


@dataclass(frozen=True, slots=True)
class PathComponentSelector:
    """
    Selects a component based on the request path. The component key is selected by a regular
    expression that is applied to the path.
    """
    components: dict[str, MyComponentType]
    pattern: re.Pattern[str]

    def get_component(self, request: Request, error: Exception | None = None) -> MyComponentType:
        mtch = re.match(self.pattern, request.url.path)
        if mtch is None:
            raise KeyError("no-match")

        return self.templates[mtch.group(1)]

[volfpeter]

Almost forgot: @jaybonthius thanks for sharing your code! 🙂