Add key headers outside of hover state #157

awkannan · 2025-11-20T01:04:59Z

Right now, ZMK Studio will show a blank key on keys that have any behavior set other than Key Press.

So at a glance, there isn't an easy way to differentiate between truly unbound keys, transparent keys, and keys with other behaviors assigned, such as studio unlock, bluetooth configuration, layer tap, mod tap, etc.

In order to see the behavior name, you have to hover over the key. This isn't ideal for a number of reasons.

This change adds key headers to keys at rest, without hover state.

There is one key challenge though - which is the space. If the header overflows the key, the UI will look like a mess. To handle this, I implemented a very simple heuristic (which should probably be discussed more).

If there are 10 characters or more, we try to split the behavior name into separate words (separated by a space or -) and then shorten each part equally to fit into 9 characters. This should handle most well formed behavior names, which are usually 2-3 words long.

If the human readable name of the behavior is 9 characters or less, we assume it'll fit on the key, and just display it as is.

Here's a few examples of what it looks like:

This meant to be up for discussion, this is just a starting point.

netlify · 2025-11-20T01:05:04Z

✅ Deploy Preview for zmk-studio ready!

Name	Link
🔨 Latest commit	`46acf08`
🔍 Latest deploy log	https://app.netlify.com/projects/zmk-studio/deploys/69274994c634a40008d82d3f
😎 Deploy Preview	https://deploy-preview-157.preview.zmk.studio
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

awkannan · 2025-11-20T01:10:27Z

Note -

I think that maybe we can special-case Key Press or other behaviors that get special treatment.
For example, maybe we hide the headers on Key Press
Or create a list of short name overrides for certain behavior strings, etc.

I think all of these things might improve the experience, but we have to start somewhere.

I don't know what the community will land on, so I'm starting with something simple.

awkannan · 2025-11-20T14:42:30Z

I decided to be a little opinionated - and hid the Key Press header via special case.
This will clean up some of the visual noise.
Key Press seems to be a reasonable "default" behavior, so I think it can be hidden.

I don't think we should implement any other special cases at this point, though.

danielsvane · 2025-11-20T14:52:24Z

I think its an improvement in most cases. The header when hovering should have the same limitation I think, since it will take up the same relative space:

Maybe we could have a list of common shorthands like:

Backspace Shift: bksp shft
Transparent: trans
Bootloader: bootldr

And then fall back to your auto shortening logic if we dont have a common shorthand. Its not like Im in love with this solution, but I cant think of a perfect way to do this. We can also decrease the font size of the header a bit if that will help.

danielsvane · 2025-11-20T15:20:33Z

To add to the list of silly ideas, we can scale down texts that are too long to fit in the container:

I actually think this looks decent enough, but would like some input.

awkannan · 2025-11-20T15:34:06Z

I think ultimately having short names and/or icons in metadata is probably the best solution.

Defining overrides now could mimic the same thing that the ultimate solution would bring - so I would be in favor of implementing overrides now with the eventual plan of relying on metadata instead of an override mapping in the future.

In the meantime - I think I prefer the shortening vs the scaling. I worry with a too long behavior name, the scaling could make the text too small to read, especially on smaller screens. In your example, that looks good imo, but I think it also will limit the legible range of the headers.

On the flip side - some keys do have more space for the normal size text. Not all keys are 1U. The scaling solution would handle this case elegantly. Another option would be to adjust the max length of a shortened header based on key size - but that also adds complexity.

I'm leaning towards defining set overrides for now and using the existing shortening heuristic for anything without an override. We can define overrides for all of the standard ZMK behaviors.

In the future, the metadata can provide the short header we should use, and it'd be up to module developers to provide reasonable short names.

Thoughts?

danielsvane · 2025-11-20T17:23:58Z

I think the lookup table for short names is the easiest to maintain and implement, especially if its only a short term solution. I dont think the short names will be too confusing for users, since they are probably already nerds. Do you have a way of getting all the standard behaviors?

I personally wouldnt mind having keypress be listed as &kp

danielsvane · 2025-11-20T17:32:54Z

src/keyboard/Key.tsx

    >
