From 6f3fce8f706e9aa4e278b58e74b3e65c6c71e400 Mon Sep 17 00:00:00 2001
From: rameel <rameel-b@hotmail.com>
Date: Mon, 26 Oct 2026 20:37:58 +0500
Subject: [PATCH] tag-helpers: generate HTMX request URLs from asp-* attributes

HTMX 4 defines its own hx-action attribute for the request URL, so the
URL Tag Helper turned native markup such as
<button hx-action="/api/users" hx-method="post"> into a GET request to
an MVC action named "/api/users".

Read the standard asp-* routing attributes instead of the hx-* copies.
The Tag Helper now applies only to an element that has an hx-get,
hx-post, hx-put, hx-patch, hx-delete, or HTMX 4 hx-action attribute
written without a value and at least one asp-* routing attribute. It
throws if that attribute has any value, even an empty one, or if
hx-action is used with HTMX 1.9.x or 2.x. It no longer adds hx-get when
no request attribute is present.
---
 README.md                                     |  17 +-
 docs/articles/antiforgery.md                  |  12 +-
 docs/articles/forms-and-validation.md         |  12 +-
 docs/articles/getting-started.md              |  15 +-
 docs/articles/loading-and-errors.md           |   4 +-
 docs/articles/mvc.md                          |  10 +-
 docs/articles/overview.md                     |  15 +-
 docs/articles/pages-and-fragments.md          |   7 +-
 docs/articles/recipes.md                      |  35 +--
 docs/articles/tag-helpers.md                  | 100 +++++---
 docs/articles/troubleshooting.md              |  17 +-
 .../responses/TriggerEventListener.cshtml     |   5 +-
 docs/snippets/tag-helpers/UrlTagHelper.cshtml |   6 +-
 .../Pages/Examples/Antiforgery.cshtml         |   6 +-
 .../Pages/Examples/FluentResponse.cshtml      |  12 +-
 .../Pages/Examples/Headers.cshtml             |   4 +-
 .../Pages/Examples/HtmxRequest.cshtml         |   4 +-
 .../Pages/Examples/HtmxVals.cshtml            |   8 +-
 .../Pages/Examples/MvcAttributes.cshtml       |   6 +-
 .../Pages/Examples/Polling.cshtml             |   4 +-
 .../Pages/Examples/RequestOptions.cshtml      |   4 +-
 .../Pages/Examples/RouteData.cshtml           |  14 +-
 .../Pages/Examples/ServerEvents.cshtml        |   8 +-
 .../Pages/Examples/UrlTagHelper.cshtml        |   7 +-
 .../Pages/Examples/_PollingStatus.cshtml      |  11 +-
 .../TagHelpers/HtmxUrlTagHelper.cs            | 215 ++++++++++++++----
 .../TagHelpers/HtmxUrlTagHelperTests.cs       |  93 +++++++-
 27 files changed, 459 insertions(+), 192 deletions(-)

diff --git a/README.md b/README.md
index 6d4969a..204ba74 100644
--- a/README.md
+++ b/README.md
@@ -75,9 +75,9 @@ See [Static assets](https://rameel.github.io/ramstack.htmxtoolkit/articles/stati
 
 ```html
 <button hx-get
-        hx-controller="Books"
-        hx-action="List"
-        hx-route-category="science"
+        asp-controller="Books"
+        asp-action="List"
+        asp-route-category="science"
         hx-target="#results">
     Show science books
 </button>
@@ -183,15 +183,16 @@ The URL attributes from the example above work with Razor Pages too:
 
 ```html
 <button hx-post
-        hx-page="/Orders"
-        hx-page-handler="Archive"
-        hx-route-id="@Model.Id">
+        asp-page="/Orders"
+        asp-page-handler="Archive"
+        asp-route-id="@Model.Id">
     Archive
 </button>
 ```
 
-The request method comes from `hx-get`, `hx-post`, `hx-put`, `hx-patch`, or `hx-delete`.
-If you leave it out, `hx-get` is used.
+Write one of `hx-get`, `hx-post`, `hx-put`, `hx-patch`, or `hx-delete` without a value to choose
+the request method; the Tag Helper fills in its URL from the `asp-*` attributes.
+Without such an attribute, no URL is generated.
 
 Other Tag Helpers build HTMX attributes that otherwise need hand-written JSON:
 
diff --git a/docs/articles/antiforgery.md b/docs/articles/antiforgery.md
index 26a150d..f123bec 100644
--- a/docs/articles/antiforgery.md
+++ b/docs/articles/antiforgery.md
@@ -76,8 +76,8 @@ For a Razor Page with a `Save` POST handler:
 
 ```razor
 <form hx-post
-      hx-page="/Account/Profile"
-      hx-page-handler="Save"
+      asp-page="/Account/Profile"
+      asp-page-handler="Save"
       hx-target="#save-result">
     <label>
         Display name
@@ -99,10 +99,12 @@ public IActionResult OnPostSave(string? displayName)
 }
 ```
 
-No token input is required in this HTMX form because the layout metadata and Toolkit script supply it.
+The standard Form Tag Helper renders the form `action` and a hidden token input from the same `asp-*` attributes.
+The Toolkit script detects that input and does not add a second token. For HTMX requests without a token input,
+such as a button outside a form, the layout metadata and Toolkit script supply the token.
 The validation message returns 200 so HTMX 2.x displays it with its default response handling.
-For a form that also works without JavaScript, include a normal POST action and let the standard Form Tag Helper
-render a token, as shown in the [forms tutorial](forms-and-validation.md).
+To make the form also work without JavaScript, return a full page for normal requests, as shown in the
+[forms tutorial](forms-and-validation.md).
 
 ## Token refresh after boosted navigation
 
diff --git a/docs/articles/forms-and-validation.md b/docs/articles/forms-and-validation.md
index aa6ba7f..3a82abc 100644
--- a/docs/articles/forms-and-validation.md
+++ b/docs/articles/forms-and-validation.md
@@ -61,11 +61,9 @@ Create `Pages/_ProfileForm.cshtml`:
 
 <form id="profile-editor"
       method="post"
+      hx-post
       asp-page="/Profile"
       asp-page-handler="Save"
-      hx-post
-      hx-page="/Profile"
-      hx-page-handler="Save"
       hx-target="this"
       hx-swap="outerHTML"
       novalidate>
@@ -89,7 +87,8 @@ The form replaces itself with `outerHTML`. Every returned form keeps the same ID
 so it can be submitted again. `novalidate` lets you see the server's validation response without the browser
 blocking an empty submission first. You can remove it when you add browser validation.
 
-The ordinary `method` and `asp-page-*` attributes provide a non-HTMX form action. The standard Form Tag Helper
+The `asp-page` and `asp-page-handler` attributes produce both the `hx-post` URL and, through the standard
+Form Tag Helper, the ordinary form `action`, so the form also works without HTMX. The Form Tag Helper
 also creates a hidden antiforgery input. The Toolkit script detects that input and does not add a second token.
 For forms without that input, the layout metadata and script supply the token instead.
 
@@ -114,8 +113,9 @@ Create `Pages/Profile.cshtml`:
 @await Html.PartialAsync("_ProfileForm", Model)
 
 <aside id="profile-summary"
-       hx-page="/Profile"
-       hx-page-handler="Summary"
+       hx-get
+       asp-page="/Profile"
+       asp-page-handler="Summary"
        hx-trigger="profile-saved from:body"
        aria-live="polite">
     @await Html.PartialAsync("_ProfileSummary", Model.CurrentDisplayName)
diff --git a/docs/articles/getting-started.md b/docs/articles/getting-started.md
index 173d3ca..c4f7235 100644
--- a/docs/articles/getting-started.md
+++ b/docs/articles/getting-started.md
@@ -59,7 +59,7 @@ Replace `Pages/_ViewImports.cshtml` with:
 ```
 
 The standard ASP.NET Core helpers resolve `~/` paths and generate versioned script URLs.
