Configuration Guide

This guide explains how to configure SmartMotion using setup({ ... }), what the default options look like, and how your configuration is passed into the pipeline.

---

⚙️ Default Config

Here’s what the default config looks like internally:

local default_config = {
  keys = "fjdksleirughtynm", -- Keys used for hints
  use_background_highlights = false, -- Toggles between character and background highlights
  highlight = { -- Highlights used for hints
    hint = "SmartMotionHint",
    hint_dim = "SmartMotionHintDim",
    two_char_hint = "SmartMotionTwoCharHint",
    two_char_hint_dim = "SmartMotionTwoCharHintDim",
    dim = "SmartMotionDim",
    search_prefix = "SmartMotionSearchPrefix",
    search_prefix_dim = "SmartMotionSearchPrefixDim",
  },
  presets = {},
}

[!NOTE] The highlight values can either be highlight group names (strings) or tables with custom colors ({ fg = "#HEX" }).

---

🧪 Simple Config Example

return {
  "FluxxField/smart-motion.nvim",
  opts = {},
}

This will use all default settings — no presets, default highlight groups, and default label keys.

---

✅ Enable All Presets

return {
  "FluxxField/smart-motion.nvim",
  opts = {
    presets = {
      words = true,
      lines = true,
      search = true,
      delete = true,
      yank = true,
      change = true,
    },
  },
}

You can also exclude individual motions:

presets = {
  words = { "w", "b" },
  delete = false,
}

---

🎨 Override Highlights

highlight = {
  hint = { fg = "#FF2FD0" },
  two_char_hint = { fg = "#2FD0FF" },
  dim = { fg = "Comment" },
}

This allows SmartMotion to fit your theme or visual system.

You can also use the toggle use_background_highlights to change between character and background hints

opts = {
  use_background_highlights = true,
}

---

🧷 Change Keys

keys = "arstneio"

This defines the keys used for labeling. The string should contain only unique, lowercase characters.

[!IMPORTANT] The number of unique targets you can display depends on how many keys you define. With N keys, SmartMotion can create up to N^2 unique 2-character labels. If you use too few keys, you may not be able to label all targets.

---

🔁 Passing Config to Modules and Why It Matters

Every module receives:

• ctx: context like bufnr, winid, cursor_line
• cfg: your full setup() config
• motion_state: shared mutable state for the current motion

[!TIP] This means cfg is available inside collectors, extractors, filters, visualizers, actions, and wrappers.

[!NOTE] The reason cfg is passed to all modules is to support advanced behavior as SmartMotion evolves. For example:

• A future setting like flow_timeout (for how fast you must press to chain motions) may be needed by visualizers or wrappers.
• A debug flag could enable extra logging in actions.
• A max_targets setting might help collectors limit result size.

Passing cfg gives you full access to your own global settings inside any stage of the motion pipeline.

---

🔧 Registering Inside config = function()

If you're using Lazy.nvim or another plugin manager, this is the best place to register custom modules or motions:

return {
  "FluxxField/smart-motion.nvim",
  config = function()
    local sm = require("smart-motion")
    sm.register_motion("x", { ... })
    sm.filters.register("my_filter", MyFilter)
  end,
}

This ensures all your code runs after SmartMotion is loaded and configured.

---

Next:

• custom_motion.md
• presets.md