Layers

KeymapKit supports multiple layers in keyboard layouts, allowing you to define different key mappings that can be switched between. This is useful for creating layouts with function layers, number layers, or any other key groupings.

Layer Entry Keys

Layer entry keys are special keys that can switch between different layers. These keys are highlighted in purple to indicate their function and help users understand which keys can be used to access different layers.

To define layer entry keys, use the layerEntryKeys parameter when creating a layer:

KeymapLayer.fromKeyList({
  displayName: "Second Layer",
  shortName: "Second",
  welcome: ["Welcome to the second layer"],
  layerEntryKeys: ["key-id-1"], // These keys will be highlighted in purple
  keys: [
    // ... key definitions
  ],
});

Example: Layer Entry Keys

Here’s an example layout that demonstrates layer entry key functionality:

import { KeyboardModelTitleScreen } from "./title-screen-keyboard.js";
import { KeymapLayout, KeymapKey, KeymapLayer } from "@keymapkit/ui";

const welcome = [
  `Welcome to the Layer Entry Key Test!`,
  `This layout demonstrates layer entry key functionality.`,
  `Click on any key above to see information about it.`,
];

const secondLayerWelcome = [
  `You're now on the second layer!`,
  `This layer was accessed via the layer entry key from the main layer.`,
  `The first key (K) is the key used to enter this layer. It's highlighted in purple to indicate this.`,
  `Click on any key above to see information about it.`,
];

const keyInfo = [
  "Click another key, or click the same key again to close the info and go back to the welcome message.",
];

const layerEntryKeyInfo = [
  "This is a layer entry key. Layer entry keys are highlighted in purple to show their special function.",
  "Click this key to switch to the corresponding layer.",
];

/* A test layout with layer entry keys functionality
 * Features two layers with keys that can switch between them
 */
export const KeymapTitleScreenLayoutLayerTest = new KeymapLayout({
  displayName: "Title Screen Map (Layer Test)",
  uniqueId: "title-screen-map-layertest",
  model: KeyboardModelTitleScreen,
  layers: [
    KeymapLayer.fromKeyList({
      displayName: "Main Layer",
      shortName: "Main",
      welcome: welcome,
      keys: [
        new KeymapKey({ name: "K", id: "title-1-1", info: keyInfo }),
        new KeymapKey({ name: "E", id: "title-3-1", info: keyInfo }),
        new KeymapKey({ name: "Y", id: "title-5-1", info: keyInfo }),
        new KeymapKey({ name: "M", id: "title-7-1", info: keyInfo }),
        new KeymapKey({ name: "A", id: "title-9-1", info: keyInfo }),
        new KeymapKey({ name: "P", id: "title-11-1", info: keyInfo }),
        new KeymapKey({ name: "K", id: "title-13-1", info: keyInfo }),
        new KeymapKey({ name: "I", id: "title-15-1", info: keyInfo }),
        new KeymapKey({ name: "T", id: "title-17-1", info: keyInfo }),
      ],
    }),
    KeymapLayer.fromKeyList({
      displayName: "Second Layer",
      shortName: "Layer2",
      welcome: secondLayerWelcome,
      keys: [
        new KeymapKey({ name: "K", id: "title-1-1", info: layerEntryKeyInfo }),
        new KeymapKey({
          name: "E",
          id: "title-3-1",
          info: keyInfo,
          selection: ["title-1-1", "title-5-1"],
        }),
        new KeymapKey({ name: "Y", id: "title-5-1", info: keyInfo }),
        new KeymapKey({ name: "M", id: "title-7-1", info: keyInfo }),
        new KeymapKey({ name: "A", id: "title-9-1", info: keyInfo }),
        new KeymapKey({ name: "P", id: "title-11-1", info: keyInfo }),
        new KeymapKey({ name: "K", id: "title-13-1", info: keyInfo }),
        new KeymapKey({ name: "I", id: "title-15-1", info: keyInfo }),
        new KeymapKey({ name: "T", id: "title-17-1", info: keyInfo }),
      ],
      layerEntryKeys: ["title-1-1"], // K key (first one) enters this layer
    }),
  ],
  guides: [],
});

Layer Entry Colors Override Others

Note that the layer entry color overrides other colors, including orange key selection groups and green key indicators.