-The toolkit helpers turn attributes such as `hx-page` and `hx-route-id` into HTMX request URLs.
+The toolkit helpers turn standard routing attributes such as `asp-page` and `asp-route-id` into HTMX request URLs.
 You will add the `HtmxStarter.Models` namespace in step 5.
 
 ## 4. Load the browser scripts
@@ -132,9 +132,10 @@ Create `Pages/Products.cshtml`:
 
 <h1>Products</h1>
 
-<button hx-page="/Products"
-        hx-page-handler="Details"
-        hx-route-id="42"
+<button hx-get
+        asp-page="/Products"
+        asp-page-handler="Details"
+        asp-route-id="42"
         hx-target="#product-details">
     View product
 </button>
@@ -181,12 +182,14 @@ Open <http://localhost:5080/Products> and select **View product**. The product d
 Inspect the rendered button. Its routing attributes have become a URL similar to:
 
 ```html
-<button hx-get="/Products?id=42&amp;handler=Details" hx-target="#product-details">
+<button hx-get="/Products?id=42&amp;handler=Details" hx-target="#product-details"
+        formaction="/Products?id=42&amp;handler=Details">
     View product
 </button>
 ```
 
-Query parameter order may differ. The important parts are the page path, `id=42`, and `handler=Details`.
+The standard Form Action Tag Helper renders `formaction` from the same attributes; it matters only
+when the button submits a form. Query parameter order may differ. The important parts are the page path, `id=42`, and `handler=Details`.
 
 In the browser Network panel, the request should have `HX-Request: true`, return HTTP 200,
 and contain only the `<article>` in its response. HTMX's default swap replaces the target's contents,
diff --git a/docs/articles/loading-and-errors.md b/docs/articles/loading-and-errors.md
index 1ba079b..048f87e 100644
--- a/docs/articles/loading-and-errors.md
+++ b/docs/articles/loading-and-errors.md
@@ -14,11 +14,9 @@ In `Pages/_ProfileForm.cshtml`, replace the opening `<form>` tag with:
 ```razor
 <form id="profile-editor"
       method="post"
+      hx-post
       asp-page="/Profile"
       asp-page-handler="Save"
-      hx-post
-      hx-page="/Profile"
-      hx-page-handler="Save"
       hx-target="this"
       hx-swap="outerHTML"
       hx-indicator="#profile-busy"
diff --git a/docs/articles/mvc.md b/docs/articles/mvc.md
index 6cc1afa..cbd9454 100644
--- a/docs/articles/mvc.md
+++ b/docs/articles/mvc.md
@@ -159,9 +159,10 @@ Create `Views/Products/Index.cshtml`:
 ```razor
 <h1>Products</h1>
 
-<button hx-controller="Products"
-        hx-action="Details"
-        hx-route-id="42"
+<button hx-get
+        asp-controller="Products"
+        asp-action="Details"
+        asp-route-id="42"
         hx-target="#product-details">
     View product
 </button>
@@ -202,8 +203,7 @@ Create `Views/Products/_ProductForm.cshtml`:
 @model ProductInput
 
 <form id="product-editor"
-      method="post" asp-controller="Products" asp-action="Save"
-      hx-post hx-controller="Products" hx-action="Save"
+      method="post" hx-post asp-controller="Products" asp-action="Save"
       hx-target="this" hx-swap="outerHTML" novalidate>
     <div asp-validation-summary="All" role="alert"></div>
 
diff --git a/docs/articles/overview.md b/docs/articles/overview.md
index acda13b..c2aab3b 100644
--- a/docs/articles/overview.md
+++ b/docs/articles/overview.md
@@ -50,9 +50,10 @@ or `hx-swap`. Add a supported HTMX release to the application separately.
 For example, write this in a Razor view:
 
 ```razor
-<button hx-page="/Products"
-        hx-page-handler="Details"
-        hx-route-id="42"
+<button hx-get
+        asp-page="/Products"
+        asp-page-handler="Details"
+        asp-route-id="42"
         hx-target="#product-details">
     View product
 </button>
@@ -63,15 +64,17 @@ For example, write this in a Razor view:
 Razor processes the toolkit attributes on the server. The browser receives markup similar to:
 
 ```html
-<button hx-get="/Products?id=42&amp;handler=Details" hx-target="#product-details">
+<button hx-get="/Products?id=42&amp;handler=Details" hx-target="#product-details"
+        formaction="/Products?id=42&amp;handler=Details">
     View product
 </button>
 
 <div id="product-details"></div>
 ```
 
-The query parameter order may differ. `hx-page`, `hx-page-handler`, and `hx-route-*` are server-side inputs;
-HTMX in the browser uses the generated `hx-get`. `hx-target` passes through unchanged.
+The query parameter order may differ. `asp-page`, `asp-page-handler`, and `asp-route-*` are server-side inputs;
+HTMX in the browser uses the generated `hx-get`. The standard Form Action Tag Helper renders `formaction`
+from the same attributes. `hx-target` passes through unchanged.
 
 The page handler returns a partial view:
 
diff --git a/docs/articles/pages-and-fragments.md b/docs/articles/pages-and-fragments.md
index 0eb1403..f695113 100644
--- a/docs/articles/pages-and-fragments.md
+++ b/docs/articles/pages-and-fragments.md
@@ -52,9 +52,10 @@ public IActionResult OnGetInventory(int productId) =>
 ```
 
 ```razor
-<button hx-page="/Products/Details"
-        hx-page-handler="Inventory"
-        hx-route-productid="@Model.Product.Id"
+<button hx-get
+        asp-page="/Products/Details"
+        asp-page-handler="Inventory"
+        asp-route-productid="@Model.Product.Id"
         hx-target="#inventory">
     Check inventory
 </button>
diff --git a/docs/articles/recipes.md b/docs/articles/recipes.md
index e2b5fc6..844a212 100644
--- a/docs/articles/recipes.md
+++ b/docs/articles/recipes.md
@@ -11,8 +11,7 @@ Start with the `ProfileInput`, `ProfileStore`, and bound `Input` property from t
 use this markup in `Pages/Profile.cshtml` instead of `_ProfileForm`:
 
 ```razor
-<form method="post" asp-page-handler="Save"
-      hx-post hx-page="/Profile" hx-page-handler="Save"
+<form method="post" hx-post asp-page="/Profile" asp-page-handler="Save"
       hx-target="#save-result" novalidate>
     <div id="validation-errors" role="alert">
         <div asp-validation-summary="All"></div>
@@ -84,8 +83,9 @@ The [forms tutorial](forms-and-validation.md) includes a complete example: a sav
 and an independent summary requests its latest HTML. Listen on `body` when the source is another component:
 
 ```razor
-<aside hx-page="/Profile"
-       hx-page-handler="Summary"
+<aside hx-get
+       asp-page="/Profile"
+       asp-page-handler="Summary"
        hx-trigger="profile-saved from:body">
 </aside>
 ```
