Skip to content

Commit 2bd6519

Browse files
docs(readme): reindent file, tidy examples, and improve wording
1 parent 9ed889c commit 2bd6519

File tree

1 file changed

+67
-90
lines changed

1 file changed

+67
-90
lines changed

README.md

Lines changed: 67 additions & 90 deletions
Original file line numberDiff line numberDiff line change
@@ -7,15 +7,14 @@
77
[![Coverage Status](https://coveralls.io/repos/github/remarkablemark/html-react-parser/badge.svg?branch=master)](https://coveralls.io/github/remarkablemark/html-react-parser?branch=master)
88
[![Dependency status](https://david-dm.org/remarkablemark/html-react-parser.svg)](https://david-dm.org/remarkablemark/html-react-parser)
99

10-
An HTML to React parser:
11-
10+
An HTML to React parser that works on the server and the browser:
1211
```
13-
Parser(htmlString[, options])
12+
HTMLReactParser(htmlString[, options])
1413
```
1514

16-
The parser converts an HTML string to [React Element(s)](https://facebook.github.io/react/docs/react-api.html#creating-react-elements).
15+
It converts an HTML string to [React elements](https://facebook.github.io/react/docs/react-api.html#creating-react-elements).
1716

18-
There is also an option to [replace](#replacedomnode) element(s) with your own React Element(s) via the [parser options](#options).
17+
There's also an [option](#options) to [replace](#replacedomnode) elements with your own custom React elements.
1918

2019
## Example
2120

@@ -25,7 +24,7 @@ Parser('<p>Hello, world!</p>');
2524
// same output as `React.createElement('p', {}, 'Hello, world!')`
2625
```
2726

28-
[JSFiddle](https://jsfiddle.net/remarkablemark/7v86d800/)
27+
[JSFiddle](https://jsfiddle.net/remarkablemark/7v86d800/) | [repl.it](https://repl.it/@remarkablemark/html-react-parser)
2928

3029
## Installation
3130

@@ -49,159 +48,137 @@ yarn add html-react-parser
4948
<script src="https://unpkg.com/html-react-parser@latest/dist/html-react-parser.min.js"></script>
5049
```
5150

52-
See [examples](https://github.com/remarkablemark/html-react-parser/tree/master/examples).
51+
More [examples](https://github.com/remarkablemark/html-react-parser/tree/master/examples).
5352

5453
## Usage
5554

56-
Given that you have the following imported:
57-
55+
Given you have the following imported:
5856
```js
5957
// ES Modules
6058
import Parser from 'html-react-parser';
6159
import { render } from 'react-dom';
6260
```
6361

64-
You can render an element:
65-
62+
Render a single element:
6663
```js
6764
render(
68-
Parser('<p>single</p>'),
69-
document.getElementById('root')
65+
Parser('<h1>single</h1>'),
66+
document.getElementById('root')
7067
);
7168
```
7269

73-
You can render multiple elements:
74-
70+
Render multiple elements:
7571
```js
7672
// with JSX
7773
render(
78-
// the parser returns an array for adjacent elements
79-
// so make sure they are nested under a parent React element
80-
<div>
81-
{Parser('<p>brother</p><p>sister</p>')}
82-
</div>,
83-
document.getElementById('root')
74+
// the parser returns an array for adjacent elements
75+
// so make sure they're nested under a parent React element
76+
<div>{Parser('<p>brother</p><p>sister</p>')}</div>,
77+
document.getElementById('root')
8478
);
8579

86-
// without JSX
80+
// or without JSX
8781
render(
88-
React.createElement('div', {},
89-
Parser('<p>brother</p><p>sister</p>')
90-
),
91-
document.getElementById('root')
82+
React.createElement('div', {}, Parser('<p>brother</p><p>sister</p>')),
83+
document.getElementById('root')
9284
);
9385
```
9486

95-
You can render nested elements:
96-
87+
Render nested elements:
9788
```js
9889
render(
99-
Parser('<ul><li>inside</li></ul>'),
100-
document.getElementById('root')
90+
Parser('<ul><li>inside</li></ul>'),
91+
document.getElementById('root')
10192
);
10293
```
10394

104-
The parser will also preserve attributes:
105-
95+
Renders with attributes preserved:
10696
```js
10797
render(
108-
Parser('<section id="foo" class="bar baz" data-qux="42">look at me now</section>'),
109-
document.getElementById('root')
98+
Parser('<p id="foo" class="bar baz" data-qux="42">look at me now</p>'),
99+
document.getElementById('root')
110100
);
111101
```
112102

113103
### Options
114104

115105
#### replace(domNode)
116106

117-
The `replace` method allows you to swap an element with your own React Element.
107+
The `replace` method allows you to swap an element with your own React element.
118108

119-
The first argument is `domNode`, which is an object that has the same output as [`htmlparser2.parseDOM`](https://github.com/fb55/domhandler#example).
109+
The first argument is `domNode`--an object with the same output as [htmlparser2](https://github.com/fb55/htmlparser2)'s [domhandler](https://github.com/fb55/domhandler#example).
120110

121-
The element is only replaced if a valid React Element is returned.
111+
The element is replaced only if a valid React element is returned.
122112

123113
```js
124-
// with JSX
125114
Parser('<p id="replace">text</p>', {
126-
replace: function(domNode) {
127-
if (domNode.attribs && domNode.attribs.id === 'replace') {
128-
return <span>replaced</span>;
129-
}
115+
replace: function(domNode) {
116+
if (domNode.attribs && domNode.attribs.id === 'replace') {
117+
return React.createElement('span', {}, 'replaced');
130118
}
119+
}
131120
});
132121
```
133122

134-
Advanced example (keep the replaced children):
135-
123+
Here's an [example](https://repl.it/@remarkablemark/html-react-parser-replace-example) that replaces but keeps the children:
136124
```js
137125
// with ES6 and JSX
138-
139-
// converts DOM object to React Elements
140126
import domToReact from 'html-react-parser/lib/dom-to-react';
141127

142-
const html = `
143-
<div>
144-
<p id="main">
145-
<span class="prettify">
146-
keep me and make me pretty!
147-
</span>
148-
</p>
149-
</div>
128+
const htmlString = `
129+
<p id="main">
130+
<span class="prettify">
131+
keep me and make me pretty!
132+
</span>
133+
</p>
150134
`;
151135

152136
const parserOptions = {
153-
replace: (domNode) => {
154-
// do not replace if element has no attributes
155-
if (!domNode.attribs) return;
156-
157-
if (domNode.attribs.id === 'main') {
158-
return (
159-
<span style={{ fontSize: '42px' }}>
160-
{domToReact(domNode.children, options)}
161-
</span>
162-
);
163-
164-
} else if (domNode.attribs.class === 'prettify') {
165-
return (
166-
<span style={{ color: 'hotpink' }}>
167-
{domToReact(domNode.children, options)}
168-
</span>
169-
);
170-
}
137+
replace: ({ attribs, children }) => {
138+
if (!attribs) return;
139+
140+
if (attribs.id === 'main') {
141+
return (
142+
<h1 style={{ fontSize: 42 }}>
143+
{domToReact(children, parserOptions)}
144+
</h1>
145+
);
146+
} else if (attribs.class === 'prettify') {
147+
return (
148+
<span style={{ color: 'hotpink' }}>
149+
{domToReact(children, parserOptions)}
150+
</span>
151+
);
171152
}
153+
}
172154
};
173155

174-
render(
175-
Parser(html, parserOptions),
176-
document.getElementById('root')
177-
);
156+
const reactElement = Parser(htmlString, parserOptions);
157+
ReactDOMServer.renderToStaticMarkup(reactElement);
178158
```
179159

180-
It will output the following:
181-
160+
[Output](https://repl.it/@remarkablemark/html-react-parser-replace-example):
182161
```html
183-
<div>
184-
<span style="font-size: 42px;">
185-
<span class="prettify" style="color: hotpink;">
186-
keep me and make me pretty!
187-
</span>
188-
</span>
189-
</div>
162+
<h1 style="font-size:42px">
163+
<span style="color:hotpink">
164+
keep me and make me pretty!
165+
</span>
166+
</h1>
190167
```
191168

192169
## Testing
193170

194171
```sh
195-
$ npm test
196-
$ npm run lint
172+
npm test
173+
npm run lint # npm run lint:fix
197174
```
198175

199176
## Release
200177

201178
```sh
202-
$ npm run release
203-
$ npm publish
204-
$ git push --follow-tags
179+
npm run release
180+
npm publish
181+
git push --follow-tags
205182
```
206183

207184
## Special Thanks

0 commit comments

Comments
 (0)