# Kbd

Keycap untuk shortcut keyboard memakai elemen kbd native, dua ukuran, dengan kombinasi tombol dirender sebagai keycap terpisah.

- Kategori: Data
- Status: stable
- Registry: https://markas.jenderalcorp.com/r/kbd.json
- CLI: `npx markasui@latest add kbd`

## Kapan dipakai

Menampilkan shortcut keyboard di teks bantuan, menu, tooltip, tombol, atau daftar shortcut.

- Pakai keys untuk kombinasi, jangan menulis "+" manual
- Tulis nama tombol seperti tertera di keyboard, misalnya Ctrl, Shift, Enter, dan Esc
- Jangan membuat keycap bisa diklik; pakai Button untuk aksi

## Kode

### Blade

Simpan di `resources/views/components/markas/kbd.blade.php`. Tanpa dependensi tambahan.

```blade
@props([
    'size' => 'md',
    'keys' => [],
    'separator' => '+',
])

@php
    $keycap = 'inline-flex items-center justify-center rounded-md bg-surface font-sans font-medium text-muted ring-1 ring-line';
    $sizes = [
        'sm' => 'h-5 min-w-5 px-1 text-[11px]',
        'md' => 'h-6 min-w-6 px-1.5 text-xs',
    ];
    $group = 'inline-flex items-center gap-1 font-sans';
    $joiner = 'text-xs text-muted';
@endphp

@if (count($keys) > 0)
    <kbd {{ $attributes->class([$group]) }}>@foreach ($keys as $key)@if (! $loop->first)<span class="{{ $joiner }}">{{ $separator }}</span>@endif<kbd class="{{ $keycap }} {{ $sizes[$size] }}">{{ $key }}</kbd>@endforeach</kbd>
@else
    <kbd {{ $attributes->class([$keycap, $sizes[$size]]) }}>{{ $slot }}</kbd>
@endif
```

```blade
<x-markas.kbd>Esc</x-markas.kbd>
<x-markas.kbd :keys="['Ctrl', 'K']" />
<x-markas.kbd size="sm" :keys="['G', 'N']" separator="lalu" />
```

### React

Simpan di `src/components/markas/Kbd.tsx`. Tanpa dependensi tambahan.

```tsx
import { Fragment, type ComponentProps } from "react";

const keycap =
  "inline-flex items-center justify-center rounded-md bg-surface font-sans font-medium text-muted ring-1 ring-line";
const sizes = {
  sm: "h-5 min-w-5 px-1 text-[11px]",
  md: "h-6 min-w-6 px-1.5 text-xs",
};
const group = "inline-flex items-center gap-1 font-sans";
const joiner = "text-xs text-muted";
const cx = (...c: (string | false | null | undefined)[]) =>
  c.filter(Boolean).join(" ");

export type KbdProps = ComponentProps<"kbd"> & {
  size?: keyof typeof sizes;
  /** Kombinasi tombol, dirender sebagai keycap terpisah. Menggantikan children. */
  keys?: string[];
  /** Teks di antara tombol pada kombinasi. */
  separator?: string;
};

export function Kbd({
  size = "md",
  keys = [],
  separator = "+",
  className,
  children,
  ...props
}: KbdProps) {
  if (keys.length === 0)
    return (
      <kbd className={cx(keycap, sizes[size], className)} {...props}>
        {children}
      </kbd>
    );

  return (
    <kbd className={cx(group, className)} {...props}>
      {keys.map((key, index) => (
        <Fragment key={index}>
          {index > 0 && <span className={joiner}>{separator}</span>}
          <kbd className={cx(keycap, sizes[size])}>{key}</kbd>
        </Fragment>
      ))}
    </kbd>
  );
}
```

```tsx
import { Kbd } from "@/components/markas/Kbd";

<Kbd>Esc</Kbd>
<Kbd keys={["Ctrl", "K"]} />
<Kbd size="sm" keys={["G", "N"]} separator="lalu" />
```

### Vue

Simpan di `src/components/markas/Kbd.vue`. Tanpa dependensi tambahan.