@@ -139,9 +139,10 @@ Create `Pages/Jobs/_Progress.cshtml` (and import the model's namespace in `_View
 else
 {
     <div id="job-progress"
-         hx-page="/Jobs/Status"
-         hx-page-handler="Progress"
-         hx-route-progress="@Model.Percent"
+         hx-get
+         asp-page="/Jobs/Status"
+         asp-page-handler="Progress"
+         asp-route-progress="@Model.Percent"
          hx-trigger="load delay:1s"
          hx-target="this"
          hx-swap="outerHTML">
@@ -256,7 +257,7 @@ Create `Pages/Orders.cshtml`:
 <h1>Orders</h1>
 <ul id="orders"></ul>
 <div id="load-more">
-    <button hx-page="/Orders" hx-page-handler="More" hx-route-after="0"
+    <button hx-get asp-page="/Orders" asp-page-handler="More" asp-route-after="0"
             hx-target="#orders" hx-swap="beforeend">
         Load more
     </button>
@@ -300,7 +301,7 @@ Create `Pages/_OrderBatch.cshtml`:
 <div id="load-more" hx-swap-oob="outerHTML">
     @if (Model.NextCursor is { } cursor)
     {
-        <button hx-page="/Orders" hx-page-handler="More" hx-route-after="@cursor"
+        <button hx-get asp-page="/Orders" asp-page-handler="More" asp-route-after="@cursor"
                 hx-target="#orders" hx-swap="beforeend">
             Load more
         </button>
@@ -326,8 +327,9 @@ Use an input event with a delay so the server receives a request after the user
 <input id="catalog-search"
        name="query"
        type="search"
-       hx-page="/Catalog"
-       hx-page-handler="Search"
+       hx-get
+       asp-page="/Catalog"
+       asp-page-handler="Search"
        hx-trigger="input changed delay:300ms, search"
        hx-target="#search-results"
        hx-request-timeout="5000" />
@@ -363,9 +365,10 @@ Create `Pages/_ProductRow.cshtml` for a display row:
     <td>@Model.Name</td>
     <td>@Model.Price</td>
     <td>
-        <button hx-page="/Products"
-                hx-page-handler="Edit"
-                hx-route-id="@Model.Id"
+        <button hx-get
+                asp-page="/Products"
+                asp-page-handler="Edit"
+                asp-route-id="@Model.Id"
                 hx-target="closest tr"
                 hx-swap="outerHTML">
             Edit
@@ -413,8 +416,8 @@ Create `Pages/_ProductEdit.cshtml`. It posts back to another handler with the sa
 <tr id="product-@Model.Id">
     <td colspan="3">
         <form hx-post
-              hx-page="/Products"
-              hx-page-handler="Save"
+              asp-page="/Products"
+              asp-page-handler="Save"
               hx-target="closest tr"
               hx-swap="outerHTML">
             <div asp-validation-summary="All" role="alert"></div>
diff --git a/docs/articles/tag-helpers.md b/docs/articles/tag-helpers.md
index a893c95..b398176 100644
--- a/docs/articles/tag-helpers.md
+++ b/docs/articles/tag-helpers.md
@@ -15,22 +15,24 @@ Register the namespace and Tag Helpers in `_ViewImports.cshtml`:
 ### Razor Pages
 
 ```razor
-<button hx-page="/Orders/Details"
-        hx-page-handler="Status"
-        hx-route-id="@Model.OrderId"
+<button hx-get
+        asp-page="/Orders/Details"
+        asp-page-handler="Status"
+        asp-route-id="@Model.OrderId"
         hx-target="#order-status">
     Refresh status
 </button>
 ```
 
-This generates `hx-get` because no HTMX method attribute was supplied.
-Add an empty `hx-post`, `hx-put`, `hx-patch`, or `hx-delete` to select another method:
+The Tag Helper reads the standard ASP.NET Core `asp-*` routing attributes and writes the generated URL
+to the HTMX request attribute. Write that attribute without a value; it selects the method:
+`hx-get`, `hx-post`, `hx-put`, `hx-patch`, or `hx-delete`.
 
 ```razor
 <button hx-post
-        hx-page="/Orders/Edit"
-        hx-page-handler="Archive"
-        hx-route-id="@Model.OrderId">
+        asp-page="/Orders/Edit"
+        asp-page-handler="Archive"
+        asp-route-id="@Model.OrderId">
     Archive
 </button>
 ```
@@ -39,10 +41,10 @@ Add an empty `hx-post`, `hx-put`, `hx-patch`, or `hx-delete` to select another m
 
 ```razor
 <button hx-post
-        hx-area="Admin"
-        hx-controller="Users"
-        hx-action="Disable"
-        hx-route-id="@user.Id"
+        asp-area="Admin"
+        asp-controller="Users"
+        asp-action="Disable"
+        asp-route-id="@user.Id"
         hx-target="#user-@user.Id">
     Disable
 </button>
@@ -50,7 +52,7 @@ Add an empty `hx-post`, `hx-put`, `hx-patch`, or `hx-delete` to select another m
 
 ### Named routes and route dictionaries
 
-Name an endpoint, then use that name in `hx-route`. For example, replace the `[HttpGet]` attribute on
+Name an endpoint, then use that name in `asp-route`. For example, replace the `[HttpGet]` attribute on
 the `Details` action in the [MVC tutorial](mvc.md) with:
 
 ```csharp
@@ -68,8 +70,9 @@ The tutorial's `MapDefaultControllerRoute()` also maps this attribute-routed act
 In `Views/Products/Index.cshtml`, use the route name instead of controller and action attributes:
 
 ```razor
-<button hx-route="product-details"
-        hx-route-id="42"
+<button hx-get
+        asp-route="product-details"
+        asp-route-id="42"
         hx-target="#product-panel">
     Product details
 </button>
@@ -77,7 +80,7 @@ In `Views/Products/Index.cshtml`, use the route name instead of controller and a
 <div id="product-panel"></div>
 ```
 
-The generated URL is `/products/42`. Use `hx-all-route-data` when route values are already in a dictionary:
+The generated URL is `/products/42`. Use `asp-all-route-data` when route values are already in a dictionary:
 
 ```razor
 @{
@@ -88,8 +91,9 @@ The generated URL is `/products/42`. Use `hx-all-route-data` when route values a
     };
 }
 
-<button hx-route="product-details"
-        hx-all-route-data="routeValues"
+<button hx-get
+        asp-route="product-details"
+        asp-all-route-data="routeValues"
         hx-target="#product-panel">
     Product details
 </button>
@@ -97,23 +101,62 @@ The generated URL is `/products/42`. Use `hx-all-route-data` when route values a
 
 Here `id` fills the route parameter and `tab` becomes a query parameter: `/products/42?tab=reviews`.
 The action can accept a `string? tab` parameter if it needs that value.
-Use `hx-route-*` for individual values or `hx-all-route-data` for the dictionary.
+Use `asp-route-*` for individual values or `asp-all-route-data` for the dictionary.
 
-`hx-fragment` works like ASP.NET Core's `asp-fragment`: `hx-fragment="reviews"` appends `#reviews`
-to the generated URL. It is a Tag Helper input, not an HTMX attribute. The browser does not send the fragment
+`asp-fragment="reviews"` appends `#reviews` to the generated URL. The browser does not send the fragment
 to the server, so use `hx-target`, not the fragment, to choose the element to update.
 
-Choose one routing mode: `hx-route`, controller/action, or page/handler.
-Combining modes throws an `InvalidOperationException`.
-Supplying more than one HTMX method is also invalid.
+Choose one routing mode: `asp-route`, controller/action, or page/handler.
+Combining modes throws an `InvalidOperationException`. So does supplying more than one HTMX request
+attribute, or an HTMX request attribute with a value, even an empty one such as `hx-get=""`.
+The Tag Helper recognizes the `hx-` prefix only, not `data-hx-`.
+
+### Links, forms, and buttons
+
+The standard ASP.NET Core Tag Helpers process the same `asp-*` attributes on `<a>`, `<form>`, `<button>`,
+and submit or image `<input>` elements. They render `href`, `action`, or `formaction` with the same URL,
+so links and forms keep working without HTMX:
+
+```razor
+<a hx-get asp-page="/Orders/Details" asp-route-id="@Model.OrderId" hx-target="#order">Details</a>
+```
+
+Keep these side effects in mind:
+
+- Add `method="get"` to a `<form hx-get>`. Otherwise the Form Tag Helper renders `method="post"` and
+  a hidden antiforgery input, and HTMX sends the token in the query string.
+- A link always gets a working `href`, which a browser can follow with an ordinary GET request,
+  for example when the link is opened in a new tab or prefetched. Use a `<button>` rather than `<a>`
+  for `hx-post`, `hx-put`, `hx-patch`, and `hx-delete`.
+- On other elements, the Tag Helper processes `asp-*` attributes only together with an HTMX request
+  attribute. Without one, they are rendered unchanged.
+
+### HTMX 4.x `hx-action`
+
+HTMX 4.x can take the URL from `hx-action` and the method from `hx-method`.
+Write `hx-action` without a value to have the Tag Helper fill it:
+
+```razor
+<button hx-action
+        hx-method="post"
+        asp-page="/Orders/Edit"
+        asp-page-handler="Archive"
+        asp-route-id="@Model.OrderId">
+    Archive
+</button>
+```
+
+An `hx-action` that already has a URL and no `asp-*` attributes is left as is. With HTMX 1.9.x or 2.x,
+which do not support `hx-action`, an `hx-action` without a value and with `asp-*` attributes throws an `InvalidOperationException`.
 
 ## Send additional values
 
 Use `hx-val-*` when fixed values should be included as request parameters:
 
 ```razor
-<button hx-page="/Reports"
-        hx-page-handler="Preview"
+<button hx-get
+        asp-page="/Reports"
+        asp-page-handler="Preview"
         hx-val-category="science"
         hx-val-format="summary"
         hx-target="#preview">
@@ -189,8 +232,9 @@ Authenticate and authorize on the server.
 Use `hx-request-*` attributes rather than hand-writing version-specific JSON:
 
 ```razor
-<button hx-page="/Reports"
-        hx-page-handler="Preview"
+<button hx-get
+        asp-page="/Reports"
+        asp-page-handler="Preview"
         hx-request-timeout="2000"
         hx-request-credentials="@HtmxRequestCredentials.SameOrigin"
         hx-target="#preview">
diff --git a/docs/articles/troubleshooting.md b/docs/articles/troubleshooting.md
index 24d9fb3..40e800f 100644
--- a/docs/articles/troubleshooting.md
+++ b/docs/articles/troubleshooting.md
@@ -9,7 +9,7 @@ If the Network panel shows no request, check the browser setup before debugging
 
 1. Confirm that the HTMX script returns JavaScript with HTTP 200. A NuGet reference does not install HTMX.
 2. Look for console errors, including `htmx is not defined` when the Toolkit script loads too early.
-3. Inspect the rendered element. It should have a real `hx-get` or `hx-post` URL, not only `hx-page` or `hx-action`.
+3. Inspect the rendered element. It should have a real `hx-get`, `hx-post`, or HTMX 4.x `hx-action` URL, not an attribute without a value next to `asp-page` or `asp-action`.
 4. Check whether HTML form validation is blocking submission. An invalid required input can prevent a request.
 5. Check that the element's trigger matches the interaction, especially if you changed `hx-trigger`.
 
@@ -17,7 +17,7 @@ Use the explicit script setup in [Getting started](getting-started.md#4-load-the
 
 ## Tag Helper attributes appear unchanged
 
-**Symptom:** The rendered HTML still contains `hx-page`, `hx-action`, `hx-route-*`, or `hx-request-timeout`.
+**Symptom:** The rendered HTML still contains `asp-page`, `asp-action`, `asp-route-*`, or `hx-request-timeout`.
 
 **Check:** Ensure `_ViewImports.cshtml` applies to the view and contains:
 
@@ -26,6 +26,8 @@ Use the explicit script setup in [Getting started](getting-started.md#4-load-the
 ```
 
 Also verify the project references `Ramstack.HtmxToolkit` and uses only one routing mode per element.
+The URL Tag Helper processes `asp-*` attributes only on an element that also has an `hx-get`, `hx-post`,
+`hx-put`, `hx-patch`, `hx-delete`, or, for HTMX 4.x, `hx-action` attribute without a value.
 
 ## A full page is inserted into a target
 
@@ -235,12 +237,13 @@ Leave it `Unspecified` to accept requests without that header.
 
 Choose exactly one routing mode:
 
-- named route: `hx-route`;
-- MVC: `hx-controller` and/or `hx-action`;
-- Razor Pages: `hx-page` and/or `hx-page-handler`.
+- named route: `asp-route`;
+- MVC: `asp-controller` and/or `asp-action`;
+- Razor Pages: `asp-page` and/or `asp-page-handler`.
 
-Choose at most one method from `hx-get`, `hx-post`, `hx-put`, `hx-patch`, and `hx-delete`.
-If no method is present, the URL Tag Helper generates `hx-get`.
+Use exactly one HTMX request attribute without a value: `hx-get`, `hx-post`, `hx-put`, `hx-patch`, `hx-delete`,
+or, for HTMX 4.x, `hx-action`. Even an empty value, such as `hx-get=""`, is an error. Remove the value,
+or remove the `asp-*` attributes if the URL is written by hand.
 
 ## Event timing differs after moving to HTMX 4
 
diff --git a/docs/snippets/responses/TriggerEventListener.cshtml b/docs/snippets/responses/TriggerEventListener.cshtml
index ae267e5..8c462ef 100644
--- a/docs/snippets/responses/TriggerEventListener.cshtml
+++ b/docs/snippets/responses/TriggerEventListener.cshtml
@@ -1,8 +1,9 @@
 @addTagHelper *, Ramstack.HtmxToolkit
 
 @* Place the listener outside the form, so the save response does not replace it. *@
-<aside hx-page="/Profile"
-       hx-page-handler="Summary"
+<aside hx-get
+       asp-page="/Profile"
+       asp-page-handler="Summary"
        hx-trigger="profile-saved from:body">
     ...
 </aside>
diff --git a/docs/snippets/tag-helpers/UrlTagHelper.cshtml b/docs/snippets/tag-helpers/UrlTagHelper.cshtml
index af711c8..6710653 100644
--- a/docs/snippets/tag-helpers/UrlTagHelper.cshtml
+++ b/docs/snippets/tag-helpers/UrlTagHelper.cshtml
@@ -1,9 +1,9 @@
 @addTagHelper *, Ramstack.HtmxToolkit
 
 <button hx-post
-        hx-page="/Orders/Edit"
-        hx-page-handler="Archive"
-        hx-route-id="@Model.OrderId"
+        asp-page="/Orders/Edit"
+        asp-page-handler="Archive"
+        asp-route-id="@Model.OrderId"
         hx-target="#order-status">
     Archive
 </button>
diff --git a/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/Antiforgery.cshtml b/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/Antiforgery.cshtml
index f31d219..a6dfbeb 100644
--- a/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/Antiforgery.cshtml
+++ b/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/Antiforgery.cshtml
@@ -14,13 +14,13 @@
   <section class="demo-card">
     <div class="demo-card__header">
       <h2><code>hx-post</code> with antiforgery</h2>
-      <p>Razor Pages validates the POST automatically. <code>&lt;htmx-config /&gt;</code> renders the token and the toolkit script attaches it to the request.</p>
+      <p>Razor Pages validates the POST automatically. The Form Tag Helper renders the token as a hidden field of the form. For HTMX requests without that field, <code>&lt;htmx-config /&gt;</code> renders the token and the toolkit script attaches it to the request.</p>
     </div>
 
     <form class="demo-form"
           hx-post
-          hx-page="/Examples/Antiforgery"
-          hx-page-handler="Save"
+          asp-page="/Examples/Antiforgery"
+          asp-page-handler="Save"
           hx-target="#form-result">
       <label>
         Display name
diff --git a/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/FluentResponse.cshtml b/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/FluentResponse.cshtml
index 524bca3..416f51c 100644
--- a/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/FluentResponse.cshtml
+++ b/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/FluentResponse.cshtml
@@ -19,17 +19,17 @@
 
     <div class="demo-actions">
       <button hx-get
-              hx-page="/Examples/FluentResponse"
-              hx-page-handler="Product"
-              hx-route-sku="BOOK-42"
+              asp-page="/Examples/FluentResponse"
+              asp-page-handler="Product"
+              asp-route-sku="BOOK-42"
               hx-target="#product-result">
         Find BOOK-42
       </button>
       <button class="button-secondary"
               hx-get
-              hx-page="/Examples/FluentResponse"
-              hx-page-handler="Product"
-              hx-route-sku="BOOK-00"
+              asp-page="/Examples/FluentResponse"
+              asp-page-handler="Product"
+              asp-route-sku="BOOK-00"
               hx-target="#product-result">
         Find BOOK-00
       </button>
diff --git a/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/Headers.cshtml b/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/Headers.cshtml
index 3174200..865a92a 100644
--- a/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/Headers.cshtml
+++ b/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/Headers.cshtml
@@ -19,8 +19,8 @@
     <div class="demo-actions">
       <button
         hx-get
-        hx-page="/Examples/Headers"
-        hx-page-handler="Show"
+        asp-page="/Examples/Headers"
+        asp-page-handler="Show"
         hx-header-X-Report-Format="summary"
         hx-target="#header-result">
         Request summary report
diff --git a/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/HtmxRequest.cshtml b/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/HtmxRequest.cshtml
index 578ca8a..16e42b5 100644
--- a/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/HtmxRequest.cshtml
+++ b/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/HtmxRequest.cshtml
@@ -21,8 +21,8 @@
       <button
         id="check-order"
         hx-get
-        hx-page="/Examples/HtmxRequest"
-        hx-route-id="1042"
+        asp-page="/Examples/HtmxRequest"
+        asp-route-id="1042"
         hx-target="#order-status">
         Check inline
       </button>
diff --git a/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/HtmxVals.cshtml b/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/HtmxVals.cshtml
index 6b889ff..ed2d25c 100644
--- a/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/HtmxVals.cshtml
+++ b/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/HtmxVals.cshtml
@@ -20,8 +20,8 @@
     <div class="demo-actions">
       <button
         hx-get
-        hx-page="/Examples/HtmxVals"
-        hx-page-handler="Show"
+        asp-page="/Examples/HtmxVals"
+        asp-page-handler="Show"
         hx-val-category="science"
         hx-val-format="summary"
         hx-target="#values-result">
@@ -30,8 +30,8 @@
       <button
         class="button button-secondary"
         hx-get
-        hx-page="/Examples/HtmxVals"
-        hx-page-handler="Show"
+        asp-page="/Examples/HtmxVals"
+        asp-page-handler="Show"
         hx-all-vals="@(new Dictionary<string, string> { { "category", "history" }, { "format", "full" } })"
         hx-target="#values-result">
         Preview full history report
diff --git a/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/MvcAttributes.cshtml b/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/MvcAttributes.cshtml
index 97071e5..0def85b 100644
--- a/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/MvcAttributes.cshtml
+++ b/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/MvcAttributes.cshtml
@@ -18,9 +18,9 @@
 
     <div class="demo-actions">
       <button hx-get
-              hx-controller="Inventory"
-              hx-action="Status"
-              hx-route-sku="BOOK-42"
+              asp-controller="Inventory"
+              asp-action="Status"
+              asp-route-sku="BOOK-42"
               hx-target="#inventory-status">
         Check inventory
       </button>
diff --git a/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/Polling.cshtml b/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/Polling.cshtml
index 80108e3..ca5449a 100644
--- a/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/Polling.cshtml
+++ b/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/Polling.cshtml
@@ -20,8 +20,8 @@
     <div id="job-progress" class="job-progress job-progress--idle">
       <p>Start the simulated job to see server-controlled polling in action.</p>
       <button hx-post
-              hx-page="/Examples/Polling"
-              hx-page-handler="Start"
+              asp-page="/Examples/Polling"
+              asp-page-handler="Start"
               hx-target="#job-progress"
               hx-swap="outerMorph">
         Start job
diff --git a/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/RequestOptions.cshtml b/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/RequestOptions.cshtml
index 273593b..0617195 100644
--- a/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/RequestOptions.cshtml
+++ b/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/RequestOptions.cshtml
@@ -19,8 +19,8 @@
 
     <div class="demo-actions">
       <button hx-get
-              hx-page="/Examples/RequestOptions"
-              hx-page-handler="Preview"
+              asp-page="/Examples/RequestOptions"
+              asp-page-handler="Preview"
               hx-request-timeout="2000"
               hx-request-cache="@HtmxRequestCache.NoCache"
               hx-request-redirect="@HtmxRequestRedirect.Error"
diff --git a/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/RouteData.cshtml b/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/RouteData.cshtml
index 4686e50..c49b65a 100644
--- a/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/RouteData.cshtml
+++ b/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/RouteData.cshtml
@@ -13,24 +13,24 @@
 
   <section class="demo-card">
     <div class="demo-card__header">
-      <h2><code>hx-route-*</code> and <code>hx-all-route-data</code></h2>
+      <h2><code>asp-route-*</code> and <code>asp-all-route-data</code></h2>
       <p>Both buttons generate a handler URL without assembling a query string.</p>
     </div>
 
     <div class="demo-actions">
       <button
         hx-get
-        hx-page="/Examples/RouteData"
-        hx-page-handler="Order"
-        hx-route-id="1042"
+        asp-page="/Examples/RouteData"
+        asp-page-handler="Order"
+        asp-route-id="1042"
         hx-target="#order-result">
         Load order #1042
       </button>
       <button
         hx-get
-        hx-page="/Examples/RouteData"
-        hx-page-handler="Order"
-        hx-all-route-data="@(new Dictionary<string, string> { ["id"] = "1088" })"
+        asp-page="/Examples/RouteData"
+        asp-page-handler="Order"
+        asp-all-route-data="@(new Dictionary<string, string> { ["id"] = "1088" })"
         hx-target="#order-result"
         class="button-secondary">
         Load order #1088
diff --git a/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/ServerEvents.cshtml b/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/ServerEvents.cshtml
index b36417e..1978fc3 100644
--- a/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/ServerEvents.cshtml
+++ b/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/ServerEvents.cshtml
@@ -19,8 +19,8 @@
 
     <form class="demo-form"
           hx-post
-          hx-page="/Examples/ServerEvents"
-          hx-page-handler="Save"
+          asp-page="/Examples/ServerEvents"
+          asp-page-handler="Save"
           hx-target="#save-result">
       <label>
         Display name
@@ -37,8 +37,8 @@
     <div id="profile-summary"
          class="result"
          hx-get
-         hx-page="/Examples/ServerEvents"
-         hx-page-handler="Summary"
+         asp-page="/Examples/ServerEvents"
+         asp-page-handler="Summary"
          hx-trigger="profileSaved from:body"
          hx-include="#display-name">
       The profile summary has not been refreshed.
diff --git a/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/UrlTagHelper.cshtml b/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/UrlTagHelper.cshtml
index f30f205..8f52c00 100644
--- a/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/UrlTagHelper.cshtml
+++ b/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/UrlTagHelper.cshtml
@@ -13,14 +13,15 @@
 
   <section class="demo-card">
     <div class="demo-card__header">
-      <h2><code>hx-page</code> + <code>hx-page-handler</code></h2>
+      <h2><code>asp-page</code> + <code>asp-page-handler</code></h2>
       <p>The toolkit generates <code>hx-get</code>, so the URL stays in sync with ASP.NET Core routing.</p>
     </div>
 
     <div class="demo-actions">
       <button
-        hx-page="/Examples/UrlTagHelper"
-        hx-page-handler="Status"
+        hx-get
+        asp-page="/Examples/UrlTagHelper"
+        asp-page-handler="Status"
         hx-target="#result">
         Check service status
       </button>
diff --git a/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/_PollingStatus.cshtml b/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/_PollingStatus.cshtml
index 6c4f832..92af063 100644
--- a/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/_PollingStatus.cshtml
+++ b/samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/_PollingStatus.cshtml
@@ -19,8 +19,8 @@
     </div>
     <button class="button-secondary"
             hx-post
-            hx-page="/Examples/Polling"
-            hx-page-handler="Start"
+            asp-page="/Examples/Polling"
+            asp-page-handler="Start"
             hx-target="#job-progress"
             hx-swap="outerMorph">
       Run again
@@ -30,9 +30,10 @@
 else
 {
   <div id="job-progress" class="job-progress"
-       hx-get hx-page="/Examples/Polling"
-       hx-page-handler="Progress"
-       hx-route-progress="@Model.Percent"
+       hx-get
+       asp-page="/Examples/Polling"
+       asp-page-handler="Progress"
+       asp-route-progress="@Model.Percent"
        hx-trigger="every 400ms"
        hx-swap="outerMorph">
     <div class="job-progress__meta">
diff --git a/src/Ramstack.HtmxToolkit/TagHelpers/HtmxUrlTagHelper.cs b/src/Ramstack.HtmxToolkit/TagHelpers/HtmxUrlTagHelper.cs
index 5054225..da5d69d 100644
--- a/src/Ramstack.HtmxToolkit/TagHelpers/HtmxUrlTagHelper.cs
+++ b/src/Ramstack.HtmxToolkit/TagHelpers/HtmxUrlTagHelper.cs
@@ -8,63 +8,135 @@
 using Microsoft.AspNetCore.Mvc.ViewFeatures;
 using Microsoft.AspNetCore.Razor.TagHelpers;
 using Microsoft.AspNetCore.Routing;
+using Microsoft.Extensions.Options;
 
 using Ramstack.HtmxToolkit.Collections;
+using Ramstack.HtmxToolkit.Configuration;
 
 namespace Ramstack.HtmxToolkit.TagHelpers;
 
 /// <summary>
-/// Generates URLs for HTMX request attributes on matching elements.
+/// Generates URLs for HTMX request attributes from the standard ASP.NET Core <c>asp-*</c> routing attributes.
 /// </summary>
 /// <param name="factory">The factory used to create URL helpers.</param>
+/// <param name="options">The configured HtmxToolkit options.</param>
 /// <remarks>
 /// <para>
-///   The URL is written to the existing <c>hx-get</c>, <c>hx-post</c>, <c>hx-put</c>,
-///   <c>hx-patch</c>, or <c>hx-delete</c> attribute. If none of them is present,
-///   the tag helper adds <c>hx-get</c>.
+///   The tag helper applies to elements that have an <c>hx-get</c>, <c>hx-post</c>, <c>hx-put</c>,
+///   <c>hx-patch</c>, <c>hx-delete</c>, or HTMX 4.x <c>hx-action</c> attribute together with
+///   at least one of the <c>asp-action</c>, <c>asp-controller</c>, <c>asp-area</c>, <c>asp-page</c>,
+///   <c>asp-page-handler</c>, <c>asp-route</c>, <c>asp-route-*</c>, <c>asp-all-route-data</c>,
+///   <c>asp-host</c>, <c>asp-protocol</c>, or <c>asp-fragment</c> attributes.
+///   The generated URL is written to the HTMX attribute, which must not have a value.
 /// </para>
 /// <para>
-///   An <see cref="InvalidOperationException" /> is thrown when more than one of these
-///   attributes is present, or when attributes from more than one of the following groups
-///   are specified: <c>hx-route</c>; <c>hx-controller</c> and <c>hx-action</c>;
-///   <c>hx-page</c> and <c>hx-page-handler</c>.
+///   On <c>&lt;a&gt;</c>, <c>&lt;form&gt;</c>, <c>&lt;button&gt;</c>, and submit or image
+///   <c>&lt;input&gt;</c> elements, the built-in ASP.NET Core tag helpers process the same
+///   <c>asp-*</c> attributes and also render <c>href</c>, <c>action</c>, or <c>formaction</c>.
+/// </para>
+/// <para>
+///   An <see cref="InvalidOperationException" /> is thrown when more than one HTMX request attribute
+///   is present, when the HTMX request attribute has a value, even an empty one, when <c>hx-action</c> is used
+///   with a version other than HTMX 4.x, or when attributes from more than one of the following
+///   groups are specified: <c>asp-route</c>; <c>asp-controller</c> and <c>asp-action</c>;
+///   <c>asp-page</c> and <c>asp-page-handler</c>.
 /// </para>
 /// </remarks>
-[HtmlTargetElement(Attributes = ActionAttributeName)]
-[HtmlTargetElement(Attributes = ControllerAttributeName)]
-[HtmlTargetElement(Attributes = AreaAttributeName)]
-[HtmlTargetElement(Attributes = PageAttributeName)]
-[HtmlTargetElement(Attributes = PageHandlerAttributeName)]
-[HtmlTargetElement(Attributes = RouteAttributeName)]
-[HtmlTargetElement(Attributes = RouteValuesDictionaryName)]
-[HtmlTargetElement(Attributes = RouteValuesPrefix + "*")]
-[HtmlTargetElement(Attributes = HostAttributeName)]
-[HtmlTargetElement(Attributes = ProtocolAttributeName)]
-[HtmlTargetElement(Attributes = FragmentAttributeName)]
+[HtmlTargetElement(Attributes = "hx-get," + ActionAttributeName)]
+[HtmlTargetElement(Attributes = "hx-get," + ControllerAttributeName)]
+[HtmlTargetElement(Attributes = "hx-get," + AreaAttributeName)]
+[HtmlTargetElement(Attributes = "hx-get," + PageAttributeName)]
+[HtmlTargetElement(Attributes = "hx-get," + PageHandlerAttributeName)]
+[HtmlTargetElement(Attributes = "hx-get," + RouteAttributeName)]
+[HtmlTargetElement(Attributes = "hx-get," + RouteValuesDictionaryName)]
+[HtmlTargetElement(Attributes = "hx-get," + RouteValuesPrefix + "*")]
+[HtmlTargetElement(Attributes = "hx-get," + HostAttributeName)]
+[HtmlTargetElement(Attributes = "hx-get," + ProtocolAttributeName)]
+[HtmlTargetElement(Attributes = "hx-get," + FragmentAttributeName)]
+[HtmlTargetElement(Attributes = "hx-post," + ActionAttributeName)]
+[HtmlTargetElement(Attributes = "hx-post," + ControllerAttributeName)]
+[HtmlTargetElement(Attributes = "hx-post," + AreaAttributeName)]
+[HtmlTargetElement(Attributes = "hx-post," + PageAttributeName)]
+[HtmlTargetElement(Attributes = "hx-post," + PageHandlerAttributeName)]
+[HtmlTargetElement(Attributes = "hx-post," + RouteAttributeName)]
+[HtmlTargetElement(Attributes = "hx-post," + RouteValuesDictionaryName)]
+[HtmlTargetElement(Attributes = "hx-post," + RouteValuesPrefix + "*")]
+[HtmlTargetElement(Attributes = "hx-post," + HostAttributeName)]
+[HtmlTargetElement(Attributes = "hx-post," + ProtocolAttributeName)]
+[HtmlTargetElement(Attributes = "hx-post," + FragmentAttributeName)]
+[HtmlTargetElement(Attributes = "hx-put," + ActionAttributeName)]
+[HtmlTargetElement(Attributes = "hx-put," + ControllerAttributeName)]
+[HtmlTargetElement(Attributes = "hx-put," + AreaAttributeName)]
+[HtmlTargetElement(Attributes = "hx-put," + PageAttributeName)]
+[HtmlTargetElement(Attributes = "hx-put," + PageHandlerAttributeName)]
+[HtmlTargetElement(Attributes = "hx-put," + RouteAttributeName)]
+[HtmlTargetElement(Attributes = "hx-put," + RouteValuesDictionaryName)]
+[HtmlTargetElement(Attributes = "hx-put," + RouteValuesPrefix + "*")]
+[HtmlTargetElement(Attributes = "hx-put," + HostAttributeName)]
+[HtmlTargetElement(Attributes = "hx-put," + ProtocolAttributeName)]
+[HtmlTargetElement(Attributes = "hx-put," + FragmentAttributeName)]
+[HtmlTargetElement(Attributes = "hx-patch," + ActionAttributeName)]
+[HtmlTargetElement(Attributes = "hx-patch," + ControllerAttributeName)]
+[HtmlTargetElement(Attributes = "hx-patch," + AreaAttributeName)]
+[HtmlTargetElement(Attributes = "hx-patch," + PageAttributeName)]
+[HtmlTargetElement(Attributes = "hx-patch," + PageHandlerAttributeName)]
+[HtmlTargetElement(Attributes = "hx-patch," + RouteAttributeName)]
+[HtmlTargetElement(Attributes = "hx-patch," + RouteValuesDictionaryName)]
+[HtmlTargetElement(Attributes = "hx-patch," + RouteValuesPrefix + "*")]
+[HtmlTargetElement(Attributes = "hx-patch," + HostAttributeName)]
+[HtmlTargetElement(Attributes = "hx-patch," + ProtocolAttributeName)]
+[HtmlTargetElement(Attributes = "hx-patch," + FragmentAttributeName)]
+[HtmlTargetElement(Attributes = "hx-delete," + ActionAttributeName)]
+[HtmlTargetElement(Attributes = "hx-delete," + ControllerAttributeName)]
+[HtmlTargetElement(Attributes = "hx-delete," + AreaAttributeName)]
+[HtmlTargetElement(Attributes = "hx-delete," + PageAttributeName)]
+[HtmlTargetElement(Attributes = "hx-delete," + PageHandlerAttributeName)]
+[HtmlTargetElement(Attributes = "hx-delete," + RouteAttributeName)]
+[HtmlTargetElement(Attributes = "hx-delete," + RouteValuesDictionaryName)]
+[HtmlTargetElement(Attributes = "hx-delete," + RouteValuesPrefix + "*")]
+[HtmlTargetElement(Attributes = "hx-delete," + HostAttributeName)]
+[HtmlTargetElement(Attributes = "hx-delete," + ProtocolAttributeName)]
+[HtmlTargetElement(Attributes = "hx-delete," + FragmentAttributeName)]
+[HtmlTargetElement(Attributes = "hx-action," + ActionAttributeName)]
+[HtmlTargetElement(Attributes = "hx-action," + ControllerAttributeName)]
+[HtmlTargetElement(Attributes = "hx-action," + AreaAttributeName)]
+[HtmlTargetElement(Attributes = "hx-action," + PageAttributeName)]
+[HtmlTargetElement(Attributes = "hx-action," + PageHandlerAttributeName)]
+[HtmlTargetElement(Attributes = "hx-action," + RouteAttributeName)]
+[HtmlTargetElement(Attributes = "hx-action," + RouteValuesDictionaryName)]
+[HtmlTargetElement(Attributes = "hx-action," + RouteValuesPrefix + "*")]
+[HtmlTargetElement(Attributes = "hx-action," + HostAttributeName)]
+[HtmlTargetElement(Attributes = "hx-action," + ProtocolAttributeName)]
+[HtmlTargetElement(Attributes = "hx-action," + FragmentAttributeName)]
 [RequiresUnreferencedCode("Razor Page URL generation is not compatible with trimming.")]
-public sealed class HtmxUrlTagHelper(IUrlHelperFactory factory) : TagHelper
+public sealed class HtmxUrlTagHelper(IUrlHelperFactory factory, IOptions<HtmxToolkitOptions> options) : TagHelper
 {
-    private const string ActionAttributeName = "hx-action";
-    private const string ControllerAttributeName = "hx-controller";
-    private const string AreaAttributeName = "hx-area";
-    private const string PageAttributeName = "hx-page";
-    private const string PageHandlerAttributeName = "hx-page-handler";
-    private const string FragmentAttributeName = "hx-fragment";
-    private const string HostAttributeName = "hx-host";
-    private const string ProtocolAttributeName = "hx-protocol";
-    private const string RouteAttributeName = "hx-route";
-    private const string RouteValuesDictionaryName = "hx-all-route-data";
-    private const string RouteValuesPrefix = "hx-route-";
-
-    private static readonly string[] s_methods = ["hx-get", "hx-post", "hx-delete", "hx-put", "hx-patch"];
+    private const string ActionAttributeName = "asp-action";
+    private const string ControllerAttributeName = "asp-controller";
+    private const string AreaAttributeName = "asp-area";
+    private const string PageAttributeName = "asp-page";
+    private const string PageHandlerAttributeName = "asp-page-handler";
+    private const string FragmentAttributeName = "asp-fragment";
+    private const string HostAttributeName = "asp-host";
+    private const string ProtocolAttributeName = "asp-protocol";
+    private const string RouteAttributeName = "asp-route";
+    private const string RouteValuesDictionaryName = "asp-all-route-data";
+    private const string RouteValuesPrefix = "asp-route-";
+    private const string HxActionAttributeName = "hx-action";
+
+    private static readonly string[] s_requestAttributes = ["hx-get", "hx-post", "hx-delete", "hx-put", "hx-patch", "hx-action"];
 
     private IDictionary<string, string>? _routeValues;
 
     /// <inheritdoc />
     /// <remarks>
-    /// Runs before tag helpers with the default order, so that they see the generated URL attribute.
+    /// Runs after the built-in ASP.NET Core tag helpers that process the same <c>asp-*</c> attributes (-1000)
+    /// and before tag helpers with the default order, so that they see the generated URL attribute.
+    /// The value lies between -1000 and the built-in
+    /// <see cref="Microsoft.AspNetCore.Mvc.TagHelpers.RenderAtEndOfFormTagHelper" /> (-900),
+    /// leaving room for tag helpers that need to run before or after this one.
     /// </remarks>
-    public override int Order => -1000;
+    public override int Order => -950;
 
     /// <summary>
     /// Gets or sets the name of the route.
@@ -169,6 +241,10 @@ public IDictionary<string, string> RouteValues
     /// <inheritdoc />
     public override Task ProcessAsync(TagHelperContext context, TagHelperOutput output)
     {
+        var name = GetRequestAttributeName(output);
+        if (name is null)
+            return Task.CompletedTask;
+
         var routeLink = Route != null;
         var actionLink = Controller != null || Action != null;
         var pageLink = Page != null || PageHandler != null;
@@ -182,7 +258,7 @@ public override Task ProcessAsync(TagHelperContext context, TagHelperOutput outp
 
         if (Area is not null)
         {
-            // Unconditionally replace any existing area route value with the value from hx-area.
+            // Unconditionally replace any existing area route value with the value from asp-area.
             routeValues ??= new RouteValueDictionary();
             routeValues["area"] = Area;
         }
@@ -220,23 +296,43 @@ public override Task ProcessAsync(TagHelperContext context, TagHelperOutput outp
                 fragment: Fragment);
         }
 
-        string? definedMethod = null;
+        output.Attributes.SetAttribute(name, url);
+
+        return Task.CompletedTask;
+    }
+
+    /// <summary>
+    /// Returns the name of the HTMX request attribute that receives the generated URL.
+    /// </summary>
+    /// <param name="output">The tag helper output to inspect.</param>
+    /// <returns>
+    /// The name of the HTMX request attribute, or <see langword="null" /> if the element has none.
+    /// </returns>
+    private string? GetRequestAttributeName(TagHelperOutput output)
+    {
+        string? name = null;
 
-        foreach (var method in s_methods)
+        foreach (var attributeName in s_requestAttributes)
         {
-            if (output.Attributes[method] is null)
+            var attribute = output.Attributes[attributeName];
+            if (attribute is null)
                 continue;
 
-            if (definedMethod is not null)
-                Error_AmbiguousMethods();
+            if (name is not null)
+                Error_AmbiguousRequestAttributes();
+
+            // Accept only an attribute written without a value, such as <button hx-post>.
+            // Any value, even an empty one, is rejected rather than guessed to mean "no URL".
+            if (attribute.ValueStyle != HtmlAttributeValueStyle.Minimized)
+                Error_RequestAttributeHasValue(attributeName);
 
-            definedMethod = method;
+            name = attributeName;
         }
 
-        var attribute = new TagHelperAttribute(definedMethod ?? "hx-get", url);
-        output.Attributes.SetAttribute(attribute);
+        if (name == HxActionAttributeName && options.Value.TargetVersion != HtmxTargetVersion.V4)
+            Error_HxActionRequiresHtmx4();
 
-        return Task.CompletedTask;
+        return name;
     }
 
     /// <summary>
@@ -256,13 +352,36 @@ private static void Error_CannotDetermineUrl()
     }
 
     /// <summary>
-    /// Throws an exception indicating that multiple HTMX method attributes were specified.
+    /// Throws an exception indicating that multiple HTMX request attributes were specified.
+    /// </summary>
+    /// <exception cref="InvalidOperationException">Always thrown.</exception>
+    [DoesNotReturn]
+    private static void Error_AmbiguousRequestAttributes()
+    {
+        const string Message = "Ambiguous HTMX request. Only one of the following attributes is allowed: hx-get, hx-post, hx-delete, hx-put, hx-patch, hx-action";
+        throw new InvalidOperationException(Message);
+    }
+
+    /// <summary>
+    /// Throws an exception indicating that the HTMX request attribute has a value.
+    /// </summary>
+    /// <param name="attributeName">The name of the HTMX request attribute.</param>
+    /// <exception cref="InvalidOperationException">Always thrown.</exception>
+    [DoesNotReturn]
+    private static void Error_RequestAttributeHasValue(string attributeName)
+    {
+        var message = $"The {attributeName} attribute must be written without a value to receive the URL generated from the asp-* attributes. Remove its value, or remove the asp-* attributes.";
+        throw new InvalidOperationException(message);
+    }
+
+    /// <summary>
+    /// Throws an exception indicating that <c>hx-action</c> is used with HTMX 1.9.x or 2.x.
     /// </summary>
     /// <exception cref="InvalidOperationException">Always thrown.</exception>
     [DoesNotReturn]
-    private static void Error_AmbiguousMethods()
+    private static void Error_HxActionRequiresHtmx4()
     {
-        const string Message = "Ambiguous HTMX method. Only one of the following methods is allowed: hx-get, hx-post, hx-delete, hx-put, hx-patch";
+        const string Message = "The hx-action attribute is supported only in HTMX 4.x. Use hx-get, hx-post, hx-delete, hx-put, or hx-patch instead.";
         throw new InvalidOperationException(Message);
     }
 }
diff --git a/tests/Ramstack.HtmxToolkit.Tests/TagHelpers/HtmxUrlTagHelperTests.cs b/tests/Ramstack.HtmxToolkit.Tests/TagHelpers/HtmxUrlTagHelperTests.cs
index c3a9ad1..5771711 100644
--- a/tests/Ramstack.HtmxToolkit.Tests/TagHelpers/HtmxUrlTagHelperTests.cs
+++ b/tests/Ramstack.HtmxToolkit.Tests/TagHelpers/HtmxUrlTagHelperTests.cs
@@ -1,3 +1,4 @@
+using Microsoft.AspNetCore.Html;
 using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;
 using Microsoft.AspNetCore.Mvc.Abstractions;
@@ -5,6 +6,9 @@
 using Microsoft.AspNetCore.Mvc.Routing;
 using Microsoft.AspNetCore.Razor.TagHelpers;
 using Microsoft.AspNetCore.Routing;
+using Microsoft.Extensions.Options;
+
+using Ramstack.HtmxToolkit.Configuration;
 
 namespace Ramstack.HtmxToolkit.Tests.TagHelpers;
 
@@ -107,6 +111,11 @@ public async Task ProcessAsync_UsesExistingHtmxMethod()
     [TestCase("hx-delete", "hx-put")]
     [TestCase("hx-delete", "hx-patch")]
     [TestCase("hx-put", "hx-patch")]
+    [TestCase("hx-get", "hx-action")]
+    [TestCase("hx-post", "hx-action")]
+    [TestCase("hx-delete", "hx-action")]
+    [TestCase("hx-put", "hx-action")]
+    [TestCase("hx-patch", "hx-action")]
     public void ProcessAsync_MultipleMethods_Throws(string method1, string method2)
     {
         var attributes = new TagHelperAttributeList
@@ -115,10 +124,66 @@ public void ProcessAsync_MultipleMethods_Throws(string method1, string method2)
             new TagHelperAttribute(method2)
         };
 
+        Assert.ThrowsAsync<InvalidOperationException>(
+            async () => await RunAsync(attributes: attributes, version: HtmxTargetVersion.V4));
+    }
+
+    [Test]
+    public void ProcessAsync_EmptyMethodValue_Throws()
+    {
+        var attributes = new TagHelperAttributeList
+        {
+            new TagHelperAttribute("hx-post", new HtmlString(""))
+        };
+
         Assert.ThrowsAsync<InvalidOperationException>(
             async () => await RunAsync(attributes: attributes));
     }
 
+    [Test]
+    public void ProcessAsync_MethodWithUrl_Throws()
+    {
+        var attributes = new TagHelperAttributeList
+        {
+            new TagHelperAttribute("hx-post", new HtmlString("/explicit"))
+        };
+
+        var exception = Assert.ThrowsAsync<InvalidOperationException>(
+            async () => await RunAsync(attributes: attributes));
+
+        Assert.That(exception!.Message, Does.Contain("hx-post"));
+    }
+
+    [Test]
+    public async Task ProcessAsync_HxAction_WritesUrl_ForHtmx4()
+    {
+        var attributes = new TagHelperAttributeList
+        {
+            new TagHelperAttribute("hx-action"),
+            new TagHelperAttribute("hx-method", new HtmlString("post"))
+        };
+
+        var (_, output) = await RunAsync(attributes: attributes, version: HtmxTargetVersion.V4);
+
+        Assert.That(output.Attributes["hx-action"]!.Value, Is.EqualTo(TestUrlHelper.ActionUrl));
+        Assert.That(output.Attributes["hx-get"], Is.Null);
+    }
+
+    [TestCase(HtmxTargetVersion.V1)]
+    [TestCase(HtmxTargetVersion.V2)]
+    public void ProcessAsync_HxAction_Throws_BeforeHtmx4(HtmxTargetVersion version)
+    {
+        var attributes = new TagHelperAttributeList
+        {
+            new TagHelperAttribute("hx-action")
+        };
+
+        var exception = Assert.ThrowsAsync<InvalidOperationException>(
+            async () => await RunAsync(attributes: attributes, version: version));
+
+        Assert.That(exception!.Message, Does.Contain("HTMX 4.x"));
+    }
+
     [TestCase("Route", "Action")]
     [TestCase("Route", "Controller")]
     [TestCase("Route", "Page")]
@@ -149,24 +214,46 @@ static void SetLinkType(HtmxUrlTagHelper tagHelper, string linkType)
         }
     }
 
-    private static async Task<(TestUrlHelper UrlHelper, TagHelperOutput Output)> RunAsync(Action<HtmxUrlTagHelper>? configure = null, TagHelperAttributeList? attributes = null)
+    private static async Task<(TestUrlHelper UrlHelper, TagHelperOutput Output)> RunAsync(Action<HtmxUrlTagHelper>? configure = null, TagHelperAttributeList? attributes = null, HtmxTargetVersion version = HtmxTargetVersion.V2)
     {
         var urlHelper = new TestUrlHelper();
         var factory = new TestUrlHelperFactory(urlHelper);
 
-        var tagHelper = new HtmxUrlTagHelper(factory)
+        var tagHelper = new HtmxUrlTagHelper(factory, Options.Create(CreateOptions(version)))
         {
             ViewContext = new ViewContext()
         };
 
         configure?.Invoke(tagHelper);
 
-        var output = TestHelper.CreateTagHelperOutput("div", attributes);
+        var output = TestHelper.CreateTagHelperOutput("div", attributes ?? [new TagHelperAttribute("hx-get")]);
         await tagHelper.ProcessAsync(TestHelper.CreateTagHelperContext(), output);
 
         return (urlHelper, output);
     }
 
+    private static HtmxToolkitOptions CreateOptions(HtmxTargetVersion version)
+    {
+        var options = new HtmxToolkitOptions();
+
+        switch (version)
+        {
+            case HtmxTargetVersion.V1:
+                options.UseHtmxV1();
+                break;
+            case HtmxTargetVersion.V2:
+                options.UseHtmxV2();
+                break;
+            case HtmxTargetVersion.V4:
+                options.UseHtmxV4();
+                break;
+            default:
+                throw new ArgumentOutOfRangeException(nameof(version));
+        }
+
+        return options;
+    }
+
 
     private sealed class TestUrlHelperFactory(IUrlHelper helper) : IUrlHelperFactory
     {