1 | <img src="https://cloud.githubusercontent.com/assets/29597/11913937/0d2dcd78-a629-11e5-83e7-6a17b6d765a5.png" width="260" height="260">
|
2 |
|
3 | React component to highlight words within a larger body of text.
|
4 |
|
5 | Check out a demo [here](https://bvaughn.github.io/react-highlight-words).
|
6 |
|
7 | ## Usage
|
8 |
|
9 | To use it, just provide it with an array of search terms and a body of text to highlight.
|
10 |
|
11 | [Try this example in Code Sandbox.](https://codesandbox.io/s/5v8yqoxv7k)
|
12 |
|
13 | ```html
|
14 | import React from "react";
|
15 | import ReactDOM from "react-dom";
|
16 | import Highlighter from "react-highlight-words";
|
17 |
|
18 | ReactDOM.render(
|
19 | <Highlighter
|
20 | highlightClassName="YourHighlightClass"
|
21 | searchWords={["and", "or", "the"]}
|
22 | autoEscape={true}
|
23 | textToHighlight="The dog is chasing the cat. Or perhaps they're just playing?"
|
24 | />,
|
25 | document.getElementById("root")
|
26 | );
|
27 | ```
|
28 |
|
29 | And the `Highlighter` will mark all occurrences of search terms within the text:
|
30 |
|
31 | <img width="368" alt="screen shot 2015-12-19 at 8 23 43 am" src="https://cloud.githubusercontent.com/assets/29597/11914033/e3c319f6-a629-11e5-896d-1a5ce22c9ea2.png">
|
32 |
|
33 | ## Props
|
34 |
|
35 | | Property | Type | Required? | Description |
|
36 | |:---|:---|:---:|:---|
|
37 | | activeClassName | String | | The class name to be applied to an active match. Use along with `activeIndex` |
|
38 | | activeIndex | String | | Specify the match index that should be actively highlighted. Use along with `activeClassName` |
|
39 | | activeStyle | Object | | The inline style to be applied to an active match. Use along with `activeIndex` |
|
40 | | autoEscape | Boolean | | Escape characters in `searchWords` which are meaningful in regular expressions |
|
41 | | className | String | | CSS class name applied to the outer/wrapper `<span>` |
|
42 | | caseSensitive | Boolean | | Search should be case sensitive; defaults to `false` |
|
43 | | findChunks | Function | | Use a custom function to search for matching chunks. This makes it possible to use arbitrary logic when looking for matches. See the default `findChunks` function in [highlight-words-core](https://github.com/bvaughn/highlight-words-core) for signature. Have a look at the [custom findChunks example](https://codesandbox.io/s/k20x3ox31o) on how to use it. |
|
44 | | highlightClassName | String or Object | | CSS class name applied to highlighted text or object mapping search term matches to class names. |
|
45 | | highlightStyle | Object | | Inline styles applied to highlighted text |
|
46 | | highlightTag | Node | | Type of tag to wrap around highlighted matches; defaults to `mark` but can also be a React element (class or functional) |
|
47 | | sanitize | Function | | Process each search word and text to highlight before comparing (eg remove accents); signature `(text: string): string` |
|
48 | | searchWords | Array<String | RegExp> | ✓ | Array of search words. String search terms are automatically cast to RegExps unless `autoEscape` is true. |
|
49 | | textToHighlight | String | ✓ | Text to highlight matches in |
|
50 | | unhighlightClassName | String | | CSS class name applied to unhighlighted text |
|
51 | | unhighlightStyle | Object | | Inline styles applied to unhighlighted text |
|
52 |
|
53 | ## Custom highlight tag
|
54 |
|
55 | By default this component uses an HTML Mark Text element (`<mark>`) to wrap matched text, but you can inject a custom tag using the `highlightTag` property. This tag should be a React component that accepts the following properties:
|
56 |
|
57 | | Property | Type | Description |
|
58 | |:---|:---|:---|
|
59 | | children | String | Text to be highlighted |
|
60 | | highlightIndex | Number | Index of matched text |
|
61 |
|
62 | For example:
|
63 | ```js
|
64 | const Highlight = ({ children, highlightIndex }) => (
|
65 | <strong className="highlighted-text">{children}</strong>
|
66 | );
|
67 | ```
|
68 |
|
69 | ## Installation
|
70 | ```
|
71 | yarn add react-highlight-words
|
72 | ```
|
73 |
|
74 | ```
|
75 | npm i --save react-highlight-words
|
76 | ```
|
77 |
|
78 | ## License
|
79 | MIT License - fork, modify and use however you want.
|