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

> Master the Astryx Kbd component to display cross-platform keyboard shortcuts with stylized kbd elements. Learn how to integrate platform-adaptive shortcut displays using StyleX.

- Repository: [Meta/astryx](https://github.com/facebook/astryx)
- Tags: how-to-guide
- Published: 2026-07-14

---

**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`](https://github.com/facebook/astryx/blob/main/packages/core/src/Kbd/index.ts):

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

```tsx
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`](https://github.com/facebook/astryx/blob/main/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`:

```tsx
<Kbd keys="shift+plus" />

```

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

## Complex Combinations

Chain multiple modifiers using the `+` separator:

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

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

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

```

Or:

```tsx
<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`](https://github.com/facebook/astryx/blob/main/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`](https://github.com/facebook/astryx/blob/main/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.