Vue Highlight Words

Common errors

• [Vue warn]: Failed to resolve component: Highlighter

  cause The `Highlighter` component was not correctly imported or registered in your Vue application.
  fix Ensure `import Highlighter from 'vue-highlight-words'` is present in your script block and `Highlighter` is listed in the `components` option of your Vue component (e.g., `components: { Highlighter }`).

• TypeError: Cannot read properties of undefined (reading 'split') (or similar error related to array methods)

  cause The `searchWords` prop expects an array of strings, but it received an undefined or non-array value.
  fix Always pass an array of strings to the `searchWords` prop. If the input is from a string, ensure it's processed into an array (e.g., `this.words.split(' ')`) before binding.

• Property or method "text" is not defined on the instance but referenced during render

  cause A data property or computed property referenced in the template (e.g., `text` or `keywords`) has not been correctly defined in the component's `data()` or `computed` options.
  fix Verify that all variables used in your template are properly declared in the `data()` return object or as `computed` properties within your Vue component's script block.

Warnings

• breaking Version 3.0.0 removed Babel transpilation for distribution code, which might affect older build setups expecting CommonJS output or specific transpilation targets. It also included a full TypeScript rewrite.
  Fix: Ensure your project's build configuration correctly handles modern JavaScript modules (ESM) and TypeScript definitions. Update CommonJS `require` statements to access the `.default` export if necessary.
• breaking The `custom` prop was removed in v3.0.0. Custom rendering logic must now be implemented directly using slots.
  Fix: Refactor your component to utilize the default slot for custom rendering of highlighted chunks, passing `v-slot` props as needed.
• breaking Version 2.0.0 introduced breaking changes by dropping support for Vue 2, now exclusively supporting Vue 3.0.0 and newer. Additionally, `highlight tag props` were removed.
  Fix: For Vue 2 projects, use the `1.0` branch or a `vue-highlight-words` version `<2.0.0`. For Vue 3, use custom render functions with scoped slots instead of the removed `highlight tag props` for advanced styling.
• gotcha This package is specifically for Vue 3. If you are developing with Vue 2, you must use a version from the `1.0` branch, which is separately maintained.
  Fix: For Vue 2, install `vue-highlight-words@^1.0.0`. For Vue 3, install `vue-highlight-words@^3.0.0` (or `^2.0.0` for earlier Vue 3 versions).

Install

• npm install vue-highlight-words npm
• yarn add vue-highlight-words yarn
• pnpm add vue-highlight-words pnpm

Imports

• Highlighter
  wrong:

  import { Highlighter } from 'vue-highlight-words'

  correct:

  import Highlighter from 'vue-highlight-words'

  The component is exported as the default export. Named imports like `{ Highlighter }` will not work.
• Highlighter (CommonJS)
  wrong:

  const Highlighter = require('vue-highlight-words')

  correct:

  const { default: Highlighter } = require('vue-highlight-words')

  Since v3.0.0, the package may be ESM-only, requiring access to the `.default` property for CommonJS interop in some environments.
• Highlighter Component Type

  import type Highlighter from 'vue-highlight-words'

  For TypeScript users, importing the component's type definition is useful for prop typing or component references.

Quickstart

This example demonstrates how to import and use the `Highlighter` component within a Vue 3 Single File Component (SFC), providing text to highlight and an array of search terms.

<template>
  <div id="app">
    <Highlighter class="my-highlight" :style="{ color: 'red' }"
      highlightClassName="highlight"
      :searchWords="keywords"
      :autoEscape="true"
      :textToHighlight="text"/>
  </div>
</template>

<script>
import Highlighter from 'vue-highlight-words'

export default {
  name: 'app',
  components: {
    Highlighter
  },
  data() {
    return {
      text: 'The dog is chasing the cat. Or perhaps they\'re just playing?',
      words: 'and or the'
    }
  },
  computed: {
    keywords() {
      return this.words.split(' ')
    }
  }
}
</script>