---
title: "Resolve accessible names and descriptions in C#"
url: https://recursiveai.org/onehtml/cookbook/resolve-accessible-names-and-descriptions/
description: "Resolve accessible names and descriptions from local HTML in C#. See which ARIA reference, native label or title supplied the computed text."
version: "1.6.0"
---

# Resolve accessible names and descriptions in C#

**onehtml** is a free, open-source HTML library for .NET from Recursive AI. MIT or Apache-2.0, no native dependencies.

[NuGet](https://www.nuget.org/packages/RecursiveAI.OneHtml.Accessibility) · [GitHub](https://github.com/recursive-ai-oss/onehtml-csharp) · [Docs](https://recursiveai.org/onehtml/docs/) · [Download example (.zip)](https://recursiveai.org/onehtml/cookbook/resolve-accessible-names-and-descriptions/resolve-accessible-names-and-descriptions.zip)

Read a control’s name and help text from static HTML, without running page scripts.

```shell
dotnet add package RecursiveAI.OneHtml.Accessibility
```

Requires [.NET 10](https://dotnet.microsoft.com/download/dotnet/10.0) (net10.0); .NET 9 and earlier aren’t supported.

```csharp
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](https://recursiveai.org/onehtml/cookbook/resolve-accessible-names-and-descriptions/resolve-accessible-names-and-descriptions.zip), then `dotnet run`.

Prints the button’s accessible name, then its description.

```text
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.

```csharp
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:

```text
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`.

```csharp
// 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>
    """);
```

```text
Export
Saves a CSV
```

## Related recipes

- [Build an accessibility tree](https://recursiveai.org/onehtml/cookbook/accessibility-tree/)
- [Inspect keyboard tab order](https://recursiveai.org/onehtml/cookbook/inspect-accessibility-focus-order/)

---

## 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`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) points to the text that identifies a control. [`aria-describedby`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/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](https://www.w3.org/WAI/ARIA/apg/practices/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](https://recursiveai.org/onehtml/docs/accessibility-tree/#accessible-name-and-description) give the full order. The example uses `title` to show that fallback, not as a substitute for a visible form label.
