vue-diff-next

A lightweight diff viewer component for Vue 3.5+. Inspired by vue-diff, which was archived in February 2025.

Same props, same modes, same look. ~18 kB gzip for the default bundle (style.css + component JS) with 30 languages bundled, versus roughly 75 kB for the original covering 7.

Try the Live Demo to see it in action.

• Drop-in replacement — every vue-diff prop and default is preserved, verified against the original's own output
• 30 languages, all bundled; no per-language imports or registration
• Split and unified modes, with word-level highlighting composed on top of syntax highlighting

Install

npm install vue-diff-next

Vue 3.5 or newer is a peer dependency.

Usage

As a component:

<script setup>
import { Diff } from 'vue-diff-next';
import 'vue-diff-next/style.css';
</script>

<template>
  <Diff mode="split" theme="dark" language="javascript" :prev="before" :current="after" />
</template>

Or registered globally as a plugin:

import { createApp } from 'vue';
import VueDiff from 'vue-diff-next';
import 'vue-diff-next/style.css';

createApp(App).use(VueDiff).mount('#app');
// Renders as <Diff>, or pass { componentName: 'VueDiff' } to rename it.

The stylesheet is not optional — the component ships unstyled without it.

Props

| Prop | Type | Default | Description | | ----------------- | --------------------------------------------- | ------------- | ------------------------------------------------------------------------ | | mode | 'split' \| 'unified' | 'split' | Side-by-side or interleaved. | | theme | 'dark' \| 'light' \| custom* \| ... | 'dark' | See Theming. | | language | string | 'plaintext' | See Languages. | | prev | string \| null | '' | The "before" text. | | current | string \| null | '' | The "after" text. | | showLineNumbers | boolean | true | Diff line-number gutter. Set false to hide it. | | folding | boolean | false | Collapse long runs of unchanged lines. See Folding. | | foldMarker | 'dots' \| 'hunk' | 'dots' | How a collapsed run is marked. See Folding. | | inputDelay | number | 0 | Debounce re-rendering, in ms. Useful for editor-driven input. | | virtualScroll | boolean \| { height, lineMinHeight, delay } | false | Render only the rows near the viewport. See Large diffs. | | wrap | boolean | true | Soft-wrap long lines. Set false to scroll horizontally instead. |

Migrating from vue-diff

Change the import and the stylesheet path:

- import VueDiff from 'vue-diff';
- import 'vue-diff/dist/index.css';
+ import VueDiff from 'vue-diff-next';
+ import 'vue-diff-next/style.css';

That is the whole migration. Props, defaults, modes, and both install paths are unchanged.

A few things to know:

• theme="custom*" still works, but the CSS custom properties you override are named differently. See Theming.
• theme="light" / "dark" are a different palette than vue-diff's highlight.js vs / monokai. For those colors use visual-studio-light / monokai-dark and import the matching extra stylesheet (see Theming).
• Language names still work, and more are accepted. javascript, plaintext, markdown, and typescript all resolve as before.
• virtualScroll behaves as it did, windowing the output to what is near the viewport. See Large diffs.

How it differs internally

Same behaviour, different internals:

• diff (jsdiff) instead of diff-match-patch for line and word diffing.
• @speed-highlight/core instead of highlight.js. The reduced library size is mostly the highlighter: highlight.js's engine alone is 22.4 kB gzip, while @speed-highlight/core's engine plus all bundled grammars is about 9 kB.
• No @vueuse/core. Its debounce was the only part used; that is now a few lines.
• Word-diff and syntax highlighting are composed at the token level. The original injected <vue-diff-modified> marker strings into the source before highlighting and string-replaced them afterwards, which breaks if the content contains the marker. Here the two overlapping classifications are merged by splitting the token stream at word boundaries, so no string injection happens and content cannot impersonate a marker.
• Highlighting is synchronous. Grammars ship in the bundle, so each visible row tokenizes in the same tick as the source change.

Folding

With folding, runs of unchanged lines collapse to a single marker row, so a small change in a large file doesn't bury the diff. foldMarker chooses how that row looks:

<Diff :folding="true" fold-marker="hunk" :prev="before" :current="after" />

dots (default) — a centred •••••, matching the original:

  12  const config = {
   >  • • • • •
  47    timeout: 5000,

hunk — a unified-diff header, stating how much was skipped rather than only that something was:

  12  const config = {
   >  @@ -13,34 +13,34 @@
  47    timeout: 5000,

Both are styleable — see --vue-diff-fold-* under Theming. The dots' size and spacing are variables, so you can tune them without overriding the content.

A changed line is never hidden by folding, and the first unchanged line after each change stays visible as context.

Languages

Pass any of these to language. Aliases in the right column resolve to the same grammar, so highlight.js names and file extensions both work:

| Group | Languages | Also accepted | | ----------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | | Web | html css js ts json xml | htm vue · scss sass less · javascript jsx mjs cjs · typescript tsx · svg · jsdoc | | Systems | c rs go java py pl lua asm bf | cpp c++ h cs · rust · golang · python py3 · perl · assembly · brainfuck | | Data & config | yaml toml ini csv sql md leanpub-md | yml · conf cfg · markdown | | Shell & ops | bash docker make git diff http uri log | sh zsh shell · dockerfile · makefile · patch · url | | Other | regex todo plain | plaintext text |

Matching is case-insensitive and surrounding whitespace is ignored.

An unknown language renders as plain text rather than throwing, so user-supplied language names are safe to pass straight through.

Theming

| theme | Palette | Stylesheet | | --------------------- | ------------------------------------------ | ---------------------------------------------- | | dark (default) | VS Code-ish dark | vue-diff-next/style.css | | light | VS Code-ish light | vue-diff-next/style.css | | atom-dark | Atom One Dark | vue-diff-next/themes/atom-dark.css | | atom-light | Atom One Light | vue-diff-next/themes/atom-light.css | | coral-dark | Coral keywords, teal strings | vue-diff-next/themes/coral-dark.css | | coral-light | Same tokens, darkened for a white canvas | vue-diff-next/themes/coral-light.css | | github-dark | GitHub Dark | vue-diff-next/themes/github-dark.css | | github-light | GitHub Light | vue-diff-next/themes/github-light.css | | monokai-dark | highlight.js monokai (vue-diff dark) | vue-diff-next/themes/monokai-dark.css | | twilight-dark | highlight.js base16-twilight | vue-diff-next/themes/twilight-dark.css | | visual-studio-dark | highlight.js vs2015 | vue-diff-next/themes/visual-studio-dark.css | | visual-studio-light | highlight.js vs (vue-diff light) | vue-diff-next/themes/visual-studio-light.css | | custom* | Unstyled; you supply the CSS | none |

dark and light ship in the default stylesheet. Extra palettes are a second import — the wrapper class is always applied; without the extra CSS they look like an unstyled custom* theme:

import 'vue-diff-next/style.css';
import 'vue-diff-next/themes/visual-studio-light.css';

<Diff theme="visual-studio-light" ... />

If you bind theme dynamically, import every extra file you might select.

Everything is driven by CSS custom properties, so you can override any part without forking the stylesheet:

.vue-diff-theme-dark {
  --vue-diff-added-bg: #143d2b;
  --vue-diff-removed-bg: #45161a;
  --vue-diff-syn-kwd: #ff7b72;
}

For a wholly separate theme, pass any theme value beginning with custom. The component adds vue-diff-theme-<value> to its wrapper and ships no styles for it — you supply them:

<Diff theme="custom-solarized" ... />

.vue-diff-theme-custom-solarized {
  --vue-diff-bg: #002b36;
  --vue-diff-fg: #839496;
  /* …and the rest */
}

Available properties: --vue-diff-{bg,fg,font-family,font-size,line-height,gutter-width}, --vue-diff-{gutter-bg,gutter-fg}, --vue-diff-{added,removed,disabled}-bg, --vue-diff-{added,removed}-gutter-bg, --vue-diff-{added,removed}-word-bg, --vue-diff-fold-{bg,fg}, --vue-diff-fold-dot-{size,spacing,opacity}, --vue-diff-fold-hunk-opacity, and --vue-diff-syn-{kwd,str,num,bool,cmnt,func,class,var,type,oper,section,insert,deleted,err}.

Large diffs

A few thousand rows lay out and paint slowly — the cost is DOM size and per-line highlighting, not diffing. Each visible row tokenizes in the same tick; without windowing, a large file means thousands of DOM nodes and thousands of highlight passes.

Use virtualScroll for large diffs. It renders only the rows near the viewport:

<Diff :virtual-scroll="true" :prev="before" :current="after" />

<!-- or tune it -->
<Diff
  :virtual-scroll="{ height: 500, lineMinHeight: 24, delay: 100 }"
  :prev="before"
  :current="after"
/>

| Option | Default | Meaning | | --------------- | ------- | ---------------------------------------------------- | | height | 500 | Viewer height in px. Also sets the windowing extent. | | lineMinHeight | 24 | Assumed row height until one is measured. | | delay | 100 | Scroll throttle in ms. |

The window extends 1.5 viewport heights past each edge, so ordinary scrolling does not outrun it. Row heights are measured rather than assumed — a wrapped line can be any height — so the container's scroll height converges on the truth as rows report in, and the scrollbar reflects the whole diff rather than only what is rendered.

Measured on a 2000-line diff in a 500px viewer: 53 rows in the DOM instead of 2000, with a 48,000px scroll range. Only those visible rows are highlighted.

Security

The component renders untrusted text as HTML, so escaping is a correctness requirement rather than a detail. All text is escaped before insertion, and the escaping boundary is a single small module with its own test suite covering <script> tags, inline event handlers, and attribute-breaking quotes.

Found a hole? Please report it privately — see SECURITY.md.