BreadCrumb skin object to render semantic, accessible breadcrumb markup #6898

uzmannazari · 2026-01-08T07:24:35Z

Summary

This PR refactors the BreadCrumb skin object to render semantic, list-based markup using <nav>, <ol>, and <li> elements instead of inline spans and separators.

The updated output improves accessibility and aligns breadcrumb rendering with common WCAG and ARIA breadcrumb patterns, while preserving existing behavior and customization options.

Fixes #6609

Details

Updated the BreadCrumb ASCX to wrap the generated breadcrumb items inside a semantic navigation container (<nav aria-label="Breadcrumb">) and an ordered list (<ol itemscope itemtype="https://schema.org/BreadcrumbList">).
Replaced the Label with a Literal to avoid injecting wrapper markup inside the list container (ensuring valid list structure).
Refactored backend rendering to output one <li> per breadcrumb item with Schema.org BreadcrumbList / ListItem microdata and position meta.
Applied aria-current="page" to the <li> representing the current page (instead of the <a>), matching common ARIA breadcrumb patterns.
Rendered separators inside each breadcrumb <li> (only when another crumb follows) and marked them decorative via aria-hidden="true", avoiding extra list items while preserving the existing Separator customization and path resolution.
Added default styling in type.scss for nav.dnnBreadcrumb ol to prevent list items stacking vertically after switching to list markup, and to ensure the ordered list does not display numeric markers while keeping the visual breadcrumb layout consistent:
- list-style: none; (prevents numbering/markers)
- display: flex; align-items: center; gap: 0.5rem; (keeps crumbs inline and spaced)
- nav.dnnBreadcrumb ol li span { margin-inline-start: 0.5rem; display: inline-block; } (consistent spacing for the separator/content)

Impact

Improves accessibility and semantic correctness of breadcrumb markup.
Preserves existing breadcrumb features and configuration (RootLevel, UseTitle, HideWithNoBreadCrumb, DisableLink, Profile/Group URL parameters, Separator customization).
Visual output remains consistent with previous behavior via the added default styling.

Testing

Verified breadcrumb output for multi-level navigation paths renders inline (not stacked) and without ordered-list numbering.
Tested root breadcrumb rendering and HideWithNoBreadCrumb behavior.
Tested pages with disabled breadcrumb links.
Confirmed structured data output remains valid for BreadcrumbList.

Replaced asp:label with nav and ol structure for better semantic markup.

mitchelsellers

One note/request included on a change to localization.

Additionally however I do believe this would be a substantially breaking change to introduce, so the planning of how this would be released is something we have to take into consideration. @dnnsoftware/approvers anyone else with thoughts on this?

mitchelsellers · 2026-01-08T14:15:53Z

DNN Platform/Website/admin/Skins/breadcrumb.ascx

@@ -1,2 +1,6 @@
 <%@ Control Language="C#" AutoEventWireup="false" Inherits="DotNetNuke.UI.Skins.Controls.BreadCrumb" Codebehind="BreadCrumb.ascx.cs" %>
-<asp:label id="lblBreadCrumb" runat="server" EnableViewState="False" itemprop="breadcrumb" itemscope itemtype="https://schema.org/breadcrumb"/>
+<nav class="dnnBreadcrumb" aria-label="Breadcrumb">


Given that this is a literal name used for human interaction (via screen readers) I believe this should be pulling from localization

Good call — agreed. I’ve switched the aria-label value to come from the control’s resx (e.g. BreadCrumbAriaLabel.Text) with a sensible fallback to "Breadcrumb" if the resource is missing. This keeps screen-reader text properly localized.

bdukes

I like adding this markup as an option, however I don't think we can change the markup by default, I think it needs to be opt-in (e.g. add a new property for display mode or DisplayAsList or something).

bdukes · 2026-01-08T14:25:27Z

DNN Platform/Website/admin/Skins/BreadCrumb.ascx.cs

                    var changed = false;

-                    if (url.StartsWith("/", StringComparison.Ordinal))
+                    if (url.StartsWith("/"))


We want to keep the StringComparison

Fixed — restored StartsWith(..., StringComparison.Ordinal) (and kept StringComparison usage throughout) to avoid culture-sensitive comparisons.

DNN Platform/Website/admin/Skins/BreadCrumb.ascx.cs

bdukes · 2026-01-08T14:28:11Z

DNN Platform/Website/admin/Skins/BreadCrumb.ascx.cs

-                this.breadcrumb.Append(this.separator);
-            }
+                breadcrumb.Append("<li itemprop=\"itemListElement\" itemscope itemtype=\"https://schema.org/ListItem\">");
+                breadcrumb.Append("<a href=\"" + this.homeUrl + "\" class=\"" + this.cssClass + "\" itemprop=\"item\"><span itemprop=\"name\">" + this.homeTabName + "</span></a>");


Either use a formattable string or AppendFormat.

Also, the tab name will need to be HTML encoded

Updated — replaced string concatenations with AppendFormat/formattable strings and HTML-encoded tab names (HttpUtility.HtmlEncode) before rendering to prevent malformed markup and ensure safe output.

DNN Platform/Website/admin/Skins/BreadCrumb.ascx.cs

Removed nav and ol tags from breadcrumb control.

Updated the BreadCrumb class to enhance functionality and maintain compatibility with legacy systems. Introduced new properties for cleaner markup and list-based semantic rendering.

uzmannazari · 2026-01-08T15:47:59Z

One note/request included on a change to localization.

Additionally however I do believe this would be a substantially breaking change to introduce, so the planning of how this would be released is something we have to take into consideration. @dnnsoftware/approvers anyone else with thoughts on this?

Totally agree on the breaking-change risk. I’ve updated the implementation so the new semantic/list markup is opt-in via a new property (UseListMarkup, default false).
When UseListMarkup="false" the output stays in the legacy format (to preserve existing skins/CSS), and only when true it renders the <nav>/<ol>/<li> semantic structure.

uzmannazari · 2026-01-08T15:49:28Z

I like adding this markup as an option, however I don't think we can change the markup by default, I think it needs to be opt-in (e.g. add a new property for display mode or DisplayAsList or something).

Agreed — I changed this to opt-in. Added UseListMarkup (default false) so legacy markup remains the default behavior. Setting UseListMarkup="true" enables the semantic list-based breadcrumb output.

uzmannazari · 2026-01-08T16:11:52Z

@bdukes and @mitchelsellers Thanks for the feedback!

I’ve updated the PR to minimize breaking changes and address review notes:

Added UseListMarkup (default false) so legacy output remains the default, and semantic markup is opt-in.

Kept legacy wrapper <span itemprop="breadcrumb" ...> when UseListMarkup=false to preserve existing skin/CSS behavior.

Switched the control output to Literal to avoid invalid nesting; list-mode now starts with<nav>directly.

Localized the aria-label via resx with fallback.

Restored StringComparison.Ordinal, kept doc comments, and ensured tab names are HTML-encoded with AppendFormat usage.

valadas · 2026-01-08T18:10:26Z

DNN Platform/Dnn.ClientSide/src/styles/default-css/10.0.0/base/_type.scss

+nav.dnnBreadcrumb ol {
+    list-style: none;
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+}
+
+nav.dnnBreadcrumb ol li span {
+    margin-inline-start: 0.5rem;
+    display: inline-block;
+}


I am not a big fan of adding this css here, could we create a "skinobjects" folder similar to the "modules" folder and put in there one file per skinobject maybe?

DNN Platform/Website/admin/Skins/BreadCrumb.ascx.cs

mitchelsellers

Sorry upon further review one small changes suggested.

mitchelsellers · 2026-01-13T18:40:42Z

DNN Platform/Website/admin/Skins/BreadCrumb.ascx.cs

+            // This mimics the old asp:Label output wrapper and keeps schema breadcrumb attrs.
+            var breadcrumb = new StringBuilder(
+                "<span itemprop=\"breadcrumb\" itemscope itemtype=\"https://schema.org/breadcrumb\">" +
+                "<span itemscope itemtype=\"http://schema.org/BreadcrumbList\">");


This should really be broken out into either one initialization & one Append call or just one big string to avoid the concatenated string being allocated.

uzmannazari added 3 commits January 8, 2026 10:48

Refactor breadcrumb control for semantic HTML

a30da9c

Replaced asp:label with nav and ol structure for better semantic markup.

Refactor BreadCrumb class for improved readability

27f4faa

Refactor base styles in _type.scss for default breadcrumb styles

0f75c20

uzmannazari changed the title ~~Patch 6~~ BreadCrumb skin object to render semantic, accessible breadcrumb markup Jan 8, 2026

mitchelsellers requested changes Jan 8, 2026

View reviewed changes

bdukes reviewed Jan 8, 2026

View reviewed changes

uzmannazari added 3 commits January 8, 2026 19:11

Refactor breadcrumb control structure

bd754b8

Removed nav and ol tags from breadcrumb control.

Refactor BreadCrumb class for improved functionality

0a90355

Updated the BreadCrumb class to enhance functionality and maintain compatibility with legacy systems. Introduced new properties for cleaner markup and list-based semantic rendering.

added localized resource file for breadcrumb on markup mode

c289878

uzmannazari requested review from bdukes and mitchelsellers January 8, 2026 15:51

valadas reviewed Jan 8, 2026

View reviewed changes

bdukes approved these changes Jan 12, 2026

View reviewed changes

DNN Platform/Website/admin/Skins/BreadCrumb.ascx.cs Show resolved Hide resolved

Add doc comment back

8fcb9d0

mitchelsellers approved these changes Jan 13, 2026

View reviewed changes

mitchelsellers requested changes Jan 13, 2026

View reviewed changes

Uh oh!

BreadCrumb skin object to render semantic, accessible breadcrumb markup #6898

Are you sure you want to change the base?

BreadCrumb skin object to render semantic, accessible breadcrumb markup #6898

Conversation

uzmannazari commented Jan 8, 2026

Summary

Details

Impact

Testing

Uh oh!

mitchelsellers left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bdukes left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

uzmannazari commented Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

uzmannazari commented Jan 8, 2026

Uh oh!

uzmannazari commented Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mitchelsellers left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

uzmannazari commented Jan 8, 2026 •

edited

Loading

uzmannazari commented Jan 8, 2026 •

edited

Loading