BumbleTap Guide

BumbleTap lets you control any website with keyboard shortcuts and automated workflows. Here's the quick overview.

Quick Start

1. Click the BumbleTap icon in your browser toolbar to open the popup.
2. Click + Add Key Binding and record a key combination.
3. Choose an action: click an element, type text, trigger a built-in event, or write custom code.
4. Use the element picker (crosshair icon) to select elements on the page.
5. Press your shortcut on the page to trigger the action.

Global vs Site Bindings

Site bindings only work on the site you created them for (e.g., youtube.com). Global bindings work on every site. Toggle between them using the globe icon in the popup.

Global bindings can exclude specific sites if needed. Site bindings always take priority over global bindings with the same key.

Each keybinding maps a key combination to an action. You can create single-key shortcuts or multi-key chord sequences.

Action Types

Chord Shortcuts

Chords are multi-key sequences pressed one after another — like G then D. Unlike key combos (Ctrl+S), chords let you create hundreds of shortcuts using memorable letter sequences.

• Chord timeout (200–3000ms) — how long to wait between keys before resetting
• Chord overlay — optional visual indicator showing chord progress
• Configure both in the popup's Global Defaults settings

URL Scoping

Restrict when a binding activates by matching the current URL:

Use the Test URL button to verify your pattern matches the current page.

Pre-built browser and media actions you can trigger without writing code.

Scroll

Media

Media actions auto-detect the active video/audio. You can also target a specific element by CSS selector.

Navigation

Zoom

Automated workflows that run sequences of steps when triggered. Each auto-action has a trigger (when to run), optional URL filter (where to run), and a list of steps (what to do).

How It Works

1. Open the popup on your target site and click + Add Auto-Action.
2. Name your action and choose a trigger (when it should fire).
3. Optionally set a URL filter to restrict which pages it runs on.
4. Add steps — each step performs one operation in sequence.
5. Click Test to try it on the current page, then Save.

URL Filtering

Control which pages the action runs on:

