Skip to content

Commit c7bfd40

Browse files
remarkablemarkremarkablemark
authored
Merge pull request #27 from remarkablemark/chore-readme
Tidy README instructions and examples
2 parents cfffc97 + b89ca5b commit c7bfd40

File tree

1 file changed

+109
-117
lines changed

1 file changed

+109
-117
lines changed

‎README.md

Lines changed: 109 additions & 117 deletions
Original file line numberDiff line numberDiff line change
@@ -7,22 +7,22 @@
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.
10+
An HTML to React parser:
1111

1212
```
1313
Parser(htmlString[, options])
1414
```
1515

16-
The parser converts an HTML string to [React element(s)](https://facebook.github.io/react/docs/glossary.html#react-elements). You can also `replace` element(s) with your own custom React element(s) via the parser options.
16+
The parser converts a string of HTML to [React Element(s)](https://facebook.github.io/react/docs/glossary.html#react-elements).
1717

18-
### Example
18+
There is also an option to [replace](#replacedomnode) element(s) with your own React Element(s) via the [parser options](#options).
19+
20+
#### Example
1921

2022
```js
2123
var Parser = require('html-react-parser');
22-
var reactElement = (
23-
Parser('<p>Hello, world!</p>') // same as `React.createElement('p', {}, 'Hello, world!')`
24-
);
25-
require('react-dom').render(reactElement, document.getElementById('root'));
24+
Parser('<p>Hello, world!</p>');
25+
// same output as `React.createElement('p', {}, 'Hello, world!')`
2626
```
2727

2828
## Installation
@@ -31,36 +31,70 @@ require('react-dom').render(reactElement, document.getElementById('root'));
3131
$ npm install html-react-parser
3232
```
3333

34+
Or you can download the script from a CDN:
35+
36+
```html
37+
<!-- HTMLReactParser depends on React -->
38+
<script src="https://unpkg.com/react@latest/dist/react.min.js"></script>
39+
<script src="https://unpkg.com/html-react-parser@latest/dist/html-react-parser.min.js"></script>
40+
```
41+
42+
See more [examples](https://github.com/remarkablemark/html-react-parser/tree/master/examples).
43+
3444
## Usage
3545

36-
Render to DOM:
46+
Given that you have the following required:
3747

3848
```js
39-
var Parser = require('html-react-parser');
40-
var ReactDOM = require('react-dom');
49+
// ES6
50+
import Parser from 'html-react-parser';
51+
import { render } from 'react-dom';
52+
```
53+
54+
You may render one element:
4155

42-
// single element
43-
ReactDOM.render(
56+
```js
57+
render(
4458
Parser('<p>single</p>'),
4559
document.getElementById('root')
4660
);
61+
```
4762

48-
// adjacent elements
49-
ReactDOM.render(
63+
You may render adjacent elements:
64+
65+
```js
66+
// with JSX
67+
render(
5068
// the parser returns an array for adjacent elements
5169
// so make sure they are nested under a parent React element
52-
React.createElement('div', {}, Parser('<p>one</p><p>two</p>'))
70+
<div>
71+
{Parser('<p>brother</p><p>sister</p>')}
72+
</div>,
73+
document.getElementById('root')
74+
);
75+
76+
// without JSX
77+
render(
78+
React.createElement('div', {},
79+
Parser('<p>brother</p><p>sister</p>')
80+
),
5381
document.getElementById('root')
5482
);
83+
```
84+
85+
You may render nested elements:
5586

56-
// nested elements
57-
ReactDOM.render(
87+
```js
88+
render(
5889
Parser('<ul><li>inside</li></ul>'),
5990
document.getElementById('root')
6091
);
92+
```
93+
94+
The parser will also preserve attributes:
6195

62-
// attributes are preserved
63-
ReactDOM.render(
96+
```js
97+
render(
6498
Parser('<section id="foo" class="bar baz" data-qux="42">look at me now</section>'),
6599
document.getElementById('root')
66100
);
@@ -70,122 +104,80 @@ ReactDOM.render(
70104

71105
#### replace(domNode)
72106

73-
The `replace` method allows you to swap an element with your own React element.
74-
75-
The first argument is `domNode`, which is an object which shares the same schema as the output from [htmlparser2.parseDOM](https://github.com/fb55/domhandler#example).
107+
The `replace` method allows you to swap an element with your own React Element.
76108

77-
```js
78-
Parser('<p id="replace">text</p>', {
79-
replace: function(domNode) {
80-
console.log(domNode);
81-
// { type: 'tag',
82-
// name: 'p',
83-
// attribs: { id: 'replace' },
84-
// children: [],
85-
// next: null,
86-
// prev: null,
87-
// parent: null }
88-
89-
return;
90-
// element is not replaced because
91-
// a valid React element is not returned
92-
}
93-
});
94-
```
109+
The first argument is `domNode`, which is an object that has the same output as [htmlparser2.parseDOM](https://github.com/fb55/domhandler#example).
95110

96-
Simple example:
111+
The element is only replaced if a valid React Element is returned.
97112

98113
```js
99-
var Parser = require('html-react-parser');
100-
var React = require('react');
101-
102-
var html = (
103-
'<div>' +
104-
'<p id="replace">'
105-
'replace me' +
106-
'</p>' +
107-
'</div>'
108-
);
109-
110-
var reactElement = Parser(html, {
111-
replace: function(domNode) {
114+
// with JSX
115+
Parser('<p id="replace">text</p>', {
116+
replace: (domNode) => {
112117
if (domNode.attribs && domNode.attribs.id === 'replace') {
113-
return React.createElement('span', {
114-
style: { fontSize: '42px' }
115-
}, 'replaced!');
116-
// equivalent jsx syntax:
117-
// return <span style={{ fontSize: '42px' }}>replaced!</span>;
118+
return <span>replaced</span>;
118119
}
119120
}
120121
});
121-
122-
require('react-dom').render(
123-
reactElement,
124-
document.getElementById('root')
125-
);
126-
// <div>
127-
// <span style="font-size: 42px;">
128-
// replaced!
129-
// </span>
130-
// </div>
131122
```
132123

133-
Advanced example (the replaced element's children are kept):
124+
Advanced example (keep the replaced children):
134125

135126
```js
136-
var Parser = require('html-react-parser');
137-
var React = require('react');
138-
139-
// used for recursively parsing DOM created from the HTML
140-
var domToReact = require('html-react-parser/lib/dom-to-react');
141-
142-
var html = (
143-
'<div>' +
144-
'<p id="main">' +
145-
'<span class="prettify">' +
146-
'keep me and make me pretty!' +
147-
'</span>' +
148-
'</p>' +
149-
'</div>'
150-
);
151-
152-
var parserConfig = {
153-
replace: function(domNode) {
154-
var parsedChildren;
155-
if (domNode.attribs) {
156-
if (domNode.attribs.id === 'main') {
157-
// continue parsing domNode's children with same config
158-
parsedChildren = domToReact(domNode.children, parserConfig);
159-
return React.createElement('span', {
160-
style: { fontSize: '42px' }
161-
}, parsedChildren);
162-
// equivalent jsx syntax:
163-
// return <span style={{ fontSize: '42px' }}>{parsedChildren}</span>;
164-
165-
} else if (domNode.attribs.class === 'prettify') {
166-
// continue parsing domNode's children with same config
167-
parsedChildren = domToReact(domNode.children, parserConfig);
168-
return React.createElement('span', {
169-
style: { color: 'hotpink' }
170-
}, parsedChildren);
171-
// equivalent jsx syntax:
172-
// return <span style={{ color: 'hotpink' }}>{parsedChildren}</span>;
173-
}
127+
// with ES6 and JSX
128+
129+
// converts dom object to React Elements
130+
import domToReact from 'html-react-parser/lib/dom-to-react';
131+
132+
const html = `
133+
<div>
134+
<p id="main">
135+
<span class="prettify">
136+
keep me and make me pretty!
137+
</span>
138+
</p>
139+
</div>
140+
`;
141+
142+
// parser config
143+
const options = {
144+
replace: (domNode) => {
145+
// do not replace if element has no attributes
146+
if (!domNode.attribs) return;
147+
148+
if (domNode.attribs.id === 'main') {
149+
return (
150+
<span style={{ fontSize: '42px' }}>
151+
{domToReact(domNode.children, options)}
152+
</span>
153+
);
154+
155+
} else if (domNode.attribs.class === 'prettify') {
156+
return (
157+
<span style={{ color: 'hotpink' }}>
158+
{domToReact(domNode.children, options)}
159+
</span>
160+
);
174161
}
175162
}
176163
};
177164

178-
require('react-dom').render(
179-
Parser(html, parserConfig),
165+
render(
166+
Parser(html, options),
180167
document.getElementById('root')
181168
);
182-
// <div>
183-
// <span style="font-size: 42px;">
184-
// <span class="prettify" style="color: hotpink;">
185-
// keep me and make me pretty!
186-
// </span>
187-
// </span>
188-
// </div>
169+
```
170+
171+
You will get the following:
172+
173+
```html
174+
<div>
175+
<span style="font-size: 42px;">
176+
<span class="prettify" style="color: hotpink;">
177+
keep me and make me pretty!
178+
</span>
179+
</span>
180+
</div>
189181
```
190182

191183
## Testing

0 commit comments

Comments
 (0)