-      <div className={`absolute text-xs ${selected ? "text-primary-content" : "z1text-base-content"} opacity-0 group-hover:opacity-80 top-1 text-nowrap left-1/2 font-light -translate-x-1/2 text-center transition-opacity`}>{header}</div>
+      <div className={`absolute text-xs ${selected ? "text-primary-content" : "z1text-base-content"} opacity-80 group-hover:opacity-0 top-1 text-nowrap left-1/2 font-light -translate-x-1/2 text-center transition-opacity`}>{shortenHeader(header)}</div>
+      <div className={`absolute text-xs ${selected ? "text-primary-content" : "z1text-base-content"} opacity-0 group-hover:opacity-80 top-1 text-nowrap left-1/2 font-light -translate-x-1/2 text-center transition-opacity`}>{shortenHeader(header)}</div>


One of these has to be redundant right? If we show the same text on the hovered keys, we dont need to fade out the small version, and fade in the big version

Good catch! I fixed this.

awkannan · 2025-11-20T18:24:24Z

I think the lookup table for short names is the easiest to maintain and implement, especially if its only a short term solution. I dont think the short names will be too confusing for users, since they are probably already nerds. Do you have a way of getting all the standard behaviors?

I personally wouldnt mind having keypress be listed as &kp

I implemented the lookup table - plus some boilerplate for potential icons.
I can strip out the icon boilerplate to make this cleaner as well.

I think having short names be as human friendly as possible would be ideal, and I took a stab at defining some short names along those lines. &kp makes sense if you've looked at the keymap files, but if you've only ever used Studio with ZMK / never looked at the code, it might not make as much sense.

For all standard behaviors - I compiled some firmware without removing any behaviors and made short names for those. I'll go through the ZMK docs + code to see what else I need to add. We're missing a bunch (mouse emulation, backlight, soft off, underglow, sensor rotation) that I will try to add.

danielsvane · 2025-11-20T18:43:58Z

Okay good job man, I think the shorthand names you selected are fine. I made an attempt at adding icons for the actual key values here #142. I dont think the solution is perfect, but I think it adds a lot visually using icons

petejohanson

This definitely feels like a step in the right direction, but a few of the abbreviations I'm still on the fence on... How my base layer looks on my Blank Slate w/ the preview:

petejohanson · 2025-11-26T17:49:12Z

src/keyboard/Key.tsx

+  if(typeof header === "undefined"){
+    return "";
+  }
+  const maxHeaderLength = 9;


I personally don't love constants hiding in functions, Can we pull this out so it's easier to find, and maybe capitalize, e.g. MAX_HEADER_LENGTH ?

Good call! Done!

petejohanson · 2025-11-26T17:49:30Z

src/keyboard/Key.tsx

