Shortcut Syntax

Starlight Kbd supports a simple syntax for documenting keyboard shortcuts. This guide describes the format supported by the <Kbd> component and recommended practices.

Shortcuts

A basic shortcut consists of one or more modifier keys followed by a regular key, all connected with + signs.

A shortcut with a single modifier key:

<Kbd mac="Command+S" windows="Control+S" />

A shortcut with multiple modifier keys:

<Kbd mac="Command+Shift+S" windows="Control+Shift+S" />

Preview

A shortcut with a single modifier key:

Command + S CommandS Control + S ControlS Control + S ControlS

A shortcut with multiple modifier keys:

Command + Shift + S CommandShiftS Control + Shift + S ControlShiftS Control + Shift + S ControlShiftS

Chords

Some commands require a sequence of keyboard combinations, also known as chords. These are represented by separating each combination with a space.

Press some keys and then press some more keys:

<Kbd mac="Command+K Command+S" windows="Control+K Control+S" />

Preview

Press some keys and then press some more keys:

Command + K then Command + S CommandK CommandS Control + K then Control + S ControlK ControlS Control + K then Control + S ControlK ControlS

Recommendations

When documenting keyboard shortcuts, consider these recommendations:

• Be consistent and use the same key names throughout your documentation. For example, stick to either Control or Ctrl but not both.

• Avoid glyphs and use text for modifier keys. For example, use Command instead of ⌘ which may not be obvious to all users.

  Did you know?

  The Starlight Kbd plugin automatically expands common abbreviations for screen readers, e.g. the ⌘+K S sequence is announced as “Command + K then S”.