Skip to content

Commit e22fd27

Browse files
committed
docs(readme): adds "Providing data" section
1 parent d546002 commit e22fd27

File tree

1 file changed

+34
-7
lines changed

1 file changed

+34
-7
lines changed

README.md

Lines changed: 34 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -31,9 +31,11 @@ React D3 Tree is a [React](http://facebook.github.io/react/) component that lets
3131
- [Installation](#installation)
3232
- [Usage](#usage)
3333
- [Props](#props)
34-
- [Styling Nodes](#styling-nodes)
35-
- [Styling Links](#styling-links)
36-
- [Event Handlers](#event-handlers)
34+
- [Working with the default Tree](#working-with-the-default-tree)
35+
- [Providing `data`](#providing-data)
36+
- [Styling Nodes](#styling-nodes)
37+
- [Styling Links](#styling-links)
38+
- [Event Handlers](#event-handlers)
3739
- [Customizing the Tree](#customizing-the-tree)
3840
- [`renderCustomNodeElement`](#rendercustomnodeelement)
3941
- [`pathFunc`](#pathfunc)
@@ -108,7 +110,31 @@ For details on all props accepted by `Tree`, check out the [TreeProps reference
108110

109111
The only required prop is [data](https://bkrem.github.io/react-d3-tree/docs/interfaces/_tree_types_.treeprops.html#data), all other props on `Tree` are optional/pre-defined (see "Default value" on each prop definition).
110112

111-
## Styling Nodes
113+
## Working with the default Tree
114+
`react-d3-tree` provides default implementations for `Tree`'s nodes & links, which are intended to get you up & running with a working tree quickly.
115+
116+
This section is focused on explaining **how to provide data, styles and event handlers for the default `Tree` implementation**.
117+
118+
> Need more fine-grained control over how nodes & links appear/behave? Check out the [Customizing the Tree](#customizing-the-tree) section below.
119+
120+
### Providing `data`
121+
By default, `Tree` expects each node object in `data` to implement the [`RawNodeDatum` interface](https://bkrem.github.io/react-d3-tree/docs/interfaces/_types_common_.rawnodedatum.html):
122+
123+
```ts
124+
interface RawNodeDatum {
125+
name: string;
126+
attributes?: Record<string, string>;
127+
children?: RawNodeDatum[];
128+
}
129+
```
130+
131+
The `orgChart` example in the [Usage](#usage) section above is an example of this:
132+
133+
- Every node has at least a `name`. This is rendered as the **node's primary label**.
134+
- Some nodes have `attributes` defined (the `CEO` node does not). **The key-value pairs in `attributes` are rendered as a list of secondary labels**.
135+
- Nodes can have further `RawNodeDatum` objects nested inside them via the `children` key, creating a hierarchy from which the tree graph can be generated.
136+
137+
### Styling Nodes
112138
`Tree` provides the following props to style different types of nodes, all of which use an SVG `circle` by default:
113139

114140
- `rootNodeClassName` - applied to the root node.
@@ -129,7 +155,8 @@ To visually distinguish these three types of nodes from each other by color, we
129155
}
130156

131157
.node__leaf > circle {
132-
/* Let's make the radius of leaf nodes larger */
158+
fill: green
159+
/* Let's also make the radius of leaf nodes larger */
133160
r: 40;
134161
}
135162
```
@@ -159,7 +186,7 @@ export default function StyledNodesTree() {
159186
160187
<!-- For a full list of options of CSS properties that can be used for the default nodes, check the SVG circle [specification](TODO:) -->
161188

162-
## Styling Links
189+
### Styling Links
163190
`Tree` provides the `pathClassFunc` property to pass additional classNames to every link to be rendered.
164191

165192
Each link calls `pathClassFunc` with its own `TreeLinkDatum` and the tree's current `orientation`. `Tree` expects `pathClassFunc` to return a `className` string.
@@ -192,7 +219,7 @@ function StyledLinksTree() {
192219

193220
> For more details, see the `PathClassFunction` [reference docs](https://bkrem.github.io/react-d3-tree/docs/modules/_types_common_.html#pathclassfunction).
194221
195-
## Event Handlers
222+
### Event Handlers
196223
`Tree` exposes the following event handler callbacks by default:
197224

198225
- [onLinkClick](https://bkrem.github.io/react-d3-tree/docs/interfaces/_tree_types_.treeprops.html#onlinkclick)

0 commit comments

Comments
 (0)