+    return "";
+  }
+  const maxHeaderLength = 9;
+  if(shortNames[header]?.short != null){


Suggested change

if(shortNames[header]?.short != null){

if(shortNames[header]?.short){

Empty string evaluates as falsy in JS - so I wanted to make this a null check, since we use empty string to define the "blank" override for "Key Press"

I get why this came up though, since it's not obvious at first glance, and is really for a special edge case just for Key Press.

Any suggestions as to best way to fix?

Ah, fair. Ignore me then.

Perhaps better to be !== which is a bit more explicit, and should work?

Or at least a comment that this is a null check explicitly so empty strings are allowed as short names.

yep - that should work. I think the != was a relic from when I didn't have an explicit undefined check above

Ok, ignore me. The undefined check above is for the input header.
We need to use != since shortNames[header]?.short can be undefined.

I think a comment is most appropriate here. I got it wrong even though I implemented it initially

EDIT: I made this clearer by disallowing null in the typing. This makes the logic easier to understand, but I left a comment anyways

petejohanson · 2025-11-26T17:50:59Z

src/keyboard/behavior-short-names.json

+    "Grave/Escape": {"short": "Grv/Esc"},
+    "Key Repeat": {"short": "Key Rept"},
+    "Key Toggle": {"short": "Key Togg"},
+    "Momentary Layer": {"short": "MomntLayr"},


Not sure I love this one.... Maybe:

Suggested change

"Momentary Layer": {"short": "MomntLayr"},

"Momentary Layer": {"short": "MLayer"},

petejohanson · 2025-11-26T17:51:16Z

src/keyboard/behavior-short-names.json

+    "Momentary Layer": {"short": "MomntLayr"},
+    "Output Selection": {"short": "OutputSel"},
+    "Sticky Key": {"short": "Stcky Key"},
+    "Studio Unlock": {"short": "StdioUnlk"},


Suggested change

"Studio Unlock": {"short": "StdioUnlk"},

"Studio Unlock": {"short": "Unlock"},

petejohanson · 2025-11-26T18:16:20Z

src/keyboard/behavior-short-names.json

+    "Sticky Key": {"short": "Stcky Key"},
+    "Studio Unlock": {"short": "Unlock"},
+    "Toggle Layer": {"short": "Togg Layr"},
+    "Transparent": {"short": "Trans"}


Sorry, last nit: Since we've got room, maybe this could be:

Suggested change

"Transparent": {"short": "Trans"}

"Transparent": {"short": "Transpnt"}

How about we drop all the vowels?
Trnsprnt
We also have room for
Transprnt
if we go by the 9 character max

petejohanson

LGTM, but can you please squash the commits into one proper feat commit, then we can merge?

Defines short names for behaviors for display on key headers

awkannan · 2025-11-26T18:46:05Z

Should be good to go now!

awkannan force-pushed the 202511_add_header_no_hover branch from 2a4be70 to 02ac8f4 Compare November 20, 2025 01:07

danielsvane reviewed Nov 20, 2025

View reviewed changes

awkannan force-pushed the 202511_add_header_no_hover branch from 59c5e6e to 24279ab Compare November 26, 2025 03:30

petejohanson requested changes Nov 26, 2025

View reviewed changes

petejohanson reviewed Nov 26, 2025

View reviewed changes

awkannan force-pushed the 202511_add_header_no_hover branch from 096e67c to 4f74f40 Compare November 26, 2025 18:39

feat: Add headers to key in resting / non hover state

46acf08

Defines short names for behaviors for display on key headers

awkannan force-pushed the 202511_add_header_no_hover branch from 4f74f40 to 46acf08 Compare November 26, 2025 18:40

petejohanson approved these changes Nov 26, 2025

View reviewed changes

petejohanson merged commit 0f965ed into zmkfirmware:main Nov 26, 2025
4 checks passed

petejohanson mentioned this pull request Nov 20, 2025

chore(main): release 0.4.0 #137

Open

	if(shortNames[header]?.short != null){
	if(shortNames[header]?.short){

	"Momentary Layer": {"short": "MomntLayr"},
	"Momentary Layer": {"short": "MLayer"},

	"Studio Unlock": {"short": "StdioUnlk"},
	"Studio Unlock": {"short": "Unlock"},

	"Transparent": {"short": "Trans"}
	"Transparent": {"short": "Transpnt"}

Uh oh!

Add key headers outside of hover state #157

Add key headers outside of hover state #157

Uh oh!

Conversation

awkannan commented Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify bot commented Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for zmk-studio ready!

Uh oh!

awkannan commented Nov 20, 2025

Uh oh!

awkannan commented Nov 20, 2025

Uh oh!

danielsvane commented Nov 20, 2025

Uh oh!

danielsvane commented Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

awkannan commented Nov 20, 2025

Uh oh!

danielsvane commented Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

awkannan commented Nov 20, 2025

Uh oh!

danielsvane commented Nov 20, 2025

Uh oh!

petejohanson left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

awkannan Nov 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

awkannan Nov 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

petejohanson left a comment

Choose a reason for hiding this comment

Uh oh!

awkannan commented Nov 26, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

awkannan commented Nov 20, 2025 •

edited

Loading

netlify bot commented Nov 20, 2025 •

edited

Loading

danielsvane commented Nov 20, 2025 •

edited

Loading

danielsvane commented Nov 20, 2025 •

edited

Loading

awkannan Nov 26, 2025 •

edited

Loading

awkannan Nov 26, 2025 •

edited

Loading