usePlatform

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.

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

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.

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.

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.

import { isMac } from 'ferry-ui'

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

API reference#

The hooks take no argument.