Skip to content

Support kebab-case parameter names via Annotated[..., Alias("...")] #937

Closed

Description

@renatodamas

Is your feature request related to a problem? Please describe.
FastHTML matches handler argument names exactly against request data, so a parameter named user_id cannot read user-id from query strings, form fields, cookies, or path params. Only headers get hyphen mapping (snake2hyphens), so behavior is inconsistent across sources. Users coming from FastAPI expect an alias mechanism (Query(alias=...)).

Describe the solution you'd like
An opt-in Alias marker used with Annotated. The lookup key becomes the alias for every request source, and the base type is still used for conversion. Parameters without Alias are unchanged.

Example code

from typing import Annotated
from fasthtml.common import Alias

@app.get('/item')
def item(user_id: Annotated[str, Alias("user-id")]): ...

@app.get('/count')
def count(n: Annotated[int, Alias("page-size")]): ...  # int conversion applied

Similar implementations

  1. FastAPI: Query parameter aliases
  2. FastAPI: Header underscore conversion

Problem solved
Lets users use kebab-case names in query strings, forms, cookies, and paths without manual request access, and with consistent behavior across sources. It also fixes a related gap: Annotated[int, ...] is not unwrapped today, so int conversion is silently skipped.

Additional context
Current lookup logic is in _find_p (fasthtml/core.py, source in nbs/api/00_core.ipynb). Acceptance criteria: tests cover each source, missing-field messages, and Annotated[int, Alias] conversion; existing tests pass.

Confirmation

  • [ x ] I have checked the existing issues and pull requests to ensure this feature hasn't been requested before.
  • [ x ] I have read the project's documentation to ensure this feature doesn't already exist

Activity

  1. added 2 commits that reference this issue on Oct 20, 2026
    ed03aee
    71b3e94
  2. renatodamas commented on Oct 21, 2026

    @renatodamas
    ContributorAuthor

    The commit dfc4ea3 has implemented kebab-case parameter support. PR #938 will be revised to focus solely on supporting completely different names for request parameters.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions