Simple Layout

To set up a new layout for an existing keyboard, you need to create a new KeymapLayout. Here’s a very simple example of a Planck layout that only populates a few keys.

import { KeymapLayout, KeymapKey, KeymapLayer } from "@keymapkit/ui";
import { KeyboardModelPlanck48 } from "@keymapkit/keyboard.planck48";

export const Planck48ExampleLayout = new KeymapLayout({
  // The display name for the keymap; sometimes shown to users
  displayName: "Planck 48 Example",

  // The ID must be unique in a given `keymap-ui` element
  uniqueId: "planck48-example-layout",

  // The model must be an existing keyboard model
  model: KeyboardModelPlanck48,

  // Layers is a list of KeymapLayer objects
  // The first layer in the list is shown first
  layers: [
    // Define just a single layer
    KeymapLayer.fromKeyList({
      // A display name for the layer; sometimes shown to users
      displayName: "Planck 48 Main Layer",

      // A short name, used in buttons for switching between layers
      shortName: "Main",

      // The welcome page for the layer. When loading the layer, show this by default.
      welcome: [
        `Hello, and welcome to the example Planck keymap!`,
        `This welcome message is shown when the keymap loads.`,
      ],

      // A list of keys
      // Each key has a name, ID, and info,
      // which in this case is all set to the same thing
      keys: [
        new KeymapKey({ name: "K", id: "planck-1-1", info: ["1st K key"] }),
        new KeymapKey({ name: "E", id: "planck-3-1", info: ["The E key"] }),
        new KeymapKey({ name: "Y", id: "planck-5-1", info: ["The Y key"] }),
        new KeymapKey({ name: "M", id: "planck-7-1", info: ["The M key"] }),
        new KeymapKey({ name: "A", id: "planck-9-1", info: ["The A key"] }),
        new KeymapKey({ name: "P", id: "planck-11-1", info: ["The P key"] }),
        new KeymapKey({ name: "K", id: "planck-13-1", info: ["The K key"] }),
        new KeymapKey({ name: "I", id: "planck-15-1", info: ["1st I key"] }),
        new KeymapKey({ name: "T", id: "planck-17-1", info: ["The T key"] }),
      ],
    }),
  ],
  guides: [],
});

You can then use it on a web page like this:

<div id="example-container"></div>

<script type="module">
  import { Planck48ExampleLayout } from "/KeymapKit/keymaps/planck48-example-layout.js";
  const container = document.getElementById("example-container");
  const keymapUi = document.createElement("keymap-ui");
  keymapUi.setModelsAndMaps([Planck48ExampleLayout]);
  container.appendChild(keymapUi);
</script>

Which looks like this:

Key IDs

How do you know what a keyboard uses for its key IDs?

Each keyboard has one or more keygrids, and any number of keys. The keys each have an identifier based on the keygrid name and their stating location in the grid. The Planck has only one keygrid, called planck, and all of the key IDs are planck-X-Y. All of the keys are listed in each board’s source definition, for instance, the Planck file has:

const KeyboardModelPlanck48 = new KeyboardModel(
  "keymap-keyboard-planck48",
  "Planck 48",
  new Point(2, 2),
  new Size(4, 3),
  [
    // Top row
    new PhysicalKey("planck", new Point(1, 1), new Size(2, 2)),
    new PhysicalKey("planck", new Point(3, 1), new Size(2, 2)),
    new PhysicalKey("planck", new Point(5, 1), new Size(2, 2)),
    new PhysicalKey("planck", new Point(7, 1), new Size(2, 2)),
    // ...etc
  ],
);

This corresponds to IDs: