This section explores advanced SmartMotion concepts, best practices, and techniques for building custom motion ecosystems.

Flow state allows users to chain motions rapidly without showing hints every time.

• When you trigger a motion (like w) and select a target fast enough, SmartMotion enters flow.
• If you press another valid motion key (like w, b, etc.) within a short time (e.g., 300ms), the motion skips hinting and jumps to the next target.
• This creates a seamless, native-like experience.

• Feels like traditional Vim navigation.
• Dramatically improves speed and usability when repeating motions.

[!NOTE] > flow_timeout will be configurable in the future and accessible via cfg.

Instead of writing new actions for every combination (like dw, ct)), SmartMotion supports action merging:

action = merge({ "jump", "delete" })

This behaves like a normal motion + operator combo.

You can even register pre-combined actions like delete_jump or change_jump if needed.

SmartMotion’s registry system means any plugin or config can contribute:

• Custom extractors
• New actions
• Visualizers that open Telescope, float windows, etc.

These are globally available. If a plugin registers telescope_visualizer, you can use it in your pipeline with:

visualizer = "telescope_visualizer"

You can dynamically build and assign targets to motion_state.targets and skip the pipeline entirely. This is useful for:

• Manual label systems
• Search results
• LSP symbol queries

SmartMotion allows full control over highlight groups. You can change foreground colors, add backgrounds, or even point to existing highlight groups in your colorscheme.

You can pass a highlight table in your config:

require("smart-motion").setup({
  highlight = {
    hint = { fg = "#FFD700", bg = "#222222", bold = true },
    first_char = "Type", -- use an existing highlight group
    dim = "Comment",
  },
})

SmartMotion supports both:

• Tables with fg, bg, bold, italic, underline.
• Strings referring to existing highlight groups.

If a string group is invalid, it will fall back to the default.

If your colorscheme changes, SmartMotion will reapply your highlights automatically to ensure consistency.

Want a 3-character search? Want to ask the user twice? Want a modal search interface? Wrappers give you complete control over how and when run_pipeline() is invoked.

• Use log.debug(...) inside any module to output motion data
• Temporarily swap in the default visualizer to simplify feedback
• Set highlights to high-contrast colors to ensure visualizer output is visible

Next:

• config.md
• custom_motion.md