glide.hints

API for displaying hint overlays and hint-based navigation

Overview

The hints system displays overlays on clickable elements, allowing keyboard-based navigation and interaction. Hints can be shown for both content elements (links, buttons) and browser UI elements.

Methods

show()

Find and show hints for clickable elements.

glide.hints.show(opts?: HintShowOptions): void

opts · object

Options for configuring hint generation and behavior

Show properties

selector · string

Only show hints for elements matching this CSS selector. When specified, only elements matching this selector will be hinted.

glide.hints.show({ selector: "a, button" });
glide.hints.show({ selector: "[data-clickable]" });

include · string

Also show hints for elements matching this CSS selector, in addition to the default hintable elements.

glide.hints.show({ include: ".custom-button, [role='menuitem']" });

editable · boolean

Only show hints for editable elements (inputs, textareas, contenteditable).

glide.hints.show({ editable: true });

include_click_listeners · boolean · default: "false"

Include elements that have a click listener registered.

This is experimental and may have performance implications

auto_activate · boolean | 'always' · default: "false"

Automatically activate hints without user interaction.

• false - Always require user selection
• true - Activate automatically if exactly one hint is found
• "always" - Always activate the first hint immediately

// Auto-activate single results
glide.hints.show({ 
  selector: "input[type='search']",
  auto_activate: true 
});

action · HintAction

Action to perform when a hint is selected. Can be a built-in action string or a custom callback.

Built-in actions:

• "click" - Click the element (default)
• "newtab-click" - Open link in a new tab

Custom action:

glide.hints.show({
  async action({ hint, content }) {
    const text = await content.execute((el) => el.textContent);
    console.log('Clicked element with text:', text);
  }
});

location · 'content' | 'browser-ui' · default: "'content'"

Where to generate hints:

• "content" - Show hints for elements in the web page
• "browser-ui" - Show hints for browser interface elements (toolbar, tabs, menus)

// Hint browser UI elements
glide.hints.show({ location: "browser-ui" });

label_generator · HintLabelGenerator

Function to generate labels for hints. Use built-in generators or provide a custom function.

// Use numeric labels
glide.hints.show({
  label_generator: glide.hints.label_generators.numeric
});

// Custom generator based on element text
glide.hints.show({
  async label_generator({ hints, content }) {
    const texts = await content.map((el) => el.textContent);
    return texts.map(text => text.slice(0, 2).toUpperCase());
  }
});

pick · HintPicker

Filter the resolved hints before displaying them.

glide.hints.show({
  async pick({ hints, content }) {
    // Only show hints for visible images
    const areas = await content.map((el) => 
      el.offsetWidth * el.offsetHeight
    );
    return hints.filter((_, i) => areas[i] > 100);
  }
});

Examples

// Basic usage - hint all clickable elements
glide.hints.show();

// Hint only links
glide.hints.show({ selector: "a" });

// Hint editable fields with auto-focus
glide.hints.show({ 
  editable: true,
  auto_activate: true,
  action({ content }) {
    content.execute((el) => el.focus());
  }
});

// Copy link URLs to clipboard
glide.hints.show({
  selector: "a[href]",
  async action({ content }) {
    const href = await content.execute((el) => el.href);
    navigator.clipboard.writeText(href);
  }
});

// Hint browser tabs
glide.hints.show({ 
  location: "browser-ui",
  include: "tab" 
});

Label Generators

label_generators.prefix_free

Generates prefix-free hint labels using characters from glide.o.hint_chars. This ensures you never need to press more keys than necessary.

glide.hints.show({
  label_generator: glide.hints.label_generators.prefix_free
});

label_generators.numeric

Generates sequential numeric labels starting at 1.

glide.hints.show({
  label_generator: glide.hints.label_generators.numeric
});

Types

HintAction

type HintAction = 
  | "click"
  | "newtab-click"
  | ((props: HintActionProps) => Promise<void> | void);

interface HintActionProps {
  hint: Hint;
  content: {
    execute<R>(cb: (target: HTMLElement) => R): Promise<R>;
  };
}

HintLabelGenerator

type HintLabelGenerator = (ctx: HintLabelGeneratorProps) => string[] | Promise<string[]>;

interface HintLabelGeneratorProps {
  hints: Hint[];
  content: {
    map<R>(
      cb: (target: HTMLElement, index: number) => R
    ): Promise<R[]>;
  };
}

HintPicker

type HintPicker = (props: HintPickerProps) => Hint[] | Promise<Hint[]>;

interface HintPickerProps {
  hints: Hint[];
  content: {
    map<R>(
      cb: (target: HTMLElement, index: number) => R
    ): Promise<R[]>;
  };
}

Hint

interface Hint {
  id: number;
  x: number;
  y: number;
  width: number;
  height: number;
  label?: string;
}

Configuration

Hint behavior can be configured globally via glide.o:

// Change hint label characters
glide.o.hint_chars = "asdfjkl;";

// Change hint label size
glide.o.hint_size = "14px";

// Set default label generator
glide.o.hint_label_generator = glide.hints.label_generators.numeric;

Hintable Elements

By default, hints are shown for:

• Links (<a>)
• Buttons (<button>)
• Input fields (<input>, <textarea>)
• Interactive elements (<details>, <summary>, <label>)
• Elements with click listeners (when include_click_listeners is enabled)
• Elements with specific ARIA roles (button, link, tab, etc.)
• Elements matching the include selector
• Editable elements (when editable is true)

See Also

• glide.o.hint_chars - Configure hint label characters
• glide.o.hint_size - Configure hint label size
• glide.o.hint_label_generator - Set default label generator