Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/Raathigesh/dazzle
:rocket: Dashboards made easy in React JS.
https://github.com/Raathigesh/dazzle
analytics dashboard dashboard-widget drag-and-drop react-js visualization
Last synced: 2 months ago
JSON representation
:rocket: Dashboards made easy in React JS.
- Host: GitHub
- URL: https://github.com/Raathigesh/dazzle
- Owner: Raathigesh
- License: mit
- Created: 2016-04-09T14:21:41.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2019-12-12T14:46:40.000Z (almost 5 years ago)
- Last Synced: 2024-06-18T21:46:15.594Z (3 months ago)
- Topics: analytics, dashboard, dashboard-widget, drag-and-drop, react-js, visualization
- Language: JavaScript
- Homepage:
- Size: 1.83 MB
- Stars: 1,439
- Watchers: 39
- Forks: 143
- Open Issues: 19
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-star-libs - Raathigesh / dazzle
README
React Dazzle
Dashboards made easy in React JS
**Looking for maintainers https://github.com/Raathigesh/dazzle/issues/41**
Dazzle is a library for building dashboards with React JS. Dazzle does not depend on any front-end libraries but it makes it easier to integrate with them.
Dazzle's goal is to be flexible and simple. Even though there are some UI components readily available out of the box, you have the complete control to override them as you wish with your own styles and layout.
## Features
- Grid based layout
- Add/Remove widgets
- Drag and drop widget re-ordering
- UI framework agnostic
- Simple yet flexible
- Well documented (It's a feature! Don't you think?)
## Installation
```
$ npm install react-dazzle --save
```
## Dazzle me
[Here is a demo.](http://raathigesh.com/dazzle) Widgets shows fake data though but they look so damn cool (At least for me).
###### [Repository of the demo is available here.](https://github.com/Raathigesh/Dazzle-Starter-Kit)
## Usage
```javascript
import React, { Component } from 'react';
import Dashboard from 'react-dazzle';
// Your widget. Just another react component.
import CounterWidget from './widgets/CounterWidget';
// Default styles.
import 'react-dazzle/lib/style/style.css';
class App extends Component {
constructor() {
this.state = {
widgets: {
WordCounter: {
type: CounterWidget,
title: 'Counter widget',
}
},
layout: {
rows: [{
columns: [{
className: 'col-md-12',
widgets: [{key: 'WordCounter'}],
}],
}],
}
};
}
render() {
return
}
}
```
Dazzle uses [react-dnd](https://github.com/react-dnd/react-dnd). The default _Dashboard_ component of Dazzle is wrapped by [_DragDropContext_](https://react-dnd.github.io/react-dnd/docs-drag-drop-context.html) of react-dnd.
So you may want to use react-dnd in your React component hierarchy upper than where you use the _Dashboard_ component of Dazzle. If you do so then you can't let Dazzle creating the _DragDropContext_ because you want to create it yourself upper in the React component hierarchy of your application.
So forth please use the _DashboardWithoutDndContext_ component of Dazzle and wrapped your own component with _DragDropContext(HTML5Backend)_:
```javascript
import React, { Component } from 'react';
import { DashboardWithoutDndContext } from 'react-dazzle';
// react-dnd
import { DragDropContext } from 'react-dnd';
import HTML5Backend from 'react-dnd-html5-backend';
// Your widget. Just another react component.
import CounterWidget from './widgets/CounterWidget';
// Default styles.
import 'react-dazzle/lib/style/style.css';
class App extends Component {
constructor() {
this.state = {
widgets: {
WordCounter: {
type: CounterWidget,
title: 'Counter widget',
}
},
layout: {
rows: [{
columns: [{
className: 'col-md-12',
widgets: [{key: 'WordCounter'}],
}],
}],
}
};
}
render() {
return
}
}
export default DragDropContext(HTML5Backend)(App);
```
## API
| Props | Type| Description | Required |
| --- | --- | --- | --- |
| layout | Object | Layout of the dashboard. | Yes |
| widgets | Object| Widgets that could be added to the dashboard. | Yes |
| editable | Boolean |Indicates whether the dashboard is in editable mode. | No |
| rowClass | String |CSS class name(s) that should be given to the row div element. Default is `row`. | No |
| editableColumnClass | String |CSS class name(s) that should be used when a column is in editable mode. | No |
| droppableColumnClass | String |CSS class name(s) that should be used when a widget is about to be dropped in a column. | No |
| frameComponent | Component | Customized frame component which should be used instead of the default frame. [More on custom frame component.](https://github.com/Raathigesh/Dazzle/blob/master/docs/ImplementingACustomFrame.md) | No |
| addWidgetComponent | Component | Customized add widget component which should be used instead of the default AddWidget component. [More on custom add widget component.](https://github.com/Raathigesh/Dazzle/blob/master/docs/ImplementingCustomAddWidgetButton.md) | No |
| addWidgetComponentText | String | Text that should be displayed in the Add Widget component. Default is `Add Widget`. | No |
| onAdd(layout, rowIndex, columnIndex) | function |Will be called when user clicks the `AddWidget` component.| No |
| onRemove(layout) | function |Will be called when a widget is removed.| No |
| onMove(layout) | function | Will be called when a widget is moved.| No |
#### Providing `widgets`
`widgets` prop of the dashboard component takes an object. A sample `widgets` object would look like below. This object holds all the widgets that could be used in the dashboard.
```javascript
{
HelloWorldWidget: {
type: HelloWorld,
title: 'Hello World Title',
props: {
text: 'Hello Humans!'
}
},
AnotherWidget: {
type: AnotherWidget,
title: 'Another Widget Title'
}
}
```
- `type` property - Should be a React component function or class.
- `title` property - Title of the widget that should be displayed on top of the widget.
- `props` property - Props that should be provided to the widget.
#### Dashboard `layout`
The `layout` prop takes the current layout of the dashboard. Layout could have multiple rows and columns. A sample layout object with a single row and two columns would look like below.
```javascript
{
rows: [{
columns: [{
className: 'col-md-6 col-sm-6 col-xs-12',
widgets: [{key: 'HelloWorldWidget'}]
}, {
className: 'col-md-6 col-sm-6 col-xs-12',
widgets: [{key: 'AnotherWidget'}]
}]
}]
}
```
- `className` property - CSS class(es) that should be given to the column in the grid layout. Above sample layout uses the classes from bootstrap library. You could use the classes of your CSS library.
- `widgets` property - An array of widgets that should be rendered in that particular column. `key` property of the widgets array should be a key from the `widgets` object.
#### Edit mode
Setting `editable` prop to `true` will make the dashboard editable.
#### Add new widget
When user tries to add a new widget, the `onAdd` callback will be called. More info here on how to handle widget addition.
#### Remove a widget
When a widget is removed, `onRemove` method will be called and new layout (The layout with the widget removed) will be available as an argument of `onRemove` method. Set the provided layout again to the dashboard to complete the widget removal. [The Sample repository has the this feature implemented](https://github.com/Raathigesh/Dazzle-Starter-Kit/blob/master/src/components/Dashboard.jsx).
## Customization
#### Implementing custom `WidgetFrame` component
A frame is the component which surrounds a widget. A frame has the title and the close button. Dazzle provides a default frame out of the box. But if you want, you can customize the frame as you like. More info here.
#### Implementing custom `AddWidget` component
Dazzle also allows you to customize the `Add Widget` component which appears when you enter edit mode. More info here.
## Issues
- Improve drag and drop experience ([#1](https://github.com/Raathigesh/Dazzle/issues/1))
## License
MIT © [Raathigeshan](https://twitter.com/Raathigeshan)
