TanStack · fredericbahr · Mar 17, 2026 · Mar 9, 2026
diff --git a/examples/lit/held-keys/index.html b/examples/lit/held-keys/index.html
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>held-keys - TanStack Hotkey Lit example</title>
+    <script type="module" src="/src/app.ts"></script>
+  </head>
+  <body>
+    <my-app></my-app>
+  </body>
+</html>
diff --git a/examples/lit/held-keys/package.json b/examples/lit/held-keys/package.json
@@ -0,0 +1,21 @@
+{
+  "name": "@tanstack/hotkeys-example-lit-held-keys",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite --port=3069",
+    "build": "vite build",
+    "preview": "vite preview",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test:types": "tsc"
+  },
+  "dependencies": {
+    "@tanstack/lit-hotkeys": "0.4.1",
+    "lit": "^3.3.2"
+  },
+  "devDependencies": {
+    "typescript": "~5.9.3",
+    "vite": "^7.3.1"
+  }
+}
diff --git a/examples/lit/held-keys/src/app.ts b/examples/lit/held-keys/src/app.ts
@@ -0,0 +1,152 @@
+import { LitElement, css, html, unsafeCSS } from 'lit'
+import { customElement, state } from 'lit/decorators.js'
+
+import {
+  HeldKeyCodesController,
+  HeldKeysController,
+  formatKeyForDebuggingDisplay,
+} from '@tanstack/lit-hotkeys'
+
+import appStyles from './index.css?raw'
+
+@customElement('my-app')
+export class MyApp extends LitElement {
+  static styles = [
+    css`
+      :host {
+        display: block;
+        margin: 0;
+        font-family:
+          system-ui,
+          -apple-system,
+          sans-serif;
+        background: #f5f5f5;
+        color: #333;
+        box-sizing: border-box;
+      }
+      :host *,
+      :host *::before,
+      :host *::after {
+        box-sizing: border-box;
+      }
+    `,
+    unsafeCSS(appStyles),
+  ]
+
+  private heldKeys = new HeldKeysController(this)
+  private heldCodes = new HeldKeyCodesController(this)
+
+  @state() private history: Array<string> = []
+
+  override updated(): void {
+    const keys = this.heldKeys.value
+    if (keys.length > 0) {
+      const combo = keys.map((k) => formatKeyForDebuggingDisplay(k)).join(' + ')
+      const last = this.history[this.history.length - 1]
+      if (last !== combo) {
+        this.history = [...this.history.slice(-9), combo]
+      }
+    }
+  }
+
+  render() {
+    const keys = this.heldKeys.value
+    const codes = this.heldCodes.value
+
+    return html`
+      <div class="app">
+        <header>
+          <h1>HeldKeysController</h1>
+          <p>
+            Returns an array of all currently pressed keys. Useful for
+            displaying key combinations or building custom shortcut recording.
+          </p>
+        </header>
+
+        <main>
+          <section class="demo-section">
+            <h2>Currently Held Keys</h2>
+            <div class="key-display">
+              ${keys.length > 0
+                ? keys.map((key, index) => {
+                    const code = codes[key]
+                    return html`
+                      ${index > 0 ? html`<span class="plus">+</span>` : null}
+                      <kbd class="large">
+                        ${formatKeyForDebuggingDisplay(key)}
+                        ${code && code !== key
+                          ? html`<small class="code-label">
+                              ${formatKeyForDebuggingDisplay(code, {
+                                source: 'code',
+                              })}
+                            </small>`
+                          : null}
+                      </kbd>
+                    `
+                  })
+                : html`<span class="placeholder">Press any keys...</span>`}
+            </div>
+            <div class="stats">Keys held: <strong>${keys.length}</strong></div>
+          </section>
+
+          <section class="demo-section">
+            <h2>Usage</h2>
+            <pre class="code-block">
+${`import { HeldKeysController } from '@tanstack/lit-hotkeys'
+
+class KeyDisplay extends LitElement {
+  private heldKeys = new HeldKeysController(this)
+
+  render() {
+    return html\`
+      <div>
+        Currently pressed: \${this.heldKeys.value.join(' + ') || 'None'}
+      </div>
+    \`
+  }
+}`}</pre
+            >
+          </section>
+
+          <section class="demo-section">
+            <h2>Try These Combinations</h2>
+            <ul>
+              <li>Hold <kbd>Shift</kbd> + <kbd>Control</kbd> + <kbd>A</kbd></li>
+              <li>Press multiple letter keys at once</li>
+              <li>Hold modifiers and watch them appear</li>
+              <li>Release keys one by one</li>
+            </ul>
+          </section>
+
+          <section class="demo-section">
+            <h2>Recent Combinations</h2>
+            ${this.history.length > 0
+              ? html`
+                  <ul class="history-list">
+                    ${this.history.map((combo) => html`<li>${combo}</li>`)}
+                  </ul>
+                `
+              : html`<p class="placeholder">Press some key combinations...</p>`}
+            <button @click=${() => (this.history = [])}>Clear History</button>
+          </section>
+
+          <section class="demo-section">
+            <h2>Use Cases</h2>
+            <ul>
+              <li>Building a keyboard shortcut recorder</li>
+              <li>Displaying currently held keys to users</li>
+              <li>Debugging keyboard input</li>
+              <li>Creating key combination tutorials</li>
+            </ul>
+          </section>
+        </main>
+      </div>
+    `
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'my-app': MyApp
+  }
+}
diff --git a/examples/lit/held-keys/src/index.css b/examples/lit/held-keys/src/index.css
@@ -0,0 +1,131 @@
+* {
+  box-sizing: border-box;
+}
+body {
+  margin: 0;
+  font-family:
+    system-ui,
+    -apple-system,
+    sans-serif;
+  background: #f5f5f5;
+  color: #333;
+}
+.app {
+  max-width: 800px;
+  margin: 0 auto;
+  padding: 20px;
+}
+header {
+  text-align: center;
+  margin-bottom: 40px;
+}
+header h1 {
+  margin: 0 0 10px;
+  color: #0066cc;
+}
+header p {
+  color: #666;
+  margin: 0;
+  max-width: 500px;
+  margin: 0 auto;
+}
+.demo-section {
+  background: white;
+  border-radius: 12px;
+  padding: 24px;
+  margin-bottom: 24px;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.08);
+}
+.demo-section h2 {
+  margin: 0 0 16px;
+  font-size: 20px;
+}
+.demo-section ul {
+  margin: 0;
+  padding-left: 20px;
+}
+.demo-section li {
+  margin-bottom: 8px;
+}
+kbd {
+  background: linear-gradient(180deg, #f8f8f8 0%, #e8e8e8 100%);
+  border: 1px solid #ccc;
+  border-bottom-width: 2px;
+  border-radius: 4px;
+  padding: 2px 8px;
+  font-family: monospace;
+  font-size: 13px;
+}
+kbd.large {
+  font-size: 24px;
+  padding: 8px 16px;
+  display: inline-flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 2px;
+}
+kbd.large .code-label {
+  display: block;
+  font-size: 11px;
+  color: #888;
+  font-weight: normal;
+}
+.key-display {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 12px;
+  min-height: 80px;
+  flex-wrap: wrap;
+  background: #f8f9fa;
+  border-radius: 8px;
+  padding: 20px;
+}
+.key-display .plus {
+  font-size: 24px;
+  color: #666;
+}
+.placeholder {
+  color: #999;
+  font-style: italic;
+}
+.stats {
+  text-align: center;
+  margin-top: 16px;
+  font-size: 16px;
+  color: #666;
+}
+.code-block {
+  background: #1e1e1e;
+  color: #d4d4d4;
+  padding: 16px;
+  border-radius: 8px;
+  overflow-x: auto;
+  font-size: 13px;
+  line-height: 1.5;
+}
+.history-list {
+  list-style: none;
+  padding: 0;
+  margin: 0 0 16px;
+}
+.history-list li {
+  padding: 8px 12px;
+  background: #f0f0f0;
+  border-radius: 4px;
+  margin-bottom: 4px;
+  font-family: monospace;
+  font-size: 14px;
+}
+button {
+  background: #0066cc;
+  color: white;
+  border: none;
+  padding: 10px 20px;
+  border-radius: 6px;
+  cursor: pointer;
+  font-size: 14px;
+}
+button:hover {
+  background: #0052a3;
+}
diff --git a/examples/lit/held-keys/tsconfig.json b/examples/lit/held-keys/tsconfig.json
@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "experimentalDecorators": true,
+    "useDefineForClassFields": false,
+    "module": "ESNext",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "types": ["vite/client"],
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  },
+  "include": ["src"]
+}
diff --git a/examples/lit/hotkey-sequence/.gitignore b/examples/lit/hotkey-sequence/.gitignore
@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
diff --git a/examples/lit/hotkey-sequence/index.html b/examples/lit/hotkey-sequence/index.html
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>hotkey-sequence - TanStack Hotkey Lit example</title>
+    <script type="module" src="/src/app.ts"></script>
+  </head>
+  <body>
+    <my-app></my-app>
+  </body>
+</html>