Read a control’s name and help text from static HTML, without running page scripts.
dotnet add package RecursiveAI.OneHtml.AccessibilityRequires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.
using RecursiveAI.OneHtml; using RecursiveAI.OneHtml.Accessibility; using RecursiveAI.OneHtml.Css; var doc = Document.Parse(""" <span id="label">Export</span> <span id="hint">Saves a CSV</span> <button aria-labelledby="label" aria-describedby="hint">Go</button> """); var tree = AccessibilityTree.Build(doc, DocumentStyles.Create(doc)); var el = doc.Root.QuerySelector("button"); var name = tree.ComputeName(el); var desc = tree.ComputeDescription(el); Console.WriteLine(name.Value); Console.WriteLine(desc.Value);
Unzip the example, then dotnet run.
Prints the button’s accessible name, then its description.
Export Saves a CSV
The full program
The download prints the text and its source for three controls. The export button uses two label references, the email field uses a native label, and the reference field falls back to title. A broken label reference that produces no text falls through to the next naming source.
using RecursiveAI.OneHtml; using RecursiveAI.OneHtml.Accessibility; using RecursiveAI.OneHtml.Css; var doc = Document.Parse(""" <span id="action" aria-labelledby="alias">Export</span> <span id="alias">Download</span> <span id="format">CSV</span> <p id="hint">Saves the filtered rows.</p> <button id="export" aria-labelledby="action format" aria-label="Export data" aria-describedby="hint" title="Export options">Go</button> <label for="email">Email address</label> <input id="email" title="For receipts only"> <input id="reference" title="Order reference"> """); var styles = DocumentStyles.Create(doc); var tree = AccessibilityTree.Build(doc, styles); foreach (var id in new[] { "export", "email", "reference" }) { var element = doc.Root.QuerySelector("#" + id); var name = tree.ComputeName(element); var description = tree.ComputeDescription(element); Console.WriteLine($"{id}: name='{name.Value}' ({name.Source})"); Console.WriteLine($" description='{description.Value}' ({description.Source})"); }
dotnet run prints:
export: name='Export CSV' (LabelledBy) description='Saves the filtered rows.' (DescribedBy) email: name='Email address' (NativeLabelElement) description='For receipts only' (Title) reference: name='Order reference' (Title) description='' (None)
Variations
Check fallback after a missing ID
Replace the markup in the snippet at the top. With no element named missing, the button gets its name from aria-label and its description from aria-description.
// Replace the short snippet's HTML with: var doc = Document.Parse(""" <button aria-labelledby="missing" aria-label="Export" aria-description="Saves a CSV">Go</button> """);
Export Saves a CSV
Related recipes
The short answer
Parse the HTML, create DocumentStyles, and build an AccessibilityTree from that same document: computed styles help determine what’s hidden, which can change the name. Call ComputeName and ComputeDescription on the control. Each result has a Value and a Source: check both to tell whether the expected text came from the expected attribute or only matched by coincidence. You can also read Name and Description on a node already in the tree.
What’s the difference between aria-labelledby and aria-describedby?
Both take space-separated IDs. aria-labelledby points to the text that identifies a control. aria-describedby points to extra information about how to use it or what it does. In the download, action format supplies “Export CSV”, and hint separately supplies “Saves the filtered rows.” The description doesn’t extend or replace the name.
The library joins label references in attribute order, skipping duplicates. It doesn’t follow a second aria-labelledby while reading an existing label reference. The download shows the difference: action has its own reference to alias, but the button reads “Export” from action, not “Download” from alias. To include several pieces of text, reference them directly on the control.
When should I use aria-label or aria-labelledby?
Use aria-labelledby to reuse text that’s already in the document. Use aria-label for a short name when there’s no suitable text to reference, such as for a button that shows only an icon. For a form field with a visible label, use a native <label> where possible: it associates the name with the field and also lets a user click the label to interact with it. The WAI guide to names and descriptions explains the tradeoffs.
When aria-labelledby produces text, it takes precedence over aria-label. In the download, the button is named “Export CSV”, not “Export data” or its visible text “Go”. If the IDs don’t produce text, the calculation can fall through, as the variation demonstrates. If you expected a reference to win and got AriaLabel or a native source instead, check the IDs and the text they point to.
When does title supply the name or description?
For the input with a native label, title supplies the description because neither aria-describedby nor aria-description supplies one. The unlabeled reference field uses title as a fallback name instead, so the description is empty. The same title doesn’t fill both slots. The library’s name and description rules give the full order. The example uses title to show that fallback, not as a substitute for a visible form label.