How to Use the Kbd Component for Keyboard Shortcut Display in Astryx

The Kbd component in Astryx renders keyboard shortcuts as stylized <kbd> elements that automatically adapt to the user's platform (macOS vs Windows/Linux) using StyleX for styling and useSyncExternalStore for SSR-safe platform detection.

The Kbd component is part of the core package in the facebook/astryx repository, designed to display keyboard shortcuts with platform-specific glyphs. It handles the complexity of rendering ⌘ on macOS versus "Ctrl" on Windows/Linux while ensuring accessibility and server-side rendering compatibility.

Installation and Import

The Kbd component is exported from the core package. Import it from the public API entry point as defined in packages/core/src/Kbd/index.ts:

import {Kbd} from '@astryxdesign/core';

Basic Usage with the Keys Prop

The component requires a keys prop containing a string that describes the keyboard shortcut. Use the + delimiter to separate multiple keys:

export function SaveShortcut() {
  return (
    <div>
      Press <Kbd keys="mod+s" /> to save your changes.
    </div>
  );
}

This renders as ⌘ S on macOS and Ctrl S on Windows and Linux.

Platform Detection and the Mod Key

In packages/core/src/Kbd/Kbd.tsx, the detectMac() function determines the user's platform by checking the browser's User-Agent Client Hints or falling back to navigator.platform. The special mod key automatically maps to ⌘ (Command) on macOS and Ctrl elsewhere.

The detection logic is wrapped with useSyncExternalStore to prevent hydration mismatches between server and client renders.

Supported Key Mappings

The KEY_DISPLAY mapping in the source code translates logical key names to visual glyphs. Common mappings include:

• ctrl → Control glyph
• shift → ⇧
• enter → ↵
• mod → Platform-specific modifier

For literal plus signs in shortcuts, use the word plus:

<Kbd keys="shift+plus" />

This displays ⇧ + instead of interpreting the second + as a delimiter.

Complex Combinations

Chain multiple modifiers using the + separator:

<Kbd keys="mod+shift+enter" />

This renders three distinct key badges: ⌘ + ⇧ + ↵ (or Ctrl + Shift + Enter on non-Mac platforms).

Customization with StyleX

The Kbd component uses StyleX (@stylexjs/stylex) for styling, referencing tokens from packages/core/src/theme/tokens.stylex. Apply custom layout styles using the xstyle prop:

import stylex from '@stylexjs/stylex';

const customStyle = stylex.create({
  wrapper: {
    margin: '8px',
  },
});

<Kbd keys="mod+k" xstyle={customStyle.wrapper} />

The component applies the default class name astryx-kbd that can be targeted by theming tokens defined in Kbd.doc.mjs.

Fallback Styling Options

While xstyle is preferred, you can use standard className or style props for integration with non-StyleX code:

<Kbd keys="mod+p" className="my-custom-kbd" />

Or:

<Kbd keys="mod+p" style={{backgroundColor: 'gold'}} />

These approaches bypass StyleX optimizations and are generally discouraged for new applications.

Accessibility Features

The component implements robust accessibility support via KEY_LABEL mappings that provide spoken-word equivalents for screen readers. In packages/core/src/Kbd/Kbd.tsx, the component constructs an aria-label by joining key labels with "plus" (e.g., "Command plus S").

The visual <kbd> elements are marked aria-hidden="true" because their decorative glyphs are not meaningful to assistive technology. This ensures screen readers announce the shortcut using standard terminology rather than reading individual symbols.

SSR Safety and Hydration

To prevent hydration mismatches, the component provides a subscribeToPlatformChanges function and getServerPlatformSnapshot for server-side rendering. These ensure identical markup is generated on the server and client, eliminating flicker during hydration.

The server-side snapshot defaults to a safe state that gets reconciled on the client once the actual platform is detected.

Summary

• The Kbd component in packages/core/src/Kbd/Kbd.tsx renders platform-aware keyboard shortcuts using StyleX for consistent styling.
• Use the keys prop with + delimiters to define shortcuts; the special mod token automatically becomes ⌘ on macOS and Ctrl elsewhere.
• Access Kbd from @astryxdesign/core and customize layouts via the xstyle prop while maintaining theme consistency.
• The component handles accessibility through aria-label construction and hides visual glyphs from screen readers.
• SSR-safe platform detection uses useSyncExternalStore with subscribeToPlatformChanges to prevent hydration mismatches.

Frequently Asked Questions

What is the difference between mod and ctrl in the Kbd component?

The mod key is platform-aware: it renders as ⌘ (Command) on macOS and "Ctrl" on Windows and Linux. The ctrl key always renders as the Control glyph regardless of platform. Use mod for shortcuts that follow platform conventions, such as "mod+s" for save.

How does Astryx handle server-side rendering with the Kbd component?

The component uses useSyncExternalStore with getServerPlatformSnapshot to provide a default server-side state. This ensures the HTML generated on the server matches the initial client render, preventing hydration mismatches. Once hydrated, the client detects the actual platform and updates the display if necessary.

Can I use the Kbd component without StyleX?

While the component is built with StyleX, you can pass standard className or style props for customization. However, this bypasses StyleX's performance optimizations and theme token integration. For best results, import stylex from @stylexjs/stylex and use the xstyle prop.

How do I display a literal plus sign in a keyboard shortcut?

Use the word plus instead of the + symbol. For example, keys="shift+plus" renders as Shift + Plus. If you used keys="shift++", the parser would incorrectly interpret the consecutive plus signs as delimiters.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}