Feature request: allow per-option descriptions in snippet choice placeholders (`${1|...|}`)

Open
#322,678 0 comments 1 reaction 1 assignee View on GitHub

@alexdima is already working on this.

Since Jun 24, 2026.

Assessment

This issue has not been assessed yet.

Description

Feature request: allow per-option descriptions in snippet choice placeholders (${1|...|})

Summary

When a snippet uses a choice placeholder (${1|a,b,c|}), the dropdown shows only the raw option values. There is no way to attach an explanatory description/label to each option. I would like each choice option to be able to carry a short description that is rendered at the end of the line, the same way a snippet's own description is shown in the IntelliSense suggestion widget when you start typing the snippet.

Current behavior

A choice option is plain text only. The grammar defines it as:

choice ::= '${' int '|' text (',' text)* '|}'

So when the choice dropdown opens, the user just sees the bare values with nothing to explain what each one means.

Example snippet:

"Admonition": {
  "prefix": "adm",
  "body": [
    "${1|!!!,???,???+|} ${2|note,tip,warning,danger|}",
    "    $0"
  ],
  "description": "Admonition block"
}

When the snippet itself is suggested, IntelliSense already shows a description at the end of the line ("Admonition"):

Image

But when the choice placeholder dropdown opens, the options !!!, ???, ???+ have no description at all - the user cannot tell what each marker does:

Image

Desired behavior

Allow each choice option to declare a description that the dropdown renders at the end of the line, mirroring the snippet-suggestion widget. For the example above the dropdown could read:

!!!     static (always shown)
???     collapsible, starts closed
???+    collapsible, starts open

This is purely additive: existing snippets without descriptions keep working unchanged.

Possible syntax

  • Inline separator per option, e.g. ${1|!!!:static (always shown),???:collapsible closed,???+:collapsible open|} (would require choosing a separator that does not clash with values).
  • A richer object form in the snippet JSON for choices, mapping each value to a description.

Why

Choice placeholders are often cryptic markers (here: Material/MkDocs admonition markers !!! / ??? / ???+). Descriptions would let snippet authors document each option in place, exactly like the description already shown for the snippet as a whole.

Dominant language
TypeScript
Stars
193k
Forks
42.9k
PR metrics pending

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from microsoft/vscode

All issues in microsoft/vscode

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.