Introduction

Html.ActionLink in ASP.NET MVC encodes link text by design, so raw HTML in the text argument is rendered as plain text. If you need inner markup such as icons or styled spans, build the anchor tag manually with Url.Action or use TagBuilder. This gives full control while keeping routing correct.

Why ActionLink Escapes HTML

ActionLink is safe by default to reduce XSS risk. It treats link text as content, not markup. That is why passing icon HTML as the text parameter does not render as expected.

@Html.ActionLink("<span class='icon'></span>", "Details", "Orders")

The output contains escaped characters instead of an actual span element. This behavior is intentional.

Correct Approach with Url.Action

Use Url.Action to generate route-safe URLs, then write anchor markup in Razor. This pattern is explicit and easy to audit.

1@{
2    var url = Url.Action("Details", "Orders", new { id = 42 });
3}
4
5<a href="@url" class="btn btn-link" aria-label="View order details">
6    <span class="icon icon-eye"></span>
7</a>

If no visible text is needed, provide an accessible label with aria-label so assistive technology can interpret the link.

Reusable Helper with TagBuilder

For repeated patterns, encapsulate link creation in a helper to avoid duplicated markup and escaping mistakes.

1using System.Web.Mvc;
2
3public static class LinkHelpers
4{
5    public static MvcHtmlString IconLink(this HtmlHelper html, string action, string controller, object routeValues, string css, string ariaLabel)
6    {
7        var url = new UrlHelper(html.ViewContext.RequestContext).Action(action, controller, routeValues);
8        var a = new TagBuilder("a");
9        a.Attributes["href"] = url;
10        a.AddCssClass(css);
11        a.Attributes["aria-label"] = ariaLabel;
12        a.InnerHtml = "<span class='icon icon-eye'></span>";
13        return MvcHtmlString.Create(a.ToString());
14    }
15}

This keeps route generation and accessibility rules centralized.

Security and Accessibility Notes

Only inject trusted HTML into link content. If any part of inner markup comes from user input, sanitize it first or avoid raw HTML altogether. For icon-only links, include screen-reader text or labels so navigation remains understandable.

Also verify keyboard focus styles in your CSS. Icon links are easy to make visually clean but inaccessible if focus indicators are removed.

Testing and Maintenance Strategy

When link markup becomes reusable infrastructure, back it with automated view tests or rendering snapshots. Verify generated href, CSS classes, and accessibility attributes for representative routes. This catches regressions when routing conventions or helper methods evolve.

// Pseudo test intent
// Render view containing IconLink helper
// Assert output contains expected href and aria-label

Also centralize icon naming conventions. If icon class names change across a design refresh, helper-level updates let you migrate once instead of editing dozens of views. Treat link helpers as shared UI APIs with versioned behavior.

If you migrate to newer ASP.NET stacks, keep the same principle: generate URLs with framework routing helpers and keep markup explicit. Framework APIs may differ, but encoded-by-default link helpers still exist for security reasons. A clear policy around safe HTML generation reduces XSS risk and keeps view code consistent during framework upgrades.

Document which helpers are approved for raw HTML and require security review for new helpers that set InnerHtml. This governance approach scales better than ad hoc view-level decisions.

Centralized helper documentation also speeds onboarding for new developers.

It also improves long-term maintainability across view templates.

Common Pitfalls

• Expecting ActionLink to render raw HTML inside link text.
• Building URLs manually instead of using routing helpers.
• Rendering icon-only links without accessible labels.
• Mixing trusted and user-provided HTML in InnerHtml without sanitization.
• Copying inline anchor markup across views and creating maintenance drift.

Summary

• Html.ActionLink encodes text intentionally and will not render inner HTML.
• Use Url.Action plus manual anchor markup for custom link content.
• Centralize repeated patterns with helper methods and TagBuilder.
• Preserve accessibility for icon-only links with labels.
• Keep HTML injection surfaces controlled and sanitized.