• All pages — runs on every page of the site
• Pattern — wildcard matching, e.g., */video/*
• Regex — full regular expression, e.g., /watch\?v=/

See the sub-topics in the sidebar for details on each trigger type, step type, the Extract system, and If/Else branching.

Triggers

Triggers determine when your auto-action fires.

Step Types

Each auto-action consists of steps executed in order. Add steps via the + buttons in the editor.

Click

Click an element identified by CSS selector. Use the element picker to select it visually.

• Selector — CSS selector for the target element
• Element name — optional human-readable label
• Selector index — which match to click if multiple elements match (0 = first)

Text Input

Type text into a form field.

• Text content — what to type. Supports {{variables}}
• Clear first — select all existing text before typing
• Press Enter — submit after typing

Wait

Pause execution before continuing to the next step. Three modes:

Custom JS

Run arbitrary JavaScript code. Same helpers as keybinding custom code. Use ctx.get() / ctx.set() to read and write variables. See the Custom Code and ctx API pages.

Extract

Pull data from page elements into named variables for use in later steps. This is a powerful data-capture step — see Extract & Variables for full details.

If/Else

Conditional branching based on element presence or a JavaScript condition. See If/Else Branching for details.

Extract & Variables

The Extract step pulls data from page elements and stores it in named variables. Later steps can reference these variables using {{variableName}} syntax.

How to Use

1. Add an Extract step in the auto-action editor.
2. Enter a variable name (e.g., pageTitle).
3. Pick an element using the element picker or type a CSS selector.
4. Choose what to extract (text, value, attribute, etc.).
5. Click Preview to test the extraction on the current page.
6. In later steps, use {{pageTitle}} in text fields, or ctx.get('pageTitle') in Custom Code steps.

Extraction Targets

Extract All Matches

Enable "Extract all matches" to capture data from every element matching the selector, not just the first.

• Result is always an array
• {{prices}} joins with comma: 10.00,25.00,7.50
• {{prices[0]}} accesses the first item: 10.00
• {{prices[2]}} accesses the third item: 7.50

Table Extraction

Extract structured data from HTML tables or repeated list elements:

// Configuration:
Row selector:  "table.prices tbody tr"
Columns:
  product  →  "td:nth-child(1)"
  price    →  "td:nth-child(2)"

// Result stored in variable:
[
  { product: "Widget A", price: "$10.00" },
  { product: "Widget B", price: "$25.00" }
]

Transform

Apply a JavaScript expression to modify the extracted value before storing it. The raw value is available as value:

Live Preview

Click the Preview button to run the extraction on the current page instantly. The result appears inline — green for success, red for errors. Transform is applied in the preview too.

Using Extracted Data in Custom Code

In text fields, use {{variableName}}. But in Custom JS steps, variables are accessed through the ctx API instead:

// Read a value set by a previous Extract step
const title = ctx.get('pageTitle');
const price = ctx.get('prices[0]');  // array access

// Write a new variable for later steps
ctx.set('fullLabel', title + ' — ' + price);

All ctx operations are synchronous — no await needed. See the full ctx API reference for path syntax and lifecycle details.

If/Else Branching

Add conditional logic to your workflows. Run different steps based on whether an element exists or a JavaScript expression is true.

Condition Types

Branches

• Then — steps that run if the condition is true
• Else — steps that run if the condition is false (optional)
• Each branch can contain any step type: click, text, wait, JS, or even nested if/else

Example: Auto-dismiss Cookie Banner

IF element exists: "#cookie-banner .accept-btn"
  THEN:
    Click → "#cookie-banner .accept-btn"
  ELSE:
    Wait → 2000ms
    IF element exists: ".gdpr-overlay .dismiss"
      THEN: Click → ".gdpr-overlay .dismiss"

Write JavaScript that runs when you press a shortcut or when an auto-action step executes. Your code has full DOM access, async/await support, and a set of built-in helper functions.

Rules

• await works directly — no wrapper function needed
• External libraries: add them via the Libraries panel on the custom-code step (fetched once at edit time, then cached offline)
• DOM access works normally — read, modify, create any HTML element
• Page JavaScript variables are not accessible (isolated execution context). Bundle libraries via the Libraries panel.

Examples

Click a button

$('.subscribe-button').click();

Wait for element, then click

const btn = await waitForElement('.cookie-accept');
btn.click();
toast('Done!', 'success');

Toggle video playback speed

const v = getActiveVideo();
if (v) {
  v.playbackRate = v.playbackRate === 1 ? 2 : 1;
  toast('Speed: ' + v.playbackRate + 'x');
}

Save data across page loads

let count = storage.get('clicks') || 0;
count++;
storage.set('clicks', count);
toast('Clicked ' + count + ' times');

Use a bundled library

Attach canvas-confetti via the Libraries panel (it fetches once from a CDN and caches the bundle with the action). Then reference its export directly:

confetti({ particleCount: 200, spread: 90 });

See Helper Functions and ctx API in the sidebar for the complete reference.

Helper Functions

Available directly in your custom code — no imports needed.

DOM Selection

Media

Async

Storage

UI

Context Objects

ctx API

In custom JS steps, the ctx object gives you synchronous read/write access to the shared variable pool.

API Reference

Examples

Read a variable from a previous Extract step

const title = ctx.get('pageTitle');
toast('Title: ' + title);

Set a variable for later steps

const count = $$('.item').length;
ctx.set('itemCount', count);
// Later steps can use {{itemCount}} in text fields

Read nested paths

// If a previous extract stored an object or array:
const first = ctx.get('prices[0]');        // array index
const name = ctx.get('user.name');        // dot path
const deep = ctx.get('data[0].items[2].id'); // deep path

Lifecycle

• All ctx operations are synchronous — no await needed
• Variables are pre-loaded before your code runs and written back after it completes
• Variables persist across page navigations within the same browser session
• Variables are shared across all actions and tabs (cross-action by design)
• Variables clear when the browser closes

Use {{variableName}} in any text field to insert dynamic values. Variables can be built-in or created by Extract steps and custom code.

Built-in Variables

User Variables

Create your own variables two ways:

• Extract step — pull data from page elements into a named variable
• ctx.set() — write a variable from custom JavaScript code

Path Syntax

Access nested data with dot notation and bracket indexes:

Where Variables Work

• Text input steps and keybindings — {{email}} in the text field
• CSS selectors — .item[data-id="{{itemId}}"]
• Wait conditions — dynamic wait targets
• NOT in custom code — use ctx.get() instead
• NOT in variable names — variableName is always literal

Variables Sidebar

The auto-action editor has a Variables sidebar (toggle via the header button) that shows all current variables with their names, sources (which step created them), and values. It updates after every test run.

Record your interactions — clicks, typing, scrolling, navigation — and convert them into auto-action steps.

How to Record

1. Open the auto-action editor and click the Record button.
2. A dark toolbar appears at the top of the page showing recording status.
3. Interact with the page normally — your actions are captured as steps.
4. Click Stop in the toolbar (or press the stop button) to finish.
5. The recorded steps appear in the auto-action editor for review and editing.

What Gets Captured

Toolbar Controls

A searchable overlay listing all your keybindings — site-specific and global. Find and execute any binding instantly.

How to Use

1. Press the palette shortcut (configure in popup's Global Defaults under "Command Palette Shortcut").
2. A search overlay appears. Start typing to filter bindings.
3. Use ↑ ↓ arrow keys to navigate, Enter to execute, Esc to close.

Features

• Fuzzy search across binding names, selectors, element names, and custom code names
• Dimmed items — bindings whose target elements are missing on the current page appear dimmed
• Instant execution — run any binding without remembering its shortcut
• Shows both site-specific and global bindings applicable to the current page

BumbleTap ships with a Chrome side panel SPA — a dockable editor for actions, bindings, recording, and per-site settings. It opens alongside the page, or as a detached pop-out window.

What's in the panel

• Home — site dashboard, scope switcher, recent activity.
• Auto-Actions — list, inline editor, run/test, logs, per-action variables.
• Keybindings — inline-expand rows for add/edit/delete/duplicate.
• Recorder — live capture + review before saving.
• Sites — manage every registered site from one place.
• Settings — playback, recording defaults, import/export, and binding mode defaults.

Binding Modes

A binding mode controls which tab the side panel (or pop-out) reads bindings from and runs actions against. Change the default in Settings → Pop-out & Sidebar, or override per-instance via the pin button in the header.

Action-lock

If an auto-action is running, the panel queues any incoming tab or mode changes until the run completes. Your action finishes against the hostname it started on — no mid-flight context shifts.

Edge cases

• Pinned tab navigates to a new site → the panel follows; the tab identity is the anchor.
• Pinned tab closes → empty state with a re-pin call-to-action.
• Pinned tab moves to another window → the panel follows to the new window.
• Tab is discarded (Chrome sleep) → auto-waked when an action runs.
• No tab matches a pinned hostname → a fresh tab is opened with the last-known URL.
• Browser restart with Pin to tab → the panel tries to re-pin to a tab whose URL matches; otherwise shows the empty state.

Pop-out & Pinning

The header pin control lives next to the title: an icon button opens the mode menu, the pill next to it shows the current target (favicon + name). Click the pill to re-pin.

Opening a pop-out

1. Open the side panel (Ctrl+Shift+Y or extension icon).
2. Click the pop-out icon in the home header — a detached window spawns.
3. The new pop-out starts in your global default mode (Settings → Pop-out & Sidebar).

Changing mode on a running pop-out

1. Click the pin icon in the header (or press Ctrl+Shift+P).
2. Pick a mode from the menu.
3. For Pin to tab, click the target pill to choose which tab (current tab, or pick from a list).

Multiple pop-outs

Each pop-out is independent. One can be pinned to youtube.com, another to a specific Jira ticket tab, a third in follow-window mode — they all work side by side.

Window title

Pop-outs update their window title with the pin target (e.g. BumbleTap — pinned to youtube.com). Handy when several pop-outs are in your taskbar.

Sidebars

The docked sidebar supports the same modes except Follow focused window (which is incoherent for a docked UI). Picking that mode in Settings has no effect on sidebars.

Keyboard Shortcuts

All panel-side shortcuts work in both the sidebar and the pop-out. They do not conflict with page-level bindings — BumbleTap binds them on the panel document only.

BumbleTap requires a one-time setup for custom code features.

Enable User Scripts (Required for Custom Code)

1. Go to chrome://extensions in your browser.
2. Find BumbleTap and click Details.
3. Find "Allow in Developer Mode" (or "Allow User Scripts") and turn it ON.
4. Click the reload button (↻) on BumbleTap, then refresh any open pages.

Permissions Explained

Privacy

All your data stays on your device. BumbleTap has no servers, no accounts, and no analytics. Your settings are stored locally using Chrome's storage API. Nothing is ever transmitted.

See the Privacy Policy for full details.