Setting Keybinds

Ghostty Config includes a powerful keybinding editor with sequence support, validation, and a visual builder for creating custom keyboard shortcuts.

Accessing Keybinds

Access keybinding settings from the Keybinds category in the navigation sidebar.

For detailed information on Ghostty’s keybinding format and available actions, refer to Ghostty’s keybind documentation.

The Keybind Editor

The keybind editor displays all your keybindings in a list with visual validation:

// From Keybinds.svelte
<div class="item-list">
  {#each value as _, i (i)}
    <div
      class="keybind"
      class:selected={selected.includes(i)}
      class:invalid={diagnostics[i]?.status === "invalid"}
      class:duplicate={diagnostics[i]?.duplicate}
    >
      <Text value={value[i].split("=")[0]} blank={true} align="left" change={update(i)} />
      <Text value={value[i].split("=")[1]} blank={true} change={update(i, true)} />
    </div>
  {/each}
</div>

Visual Indicators

Keybindings are color-coded based on their status:

Normal: Standard display
Selected: Blue highlight when clicked
Duplicate: Orange indicator for duplicate key combinations
Invalid: Red indicator for invalid syntax

.keybind.selected {
  background: #2457c9;
}

.keybind.duplicate {
  box-shadow: inset 4px 0 0 rgba(255, 196, 70, 0.7);
  background: rgba(255, 196, 70, 0.08);
}

.keybind.invalid {
  box-shadow: inset 4px 0 0 rgba(255, 106, 106, 0.8);
  background: rgba(255, 90, 90, 0.12);
}

Keybind Format

Ghostty keybindings follow the format:

keybind = modifier+key=action:argument

Components

Modifiers
Keys
Actions

Available modifiers:

super - Cmd (macOS) or Windows key (Linux/Windows)
ctrl - Control key
alt - Alt/Option key
shift - Shift key

Combine multiple modifiers with +:

super+ctrl+t=new_tab
super+shift+enter=toggle_fullscreen

Common key names:

Letters: a-z
Numbers: 0-9, one-nine (physical keys)
Function: f1-f24
Navigation: arrow_up, arrow_down, page_up, page_down
Special: enter, tab, space, backspace, escape
Symbols: comma, period, bracket_left, equal

Use physical: prefix for physical key positions:

super+physical:one=goto_tab:1

Common actions:

new_tab - Create new tab
close_surface - Close current pane
new_split:right - Split right
goto_tab:N - Switch to tab N
scroll_page_up - Scroll up one page
toggle_fullscreen - Toggle fullscreen
text:\x01 - Send literal text

See Ghostty’s action reference for all actions.

Adding Keybindings

Click the + button

Click the + button in the bottom toolbar to open the keybind editor

Build your keybind

Use the visual builder to construct your keybinding:

Select modifiers (Cmd, Ctrl, Alt, Shift)
Choose a key
Pick an action
Add arguments if needed

Save

Click Save to add the keybinding to your list

// From Keybinds.svelte
function addNew() {
  editorMode = "add";
  editorValue = "";
  showEditor = true;
}

function handleSave(detail: string) {
  if (editorMode === "add") {
    value = [...value, detail];
    
    // Scroll to the new item
    setTimeout(() => {
      if (scroller) scroller.scrollTop = scroller.scrollHeight;
    }, 1);
  }
  showEditor = false;
}

Editing Keybindings

Select a keybind

Click a keybinding in the list to select it

Click edit button

Click the edit button (pencil icon) in the toolbar

Modify in editor

Make your changes in the visual editor

Save changes

Click Save to apply your changes

// From Keybinds.svelte
function editSelected() {
  if (selected.length !== 1) return;
  editorMode = "edit";
  editorValue = value[selected[0]];
  showEditor = true;
}

You can also edit keybindings inline by clicking directly on the key combination or action text.

Removing Keybindings

Select keybind(s)

Click one or more keybindings to select them. Hold Ctrl/Cmd to select multiple.

Click remove button

Click the − button in the toolbar

Keybinds removed

Selected keybindings are removed from the list

// From Keybinds.svelte
function remove() {
  value = value.filter((v, i) => {
    const shouldRemove = selected.includes(i);
    return !shouldRemove;
  });
  selected = [];
}

Multi-Selection

Select multiple keybindings to batch delete:

// From Keybinds.svelte
function select(index: number) {
  return (event: MouseEvent | KeyboardEvent) => {
    if (!event.ctrlKey) return (selected = [index]);
    if (!selected.includes(index)) return selected.push(index);
    selected.splice(selected.indexOf(index), 1);
  };
}

Click: Select single keybinding
Ctrl+Click: Toggle selection (add/remove from selection)
Escape: Clear selection

Keybind Validation

The editor validates keybindings in real-time:

// From Keybinds.svelte
const diagnostics = $derived.by(() => getDiagnostics(value));

Validation Checks

Duplicate detection

The editor warns when multiple keybindings use the same key combination:

// From keybinds.ts (conceptual)
function getDiagnostics(keybinds) {
  const seen = {};
  return keybinds.map(kb => {
    const [key, action] = kb.split("=");
    if (seen[key]) {
      return { duplicate: true };
    }
    seen[key] = true;
    return {};
  });
}

Duplicates show an orange indicator.

Syntax validation

Invalid keybind syntax is flagged with a red indicator.Common issues:

Missing = separator
Invalid modifier names
Unknown key names
Malformed action syntax

Default Keybindings

Ghostty Config includes Ghostty’s default keybindings:

// From settings.ts (excerpt)
{
  id: "keybind", 
  name: "", 
  type: "keybinds", 
  value: [
    "super+t=new_tab",
    "super+w=close_surface",
    "super+enter=toggle_fullscreen",
    "super+d=new_split:right",
    "super+shift+bracket_left=previous_tab",
    "super+shift+bracket_right=next_tab",
    "super+c=copy_to_clipboard",
    "super+v=paste_from_clipboard",
    "super+equal=increase_font_size:1",
    "super+minus=decrease_font_size:1",
    // ... many more
  ]
}

Resetting to Defaults

Click reset button

Click the reset button (circular arrow icon) in the toolbar

Confirm reset

A confirmation dialog appears asking “Are you sure?”

Confirm

Click Reset Keybinds to restore all default keybindings

// From Keybinds.svelte
const defaultKeybinds = (() => {
  const panel = settings.find((entry) => entry.id === "keybinds");
  const group = panel?.groups.find((entry) => entry.id === "keybinds");
  const setting = group?.settings.find((entry) => entry.type === "keybinds");
  return (setting?.value as string[]) ?? [];
})();

function resetDefaults() {
  value = [...defaultKeybinds];
  selected = [];
  showReset = false;
  if (scroller) scroller.scrollTop = 0;
}

Resetting keybindings will overwrite all your custom keybindings. There is no undo.

Common Keybinding Examples

# Create new tab
keybind = super+t=new_tab

# Close current tab/pane
keybind = super+w=close_surface

# Navigate tabs
keybind = super+shift+bracket_left=previous_tab
keybind = super+shift+bracket_right=next_tab

# Go to specific tab
keybind = super+physical:one=goto_tab:1
keybind = super+physical:two=goto_tab:2

# Create splits
keybind = super+d=new_split:right
keybind = super+shift+d=new_split:down

# Navigate splits
keybind = super+alt+arrow_left=goto_split:left
keybind = super+alt+arrow_right=goto_split:right
keybind = super+alt+arrow_up=goto_split:up
keybind = super+alt+arrow_down=goto_split:down

# Resize splits
keybind = super+ctrl+arrow_left=resize_split:left,10
keybind = super+ctrl+arrow_right=resize_split:right,10

# Zoom split
keybind = super+shift+enter=toggle_split_zoom

# Copy and paste
keybind = super+c=copy_to_clipboard
keybind = super+v=paste_from_clipboard

# Select all
keybind = super+a=select_all

# Paste from selection (Linux)
keybind = super+shift+v=paste_from_selection

# Increase/decrease font size
keybind = super+equal=increase_font_size:1
keybind = super+minus=decrease_font_size:1
keybind = super++=increase_font_size:1

# Reset font size
keybind = super+zero=reset_font_size

# Page scrolling
keybind = super+page_up=scroll_page_up
keybind = super+page_down=scroll_page_down

# Jump to prompt
keybind = super+arrow_up=jump_to_prompt:-1
keybind = super+arrow_down=jump_to_prompt:1

# Scroll to top/bottom
keybind = super+home=scroll_to_top
keybind = super+end=scroll_to_bottom

# New window
keybind = super+n=new_window

# Fullscreen
keybind = super+enter=toggle_fullscreen
keybind = super+ctrl+f=toggle_fullscreen

# Quit
keybind = super+q=quit

# Move cursor (macOS-style)
keybind = super+arrow_left=text:\\x01
keybind = super+arrow_right=text:\\x05

# Word navigation
keybind = alt+arrow_left=esc:b
keybind = alt+arrow_right=esc:f

# Delete line
keybind = super+backspace=text:\\x15

Special Key Sequences

Ghostty supports advanced key sequences:

Text Input

Send literal text or control codes:

# Send Ctrl+A (start of line)
keybind = super+arrow_left=text:\x01

# Send Ctrl+E (end of line)
keybind = super+arrow_right=text:\x05

# Send Ctrl+U (delete line)
keybind = super+backspace=text:\x15

Escape Sequences

Send escape sequences:

# Alt+Left (word back)
keybind = alt+arrow_left=esc:b

# Alt+Right (word forward)
keybind = alt+arrow_right=esc:f

Physical Keys

Use physical: prefix for layout-independent bindings:

# Always use physical key positions regardless of layout
keybind = super+physical:one=goto_tab:1
keybind = super+physical:two=goto_tab:2

Physical keys are useful for:

Tab switching (always in same position)
Gaming-style bindings
Consistent bindings across keyboard layouts

Exporting Keybindings

Keybindings are exported with only custom bindings:

// From config.svelte.ts - diff() function
if (Array.isArray(config[key]) && key === "keybind") {
  const toAdd = config[key].filter(c => !defaults[key].includes(c));
  if (toAdd.length) output[keyToConfig(key)] = toAdd;
}

Example exported output:

# Only custom keybindings are exported
keybind = super+shift+t=new_tab
keybind = ctrl+tab=next_tab
keybind = ctrl+shift+tab=previous_tab

Only keybindings that differ from Ghostty’s defaults are exported. This keeps your config file clean and portable across Ghostty updates.

Keyboard Shortcuts in the Editor

Escape

Clear selection when viewing the keybind list

Ctrl+Click

Toggle selection (add/remove from selection)

Click

Select single keybinding

Inline Edit

Click key or action text to edit directly

Best Practices

Avoid conflicts

Be careful not to override important system or application shortcuts. The duplicate indicator helps identify conflicting bindings.

Use consistent modifiers

Stick to a consistent modifier pattern (e.g., always use super for window management) to build muscle memory.

Document complex bindings

Use comments in your exported config to explain non-obvious keybindings.

Test thoroughly

Test new keybindings in Ghostty before committing to them. Some combinations may conflict with shell or application shortcuts.

Start minimal

Begin with a few essential custom bindings rather than customizing everything at once.

Troubleshooting

Keybind not working
Invalid syntax error
Duplicate warning

If a keybinding isn’t working:

Check for duplicate bindings in the list
Verify the syntax is valid (no red indicator)
Ensure the key name is correct
Test if the key combination conflicts with OS shortcuts
Check Ghostty’s logs for errors

Common syntax issues:

Missing = between key and action
Typo in modifier name (use super, not cmd)
Incorrect key name (use arrow_up, not up)
Missing action argument (e.g., goto_tab:1)

Overview

User Guide

Features

Development

Reference

Accessing Keybinds

The Keybind Editor

Visual Indicators

Keybind Format

Components

Adding Keybindings

Editing Keybindings

Removing Keybindings

Multi-Selection

Keybind Validation

Validation Checks

Default Keybindings

Resetting to Defaults

Common Keybinding Examples

Special Key Sequences

Text Input

Escape Sequences

Physical Keys

Exporting Keybindings

Keyboard Shortcuts in the Editor

Escape

Ctrl+Click

Click

Inline Edit

Best Practices

Troubleshooting

Build docs developers (and LLMs) love

Overview

User Guide

Features

Development

Reference

​Accessing Keybinds

​The Keybind Editor

​Visual Indicators

​Keybind Format

​Components

​Adding Keybindings

​Editing Keybindings

​Removing Keybindings

​Multi-Selection

​Keybind Validation

​Validation Checks

​Default Keybindings

​Resetting to Defaults

​Common Keybinding Examples

​Special Key Sequences

​Text Input

​Escape Sequences

​Physical Keys

​Exporting Keybindings

​Keyboard Shortcuts in the Editor

Escape

Ctrl+Click

Click

Inline Edit

​Best Practices

​Troubleshooting

Build docs developers (and LLMs) love

Accessing Keybinds

The Keybind Editor

Visual Indicators

Keybind Format

Components

Adding Keybindings

Editing Keybindings

Removing Keybindings

Multi-Selection

Keybind Validation

Validation Checks

Default Keybindings

Resetting to Defaults

Common Keybinding Examples

Special Key Sequences

Text Input

Escape Sequences

Physical Keys

Exporting Keybindings

Keyboard Shortcuts in the Editor

Best Practices

Troubleshooting