```vue
<script setup lang="ts">
const props = withDefaults(
  defineProps<{
    size?: "sm" | "md";
    keys?: string[];
    separator?: string;
  }>(),
  { size: "md", keys: () => [], separator: "+" },
);

const keycap =
  "inline-flex items-center justify-center rounded-md bg-surface font-sans font-medium text-muted ring-1 ring-line";
const sizes = {
  sm: "h-5 min-w-5 px-1 text-[11px]",
  md: "h-6 min-w-6 px-1.5 text-xs",
};
const group = "inline-flex items-center gap-1 font-sans";
const joiner = "text-xs text-muted";
</script>

<template>
  <kbd v-if="props.keys.length > 0" :class="group"
    ><template v-for="(key, index) in props.keys" :key="index"
      ><span v-if="index > 0" :class="joiner">{{ props.separator }}</span
      ><kbd :class="[keycap, sizes[props.size]]">{{ key }}</kbd></template
    ></kbd
  >
  <kbd v-else :class="[keycap, sizes[props.size]]"><slot /></kbd>
</template>
```

```vue
<template>
  <Kbd>Esc</Kbd>
  <Kbd :keys="['Ctrl', 'K']" />
  <Kbd size="sm" :keys="['G', 'N']" separator="lalu" />
</template>
```

### Svelte

Simpan di `src/lib/components/markas/Kbd.svelte`. Tanpa dependensi tambahan.

```svelte
<script lang="ts">
  import type { Snippet } from "svelte";
  import type { HTMLAttributes } from "svelte/elements";

  const keycap =
    "inline-flex items-center justify-center rounded-md bg-surface font-sans font-medium text-muted ring-1 ring-line";
  const sizes = {
    sm: "h-5 min-w-5 px-1 text-[11px]",
    md: "h-6 min-w-6 px-1.5 text-xs",
  };
  const group = "inline-flex items-center gap-1 font-sans";
  const joiner = "text-xs text-muted";

  type Props = HTMLAttributes<HTMLElement> & {
    size?: keyof typeof sizes;
    /** Key combination, rendered as separate keycaps. Replaces children. */
    keys?: string[];
    /** Text between keys in a combination. */
    separator?: string;
    children?: Snippet;
  };

  let {
    size = "md",
    keys = [],
    separator = "+",
    class: className,
    children,
    ...rest
  }: Props = $props();
</script>

{#if keys.length === 0}
  <kbd class={[keycap, sizes[size], className]} {...rest}
    >{@render children?.()}</kbd
  >
{:else}
  <kbd class={[group, className]} {...rest}
    >{#each keys as key, index (index)}{#if index > 0}<span class={joiner}
          >{separator}</span
        >{/if}<kbd class={[keycap, sizes[size]]}>{key}</kbd>{/each}</kbd
  >
{/if}
```

```svelte
<script lang="ts">
  import Kbd from "$lib/components/markas/Kbd.svelte";
</script>

<Kbd>Esc</Kbd>
<Kbd keys={["Ctrl", "K"]} />
<Kbd size="sm" keys={["G", "N"]} separator="then" />
```

### Astro

Simpan di `src/components/markas/Kbd.astro`. Tanpa dependensi tambahan.

```astro
---
import type { HTMLAttributes } from "astro/types";

const keycap =
  "inline-flex items-center justify-center rounded-md bg-surface font-sans font-medium text-muted ring-1 ring-line";
const sizes = {
  sm: "h-5 min-w-5 px-1 text-[11px]",
  md: "h-6 min-w-6 px-1.5 text-xs",
};
const group = "inline-flex items-center gap-1 font-sans";
const joiner = "text-xs text-muted";

type Props = HTMLAttributes<"kbd"> & {
  size?: keyof typeof sizes;
  /** Key combination, rendered as separate keycaps. Replaces the slot. */
  keys?: string[];
  /** Text between keys in a combination. */
  separator?: string;
};

const { size = "md", keys = [], separator = "+", class: className, ...rest } =
  Astro.props;
---

{
  keys.length === 0 ? (
    <kbd class:list={[keycap, sizes[size], className]} {...rest}><slot /></kbd>
  ) : (
    <kbd class:list={[group, className]} {...rest}>
      {keys.map((key, index) => (
        <Fragment>
          {index > 0 && <span class={joiner}>{separator}</span>}
          <kbd class:list={[keycap, sizes[size]]}>{key}</kbd>
        </Fragment>
      ))}
    </kbd>
  )
}
```

```astro
---
import Kbd from "@/components/markas/Kbd.astro";
---

<Kbd>Esc</Kbd>
<Kbd keys={["Ctrl", "K"]} />
<Kbd size="sm" keys={["G", "N"]} separator="then" />
```

### Angular

Simpan di `src/app/markas/kbd.component.ts`. Tanpa dependensi tambahan.

```ts
import {
  ChangeDetectionStrategy,
  Component,
  computed,
  input,
} from "@angular/core";

const keycap =
  "inline-flex items-center justify-center rounded-md bg-surface font-sans font-medium text-muted ring-1 ring-line";
const sizes = {
  sm: "h-5 min-w-5 px-1 text-[11px]",
  md: "h-6 min-w-6 px-1.5 text-xs",
};
const group = "inline-flex items-center gap-1 font-sans";
const joiner = "text-xs text-muted";

export type KbdSize = keyof typeof sizes;

/**
 * Attribute selector on the native kbd: aria-*, title, and the user's class stay on it.
 * With `keys` the host becomes the group and every key is a nested kbd.
 */
@Component({
  selector: "kbd[markas-kbd]",
  changeDetection: ChangeDetectionStrategy.OnPush,
  host: { "[class]": "classes()" },
  template: `@if (keys().length === 0) {
      <ng-content />
    } @else {
      @for (key of keys(); track $index) {
        @if ($index > 0) {
          <span [class]="joiner">{{ separator() }}</span>
        }
        <kbd [class]="keyClass()">{{ key }}</kbd>
      }
    }`,
})
export class Kbd {
  readonly size = input<KbdSize>("md");
  /** Key combination, rendered as separate keycaps. Replaces the content. */
  readonly keys = input<string[]>([]);
  /** Text between keys in a combination. */
  readonly separator = input("+");

  protected readonly joiner = joiner;
  protected readonly keyClass = computed(
    () => `${keycap} ${sizes[this.size()]}`,
  );
  protected readonly classes = computed(() =>
    this.keys().length === 0 ? this.keyClass() : group,
  );
}
```

```ts
import { Component } from "@angular/core";
import { Kbd } from "./markas/kbd.component";

@Component({
  selector: "app-example",
  imports: [Kbd],
  template: `
    <kbd markas-kbd>Esc</kbd>
    <kbd markas-kbd [keys]="['Ctrl', 'K']"></kbd>
    <kbd markas-kbd size="sm" [keys]="['G', 'N']" separator="then"></kbd>
  `,
})
export class Example {}
```

Angular memakai attribute selector pada `kbd` native, jadi `class` dan `aria-hidden` tetap di elemen itu.

## Props

| Nama | Tipe | Default | Keterangan |
| --- | --- | --- | --- |
| `size` | `'sm' \| 'md'` | md | Tinggi keycap dan ukuran teks. Pakai sm di dalam tombol dan input. |
| `keys` | `string[]` | [] | Kombinasi tombol. Setiap tombol dirender sebagai keycap sendiri di dalam kbd luar. Menggantikan slot atau children. |
| `separator` | `string` | + | Teks muted di antara tombol pada kombinasi, misalnya "lalu" untuk urutan tombol. |
| `children / slot` | `ReactNode / slot / snippet` | - | Isi satu keycap bila keys kosong. |

## Aksesibilitas

- Memakai elemen kbd native; kombinasi menyusun satu kbd per tombol di dalam kbd luar, sesuai anjuran spesifikasi HTML.
- Pemisah berupa teks biasa sehingga pembaca layar membacakan kombinasi seperti "Ctrl + K".
- Pasang aria-hidden pada keycap bila shortcut hanya petunjuk visual di dalam kontrol yang sudah punya nama.

## Catatan

- Tanpa JavaScript. Versi Blade tidak butuh Alpine.js.
- `keys` merender `<kbd><kbd>Ctrl</kbd><span>+</span><kbd>K</kbd></kbd>`. Tanpa `keys`, slot atau children mengisi satu keycap.
- Di dalam tombol yang sudah punya nama, tambahkan `aria-hidden="true"` agar shortcut tidak dibaca dua kali.
- Pemisah default "+". Ganti lewat `separator`, misalnya "lalu" untuk urutan tombol dalam Bahasa Indonesia.
