Options

Configure Glide with glide.o (global) and glide.bo (buffer-local) options

Glide provides two ways to set options: glide.o for global options and glide.bo for buffer-specific options.

glide.o

Set browser-wide options that persist across all tabs.

glide.o.hint_size = "14px";
glide.o.native_tabs = "hide";
glide.o.mapping_timeout = 500;

glide.bo

Set buffer-specific options that only apply to the current tab. These options are reset when navigating to a new page.

glide.bo.hint_size = "20px";  // Only affects current buffer
glide.bo.native_tabs = "show"; // Only affects current buffer

Implementation:

export function make_buffer_options(): typeof glide["bo"] {
  const bo = {} as typeof glide["bo"];

  for (const name of GLIDE_O_SETTERS) {
    let value = undefined as any;
    Object.defineProperty(bo, name, {
      get() {
        return value;
      },
      set(v) {
        value = v;
        options[name]?.(v, true);
      },
    });
  }

  return bo;
}

glide.options.get()

Retrieve the effective option value, checking buffer-specific options first, then falling back to global options.

glide.options.get<Name extends keyof glide.Options>(name: Name): glide.Options[Name]

Example:

glide.o.hint_size = "11px";
glide.bo.hint_size = "16px";

const size = glide.options.get('hint_size');
console.log(size); // "16px" (buffer-specific value takes precedence)

Implementation:

options: {
  get<Name extends keyof glide.Options>(name: Name): glide.Options[Name] {
    const option = GlideBrowser.api.bo[name];
    if (is_present(option)) {
      return option!;
    }

    return GlideBrowser.api.o[name];
  },
}

---

Available Options

mapping_timeout

mapping_timeout · number · default: "200"

How long to wait (in milliseconds) until cancelling a partial keymapping execution.

For example, with glide.keymaps.set('insert', 'jj', 'mode_change normal'), after pressing j once, this option determines how long the delay should be until the j key is considered fully pressed and the mapping sequence is reset.

Note: This only applies in insert mode.

glide.o.mapping_timeout = 500;

---

switch_mode_on_focus

switch_mode_on_focus · boolean · default: "true"

Determines if the current mode will change when certain element types are focused.

For example, if true, Glide will automatically switch to insert mode when an editable element is focused.

This can be useful for staying in the same mode while switching tabs.

glide.o.switch_mode_on_focus = false;

---

yank_highlight

yank_highlight · string · default: "#edc73b"

Color used to briefly highlight text when it’s yanked. Accepts any valid CSS color value.

glide.o.yank_highlight = "#ff6b35";        // Orange
glide.o.yank_highlight = "rgb(255, 0, 0)"; // Red

---

yank_highlight_time

yank_highlight_time · number · default: "150"

How long (in milliseconds) to highlight the selection when it’s yanked.

glide.o.yank_highlight_time = 300;

---

jumplist_max_entries

jumplist_max_entries · number · default: "100"

The maximum number of entries to include in the jumplist, i.e., how far back in history the jumplist will store.

glide.o.jumplist_max_entries = 200;

---

which_key_delay

which_key_delay · number · default: "300"

The delay (in milliseconds) before showing the which-key UI.

glide.o.which_key_delay = 500;

---

hint_chars

hint_chars · string · default: "hjklasdfgyuiopqwertnmzxcvb"

The characters to include in hint labels.

glide.o.hint_chars = "asdfghjkl";

---

hint_size

hint_size · string · default: "11px"

The font size of hint labels. Directly corresponds to the CSS font-size property.

glide.o.hint_size = "14px";

Implementation:

#hint_size = "11px";
get hint_size() {
  return this.#hint_size;
}
set hint_size(value: string) {
  this.#hint_size = value;
  options.hint_size(value, false);
}

---

hint_label_generator

hint_label_generator · function

A function to produce labels for hints. Can use built-in generators:

• glide.hints.label_generators.prefix_free (default)
• glide.hints.label_generators.numeric

glide.o.hint_label_generator = glide.hints.label_generators.numeric;

// Or create custom generator
glide.o.hint_label_generator = ({ hints }) => {
  return hints.map((_, i) => String(i + 1));
};

---

native_tabs

native_tabs · 'show' | 'hide' | 'autohide' · default: "show"

Configure the behavior of the native tab bar:

• show - Always visible
• hide - Always hidden
• autohide - Shows when cursor hovers over its default position

Works for both horizontal and vertical tabs.

Warning: autohide does not work on macOS at the moment.

glide.o.native_tabs = "hide";

// For vertical tabs, adjust collapsed width:
glide.o.native_tabs = "autohide";
glide.styles.add(css`
  :root {
    --uc-tab-collapsed-width: 2px;
  }
`);

Implementation:

#native_tabs: (typeof glide)["o"]["native_tabs"] = "show";
get native_tabs() {
  return this.#native_tabs;
}
set native_tabs(value: (typeof glide)["o"]["native_tabs"]) {
  this.#native_tabs = value;
  options.native_tabs(value, false);
}

---

newtab_url

newtab_url · string · default: "about:newtab"

The URL to load when a new tab is created. May be a local file (file:///path/to/page.html) or any other URL.

glide.o.newtab_url = "https://example.com";
glide.o.newtab_url = "file:///path/to/startpage.html";

Implementation:

#newtab_url = "about:newtab";
get newtab_url() {
  return this.#newtab_url;
}
set newtab_url(value: string) {
  this.#newtab_url = value;
  options.newtab_url(value, false);
}

---

go_next_patterns

go_next_patterns · string[]

Element text patterns to search for in the :go_next excmd.

glide.o.go_next_patterns = ["next", "forward", ">"];

---

go_previous_patterns

go_previous_patterns · string[]

Element text patterns to search for in the :go_previous excmd.

glide.o.go_previous_patterns = ["prev", "back", "<"];

---

keyboard_layout

keyboard_layout · string · default: "qwerty"

The keyboard layout to use when keymaps_use_physical_layout is set to "force".

The only layout supported by default is "qwerty". See keyboard_layouts for how to add custom layouts.

glide.o.keyboard_layout = "qwerty";

---

keyboard_layouts

keyboard_layouts · object

The supported keyboard layouts. Each entry maps a key code to the string (and shifted string) used in Glide keymappings.

// Add a custom layout
declare global {
  interface GlideKeyboardLayouts {
    dvorak: GlideKeyboardLayout;
  }
}

glide.o.keyboard_layouts.dvorak = {
  Minus: ["[", "{"],
  // ... more key mappings
};
glide.o.keyboard_layout = "dvorak";

---

keymaps_use_physical_layout

keymaps_use_physical_layout · 'never' | 'for_macos_option_modifier' | 'force' · default: "for_macos_option_modifier"

Determines whether keymappings resolve from the key event code (physical key) or key (OS-resolved string).

• "never" - Always use event.key
• "force" - Always use event.code
• "for_macos_option_modifier" - Use event.code on macOS when Option is held, event.key otherwise

Setting to "force" is recommended for users with multiple or non-English keyboard layouts.

glide.o.keymaps_use_physical_layout = "force";

---

scroll_implementation

scroll_implementation · 'keys' | 'legacy' · default: "keys"

Configure the strategy for implementing scrolling. This affects the h, j, k, l, <C-u>, <C-d>, G, and gg mappings.

Note: This will be removed in the future when the kinks with the keys implementation are ironed out.

glide.o.scroll_implementation = "legacy";

---

Custom Options

You can define custom options by declaration merging:

declare global {
  interface GlideOptions {
    my_custom_option?: boolean;
    my_timeout?: number;
  }
}

glide.o.my_custom_option = true;
glide.o.my_timeout = 1000;