react-native-tree-visualizer
Version:
ui component for visualizing a tree, updating the tree nodes, delete the tree nodes and other operations
151 lines (125 loc) • 12.7 kB
Markdown
# TreeVisualizer Component
A flexible and customizable React component for visualizing tree data structures with interactive controls. This component provides extensive styling options, multiple node shapes, and interactive features for managing tree nodes.
## Documentation & Repository
<p>
<a href="https://react-native-tree-visualizer-docs.vercel.app/developerMode">
<img src="https://img.shields.io/badge/docs-View-blue?style=for-the-badge&logo=read-the-docs" alt="Documentation"/>
</a>
<a href="https://github.com/MachaVivek/react-native-tree-visualizer-docs">
<img src="https://img.shields.io/badge/github-View-black?style=for-the-badge&logo=github" alt="GitHub"/>
</a>
</p>
## Installation
```typescript
npm i react-native-tree-visualizer
```
## Import
```typescript
import { TreeNode, TreeVisualizer } from 'react-native-tree-visualizer';
```
## Basic Usage
```typescript
const [tree, setTree] = useState<TreeNode<{}>>(initialTreeData);
<TreeVisualizer
tree={tree}
setTree={setTree}
showControls={true}
/>
```
## Props Reference
| . Prop Name . | . Type . | . Default . | Required | Description |
| ---------------------------------------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tree` | `TreeNode<T>` | — | Yes | The tree data structure to be visualized. This is the main data object that the component renders. |
| `setTree` | `React.Dispatch<React.SetStateAction<TreeNode<T>>>` | — | Yes | State setter function for updating the tree. Used to handle node additions, removals, and edits when interactive controls are enabled. |
| `showControls` | `boolean` | `false` | No | Enables or disables interactive controls (add, edit, remove, view buttons) on tree nodes. Set to `true`to allow users to interact with the tree. |
| `nodeLength` | `number` | `50` | No | The size of individual nodes in pixels. Controls the radius for circular nodes or the dimensions for other shapes. Larger values create bigger visual nodes. |
| `levelGap` | `number` | `nodeLength * 2.8` | No | The vertical spacing between tree levels in pixels. Determines how far apart parent and child nodes appear vertically. Increase for more spread-out trees. |
| `nodeShape` | `NodeShape` | `"circle"` | No | The visual shape of tree nodes. Determines the rendered appearance of each node in the tree visualization. |
| `nodeStrokeColor` | `string` | `'white'` | No | The border/outline color of nodes. Accepts any valid CSS color value (hex, rgb, named colors, etc.). |
| `nodeStrokeWidth` | `number` | `2` | No | The thickness of node borders in pixels. Controls how prominent the node outlines appear. |
| `isCurvedPath` | `boolean` | `false` | No | When `true`, renders curved paths connecting parent and child nodes. When `false`, renders straight lines. Creates different visual aesthetics for the tree connections. |
| `pathStrokeColor` | `string` | `'white'` | No | The color of the lines connecting nodes. Accepts any valid CSS color value. |
| `pathStrokeWidth` | `number` | `2` | No | The thickness of connection lines in pixels. Thicker values make connections more visible. |
| `textColor` | `string` | `'white'` | No | The color of text displayed inside nodes and labels. Accepts any valid CSS color value. |
| `backgroundColor` | `string` | `'black'` | No | The background color of the entire canvas or container. Sets the overall visualization background. |
| `buttonBackgroundColor` | `string` | `'white'` | No | The background color of interactive control buttons. Used as the default button styling when button-specific colors aren't provided. |
| `buttonTextColor` | `string` | `'black'` | No | The text color displayed on interactive buttons. Ensures button labels are readable against the button background. |
| `orientation` | `"Portrait" \| "Landscape"` | `"Portrait"` | No | Controls the layout direction of the tree.`Portrait`displays trees vertically (top-to-bottom),`Landscape`displays horizontally (left-to-right). |
| `viewButtonColor` | `string` | `'#3b82f6'` | No | The color of the view/inspect button. Typically used to display node details or information. |
| `removeButtonColor` | `string` | `'#ef4444'` | No | The color of the delete/remove button. Usually a red tone to indicate destructive action. |
| `addButtonColor` | `string` | `'#22c55e'` | No | The color of the add/create button. Typically a green tone to indicate creation. |
| `editButtonColor` | `string` | `'#eab308'` | No | The color of the edit/modify button. Usually a yellow/amber tone to indicate modification. |
| `modalAnimationType` | `"fade" \| "slide" \| "dotZoom"` | `"dotZoom"` | No | The entrance animation style for modals/dialogs.`fade`provides a smooth opacity transition,`slide`moves from the edge,`dotZoom`zooms in from a point. |
| `modelOverlayColor` | `string` | `"rgba(255,255,255,0.5)"` | No | The background color of the modal overlay (scrim). Accepts any valid CSS color value with alpha channel. Darker values make the overlay more opaque. |
## Prop Types
```typescript
type NodeShape = "circle" | "square" | "rectangle" | "diamond"; // Example values
```
## Examples
### Basic Tree Visualization
```typescript
<TreeVisualizer
tree={myTree}
setTree={setMyTree}
/>
```
### Interactive Tree with Custom Styling
```typescript
<TreeVisualizer
tree={myTree}
setTree={setMyTree}
showControls={true}
nodeLength={60}
levelGap={150}
nodeShape="square"
nodeStrokeColor="#3b82f6"
pathStrokeColor="#3b82f6"
backgroundColor="#1f2937"
textColor="#f3f4f6"
/>
```
### Landscape Orientation with Curved Paths
```typescript
<TreeVisualizer
tree={myTree}
setTree={setMyTree}
orientation="Landscape"
isCurvedPath={true}
nodeLength={45}
levelGap={200}
pathStrokeWidth={3}
/>
```
## Type Definitions
```typescript
interface ITreeNodeComponentProps<T extends Record<string, string> = {}> {
tree: TreeNode<T>
setTree: React.Dispatch<React.SetStateAction<TreeNode<T>>>
showControls?: boolean
nodeLength?: number
levelGap?: number
nodeShape?: NodeShape
nodeStrokeColor?: string
nodeStrokeWidth?: number
isCurvedPath?: boolean
pathStrokeColor?: string
pathStrokeWidth?: number
textColor?: string
backgroundColor?: string
buttonBackgroundColor?: string
buttonTextColor?: string
orientation?: "Portrait" | "Landscape"
viewButtonColor?: string
removeButtonColor?: string
addButtonColor?: string
editButtonColor?: string
modalAnimationType?: "fade" | "slide" | "dotZoom"
modelOverlayColor?: string
}
```
## Notes
* All color props accept standard CSS color values: hex (`#ff0000`), rgb (`rgb(255, 0, 0)`), rgba (`rgba(255, 0, 0, 0.5)`), and named colors (`red`).
* The `levelGap` default value is dynamically calculated as `nodeLength * 2.8`, so adjusting `nodeLength` will proportionally affect spacing if `levelGap` is not explicitly set.
* When `showControls` is enabled, ensure adequate spacing (`nodeLength` and `levelGap`) to accommodate button displays.
* The `modelOverlayColor` prop affects the visual intensity of modal backdrops; use more opaque values to dim the background more effectively.
* For best readability, ensure sufficient contrast between `textColor` and `backgroundColor`, and between button colors and `buttonBackgroundColor`.