# usePlatform

Two hooks and two constants that tell if the user has an Apple platform, for keyboard hints.

```tsx
import { Kbd, useModKey } from 'ferry-ui'

export default function UsePlatformHero() {
  // "⌘" on an Apple device, "Ctrl" on other devices.
  const mod = useModKey()
  return (
    <p className="flex items-center gap-2 text-sm text-foreground-light">
      Open the command menu <Kbd>{mod} K</Kbd>
    </p>
  )
}
```

## Usage

The `use-platform` module has two hooks: `useIsMac()` and `useModKey()`. ferry-ui has no export with the name `usePlatform`.

`useModKey()` returns the label of the main modifier key. The label is `⌘` on an Apple platform (Mac, iPhone, iPad) and `Ctrl` on the other platforms. Show it in a [Kbd](/docs/components/kbd).

```tsx

function SearchHint() {
  const mod = useModKey()
  return <Kbd>{mod} K</Kbd>
}
```

- **The hooks are safe on a server.** A server does not know the platform of the user. On the server and during hydration, `useIsMac()` returns `false` and `useModKey()` returns `Ctrl`. Then React renders again with the real platform.
- **The hooks bind no key.** They only give a value to show. To bind a shortcut, use [useCommandShortcut](/docs/utilities/use-command-shortcut).

## Examples

### One key for each platform

`useIsMac()` returns `true` on an Apple platform. Use it when the two platforms need different keys or different text.

```tsx
import { Kbd, useIsMac } from 'ferry-ui'

export default function UsePlatformIsMac() {
  const isMac = useIsMac()
  return (
    <p className="flex items-center gap-2 text-sm text-foreground-light">
      Delete the selected rows
      {/* The two platforms use different keys for this action. */}
      {isMac ? <Kbd>⌘ ⌫</Kbd> : <Kbd>Del</Kbd>}
    </p>
  )
}
```

### Constants

`isMac` and `modKey` are constants with the same values as the hooks. The module reads the platform one time, when it loads.

Use the constants in code that runs only in the browser, for example an event handler. In markup that a server can render, use the hooks. On a server, the constants describe the platform of the server.

```ts

function onKeyDown(event: KeyboardEvent) {
  const mod = isMac ? event.metaKey : event.ctrlKey
  if (mod && event.key === 's') saveDraft()
}
```

## API reference

The hooks take no argument.

| Name | Type | Value |
| --- | --- | --- |
| `useIsMac()` | `boolean` | `true` on an Apple platform. `false` on the server and during hydration. |
| `useModKey()` | `string` | `'⌘'` on an Apple platform, `'Ctrl'` on the other platforms. `'Ctrl'` on the server and during hydration. |
| `isMac` | `boolean` | `true` on an Apple platform. The module reads it one time. |
| `modKey` | `string` | `'⌘'` if `isMac` is `true`, `'Ctrl'` if not. |