Dim

Focus on the main logic more easily by dimming the details.

• Familiar
• Customizable
• Non-invasive
• Polyglot
• Responsive
• Lightweight

Features

Dim is many things but not dim.

Familiar

Dim is configured using regular expressions. Adopt it quickly and build up over time.

Restrained

Dim doesn't get in the way when user wants to work on details.

Respectful

During thorough readings Dim can be disabled per document. See also Toggling with Keyboard.

Polyglot

Dim accepts language-specific rules as well.

{
  "[javascript]": {
    "dim.rules": [
      {
        "pattern": "console\\.log\\(.*?\\)",
      },
    ],
  },
}

Organized

Set defaults for RegEx flags and the opacity tier at root. All rules inherit them unless override.

{
  "dim.defaultOpacityTier": "min",
  "dim.valueForMinTier": 0.2,
  "dim.valueForMidTier": 0.3,
  "dim.valueForMaxTier": 0.4,
}

Consistent

Rules accept opacity tiers instead of direct values. Tweak defaults and they'll be applied everywhere.

{
  "dim.rules": [
    { "pattern": "FIXME: .*", "opacity": "max" }
    { "pattern": "TODO: .*", "opacity": "mid" }
    { "pattern": "DONE: .*" } // "min"
  ]
}

Forgiving

Dim checks for brace balance ({ }) inside matches to prevent eye irritation and performance problems that would arise when incomplete sections of code cause a rule to match into the next section's ending. (Experimental)

Performance

Dim is designed for speed.

Fluid

Dim doesn't run on scroll, so you can peek fast.

Remembering

Dim caches the compiled RegExes for faster refreshes after selection and content changes as well as switching tabs.

Mindful

Where some competitors iterate lines one-by-one looking for <start> and <end> tokens, Dim runs each rule against the full-text.

Steady

Dim preserves the unaffected decorations from the previous cycle to reduce flicker.

Attentive

Dim hooks into lifecycle events. It runs after each document reveal, content or config change, and selection change, balancing responsiveness and performance.

Tunable

Dim can be adjusted to react faster and more frequently to user events as the hardware allows.

Lightweight

Dim is a zero-dependency, bundled extension that activates in around 5ms.

Example configuration

{
  "[go]": {
    "dim.rules": [
      {
        // Dim Go's error wrapping blocks to "mid" tier.
        "pattern": "if err != nil {.*?}",
        "flags": "gs",
        "opacity": "mid",
      },
    ],
  },
  "[javascript]": {
    "dim.rules": [
      {
        // Dim the console.log calls including the args.
        "pattern": "console\\.log\\(.*?\\)",
      },
    ],
  },
  "dim.rules": [
    {
      // Dim the comment lines
      "pattern": "//.*",
      "opacity": "max",
    },
  ],
  "dim.defaultFlags": "g",
  "dim.defaultOpacityTier": "min",
  "dim.valueForMinTier": 0.2,
  "dim.valueForMidTier": 0.3,
  "dim.valueForMaxTier": 0.4,
}

Suggestions

Use code completion

Package file contains the configuration schema. Use code completion for configuration details.

Escaping RegExes inside JSON

Escape patterns with backslashes as shown in the examples.

Start simple

Some find RegEx cluttered. Some find it familiar and capable. If that's not you, just start simple and improve the rules over time.

Nested scopes

Patterns that allow nested scopes improve the user experience noticeably. See the test configuration for more examples.

For example, this lil' one combines lookarounds and single line mode with a "strange" pattern to dim the conditional branches of if statements without the condition expression itself, and allows one level of nesting with additional parentheses and braces. (Regex101)

{
  "[typescript]": {
    "dim.rules": [
      {
        "pattern": "(?<=(?:else|if \\([^()]*(?:\\([^()]*\\)[^()]*)*\\)) {)[^{}]*(?:{[^}]*}[^{}]*)*(?=})",
        "flags": "gs",
      },
    ],
  },
}

Matching blocks

Use RegEx's single-line s mode for matching blocks. (MDN, StackOverflow)

Toggling Dim with keyboard

Create a keyboard binding. Open the command palette and find: Preferences: Open Keyboard Shortcuts (JSON). Then add a new entry.

{
  "key": "alt+cmd+h",
  "command": "dim.toggleDimForCurrentEditor"
}

Discussions

GitHub Discussions is open for users to report bugs, suggest features and ask questions.

Prior work

Dim has inherited some code and logic from lowlight-patterns.

License

See LICENSE file