1 | <img src="https://naver.github.io/billboard.js/img/logo/billboard.js.svg" width="350" alt="billboard.js"><br>
|
2 |
|
3 | [![Latest Version][badge-latest]][link-version] [![Next version][badge-next]][link-version] [![semantic-release][badge-semantic-release]][link-semantic-release]
|
4 |
|
5 | ![CI Status][badge-ci-status] [![Coverage Status][badge-coverage]][link-coverage] [![Known Vulnerabilities][badge-snyk]][link-snyk]
|
6 | [![download][badge-download]][link-download] [![jsDelivr][badge-jsDelivr]][link-jsDelivr] [![gzip size][badge-gzip-size]][link-gzip-size]
|
7 |
|
8 | billboard.js is a re-usable, easy interface JavaScript chart library, based on D3 v4+.
|
9 | > The name "billboard" comes from the famous `billboard chart` which everybody knows.<br>
|
10 | > - [Why we decided to start billboard.js?](https://github.com/naver/billboard.js/wiki/Why-we-decided-to-start-billboard.js%3F)
|
11 |
|
12 | ## Documents
|
13 | - [API Documentation](https://naver.github.io/billboard.js/release/latest/doc/)
|
14 | - [Examples](https://naver.github.io/billboard.js/demo/)
|
15 | - [Roadmap](https://github.com/naver/billboard.js/wiki/Roadmap)
|
16 | - [Contribution Guide](CONTRIBUTING.md)
|
17 | - [Comparison table with other libraries](https://github.com/naver/billboard.js/wiki/Comparison-table)
|
18 | - [Migration guide from C3.js](https://github.com/naver/billboard.js/wiki/How-to-migrate-from-C3.js%3F)
|
19 | - [Third Party Applications](https://github.com/naver/billboard.js/wiki/Third-party-applications)
|
20 | - [Who's using billboard.js](https://github.com/naver/billboard.js/wiki/Who's-using-billboard.js)
|
21 | - [Benchmark](https://naver.github.io/billboard.js/demo/benchmark/)
|
22 | - v2 updates:
|
23 | - [v2 CHANGELOG](https://github.com/naver/billboard.js/wiki/CHANGELOG-v2)
|
24 | - [Migration Guide to v2](https://github.com/naver/billboard.js/wiki/Migration-Guide-to-v2)
|
25 |
|
26 | ## Playground
|
27 | Play with the diverse options generating on the fly!
|
28 | - https://naver.github.io/billboard.js/playground/ (obsolete)
|
29 | - https://beta.observablehq.com/@idris-maps/billboard-js-playground (by [@idris-maps](https://github.com/idris-maps))
|
30 |
|
31 | ## Questions?
|
32 | If you have any questions, checkout the previous posts or create a new one at:
|
33 | - [Stack Overflow: billboard.js tagged posts](https://stackoverflow.com/questions/tagged/billboard.js)
|
34 | - [Issue with 'question' label](https://github.com/naver/billboard.js/issues?utf8=%E2%9C%93&q=label%3Aquestion)
|
35 |
|
36 | ## Supported chart types
|
37 | <img src="https://naver.github.io/billboard.js/img/chart-types.png?v=9" width=800>
|
38 |
|
39 | ## Download and Installation
|
40 |
|
41 | Download dist files from the repo directly or install it via npm.
|
42 |
|
43 | ### For development (Uncompressed)
|
44 |
|
45 | You can download the uncompressed files for development
|
46 |
|
47 | #### Latest
|
48 | - https://naver.github.io/billboard.js/release/latest/dist/billboard.js
|
49 | - https://naver.github.io/billboard.js/release/latest/dist/billboard.css
|
50 |
|
51 | #### Specific version
|
52 | - https://naver.github.io/billboard.js/release/[VERSION]/dist/billboard.js
|
53 | - https://naver.github.io/billboard.js/release/[VERSION]/dist/billboard.css
|
54 |
|
55 | ### For production (Compressed)
|
56 |
|
57 | You can download the compressed files for production
|
58 |
|
59 | #### Latest
|
60 | - https://naver.github.io/billboard.js/release/latest/dist/billboard.min.js
|
61 | - https://naver.github.io/billboard.js/release/latest/dist/billboard.min.css
|
62 |
|
63 | #### Specific version
|
64 | - https://naver.github.io/billboard.js/release/[VERSION]/dist/billboard.min.js
|
65 | - https://naver.github.io/billboard.js/release/[VERSION]/dist/billboard.min.css
|
66 |
|
67 | ### Packaged version (with D3.js inclusion)
|
68 | > Packaged version is not an official distribution.
|
69 | > It's to provide an easy way to load 'billboard.js' with dependency.
|
70 |
|
71 | - **Latest**
|
72 | - https://naver.github.io/billboard.js/release/latest/dist/billboard.pkgd.js
|
73 | - https://naver.github.io/billboard.js/release/latest/dist/billboard.pkgd.min.js
|
74 | - **Specific version**
|
75 | - https://naver.github.io/billboard.js/release/[VERSION]/dist/billboard.pkgd.js
|
76 | - https://naver.github.io/billboard.js/release/[VERSION]/dist/billboard.pkgd.min.js
|
77 |
|
78 | ### Themes
|
79 | > If you want apply themes, simply load one of the theme css file provided instead of the default css file.
|
80 | > - [Screenshot Preview](https://github.com/naver/billboard.js/wiki/Themes)
|
81 |
|
82 | #### datalab
|
83 | - https://naver.github.io/billboard.js/release/latest/dist/theme/datalab.css
|
84 | - https://naver.github.io/billboard.js/release/latest/dist/theme/datalab.min.css
|
85 |
|
86 |
|
87 | #### insight
|
88 | - https://naver.github.io/billboard.js/release/latest/dist/theme/insight.css
|
89 | - https://naver.github.io/billboard.js/release/latest/dist/theme/insight.min.css
|
90 |
|
91 | #### graph
|
92 | - https://naver.github.io/billboard.js/release/latest/dist/theme/graph.css
|
93 | - https://naver.github.io/billboard.js/release/latest/dist/theme/graph.min.css
|
94 |
|
95 | ### Nightly version
|
96 |
|
97 | Nightly version is the latest build from the master branch.
|
98 | With nightly, you can try upcoming changes prior the official release.
|
99 |
|
100 | - https://github.com/naver/billboard.js/tree/nightly/dist
|
101 |
|
102 | > The version info will be given as the build datetime: `x.x.x-nightly-yyyymmddhhmmss`
|
103 |
|
104 | There're two ways to install from `nightly` branch directly.
|
105 | ```js
|
106 | // Specify on 'package.json' file
|
107 | "dependencies": {
|
108 | ...
|
109 | "billboard.js": "git://github.com/naver/billboard.js.git#nightly"
|
110 | },
|
111 | ```
|
112 |
|
113 | ```sh
|
114 | # Run install command from shell
|
115 | $ npm install git+https://github.com/naver/billboard.js.git#nightly --save
|
116 | ```
|
117 |
|
118 | ### Next(Release Canditate) version
|
119 |
|
120 | Next version is the 'release candidate' build, prior the latest official release.
|
121 |
|
122 | ```sh
|
123 | # Run install command from shell
|
124 | $ npm install billboard.js@next --save
|
125 | ```
|
126 |
|
127 | ### Installation with npm
|
128 |
|
129 | ```bash
|
130 | $ npm install billboard.js
|
131 | ```
|
132 |
|
133 | ### Using CDN
|
134 |
|
135 | If you want to use 'billboard.js' without installation, load files directly from one of the CDN providers.
|
136 |
|
137 | - cdnjs: https://cdnjs.com/libraries/billboard.js
|
138 | - jsDelivr: https://cdn.jsdelivr.net/npm/billboard.js/dist/
|
139 | - PageCDN: https://pagecdn.com/lib/billboardjs
|
140 | - unpkg: https://unpkg.com/billboard.js/dist/
|
141 |
|
142 | ## Supported Browsers
|
143 |
|
144 | > Basically will work on all SVG supported browsers.
|
145 |
|
146 | |Internet Explorer|Chrome|Firefox|Safari|iOS|Android|
|
147 | |---|---|---|---|---|---|
|
148 | |9+|Latest|Latest|Latest|8+|4+|
|
149 |
|
150 |
|
151 | ## Dependency by version
|
152 |
|
153 | [D3.js](https://d3js.org/) (required)| billboard.js
|
154 | :---: | :---:
|
155 | 4.x ~ 5.x | 1.x ~ 2.x
|
156 | 6.x+ | 3.x+
|
157 |
|
158 | Load billboard.js after D3.js.
|
159 |
|
160 | ```html
|
161 | <!-- 1) Load D3.js and billboard.js separately -->
|
162 | <!-- Load D3: -->
|
163 | <script src="https://d3js.org/d3.v6.min.js"></script>
|
164 |
|
165 | <!-- Load billboard.js with base(or theme) style -->
|
166 | <link rel="stylesheet" href="$YOUR_PATH/billboard.css">
|
167 | <script src="$YOUR_PATH/billboard.js"></script>
|
168 |
|
169 | <!-- 2) or Load billboard.js packaged with D3.js -->
|
170 | <link rel="stylesheet" href="$YOUR_PATH/billboard.css">
|
171 | <script src="$YOUR_PATH/billboard.pkgd.js"></script>
|
172 | ```
|
173 |
|
174 | or use importing ESM.
|
175 |
|
176 | ```js
|
177 | // 1) import billboard.js
|
178 | // as named import with desired shapes and interaction modules
|
179 | // https://github.com/naver/billboard.js/wiki/CHANGELOG-v2#modularization-by-its-functionality
|
180 | import {bb, area, bar, zoom} from "billboard.js";
|
181 |
|
182 | // or as importing default
|
183 | import bb, {area, bar, zoom} from "billboard.js";
|
184 |
|
185 | // 2) import css if your dev-env supports. If don't, include them via <link>
|
186 | import "billboard.js/dist/billboard.css";
|
187 |
|
188 | // or theme style. Find more themes from 'theme' folder
|
189 | import "billboard.js/dist/theme/insight.css"
|
190 | ```
|
191 |
|
192 | > **Note**
|
193 | > - For migration from C3.js, checkout the [migration guide](https://github.com/naver/billboard.js/wiki/How-to-migrate-from-C3.js%3F).
|
194 | > - If has an issue bundling for legacy browsers, checkout "[How to bundle for legacy browsers?](https://github.com/naver/billboard.js/wiki/How-to-bundle-for-legacy-browsers%3F)".
|
195 |
|
196 | ## Basic usage example
|
197 |
|
198 | #### 1) Create chart holder element
|
199 | ```html
|
200 | <div id="chart"></div>
|
201 | ```
|
202 |
|
203 | #### 2) Generate a chart with options
|
204 | ```js
|
205 | // generate the chart
|
206 | var chart = bb.generate({
|
207 | bindto: "#chart",
|
208 | data: {
|
209 | // for ESM import usage, import 'line' module and execute it as
|
210 | // type: line(),
|
211 | type: "line",
|
212 | columns: [
|
213 | ["data1", 30, 200, 100, 400, 150, 250]
|
214 | ]
|
215 | },
|
216 | zoom: {
|
217 | // for ESM import usage, import 'zoom' module and execute it as
|
218 | // enabled: zoom()
|
219 | enabled: true
|
220 | }
|
221 | });
|
222 |
|
223 | // call some API
|
224 | chart.load( ... );
|
225 | ```
|
226 |
|
227 | ## How to start developing billboard.js?
|
228 |
|
229 | For anyone interested in developing billboard.js, follow the instructions below.
|
230 | > Required Node.js version: `10.10.0+`
|
231 |
|
232 | ### Development Environment
|
233 |
|
234 | #### 1. Clone the repository
|
235 |
|
236 | Clone the billboard.js repository and install the dependency modules.
|
237 |
|
238 | ```bash
|
239 | # Create a folder and move.
|
240 | $ mkdir billboard.js && cd billboard.js
|
241 |
|
242 | # Clone the repository.
|
243 | $ git clone https://github.com/naver/billboard.js.git
|
244 | ```
|
245 |
|
246 | #### 2. Install dependencies
|
247 | `npm` and `Yarn` are supported.
|
248 |
|
249 | ```
|
250 | # Install the dependency modules.
|
251 | $ npm install
|
252 |
|
253 | # or
|
254 | $ yarn
|
255 | ```
|
256 |
|
257 | #### 3. Build
|
258 |
|
259 | Use npm script to build billboard.js
|
260 |
|
261 | ```bash
|
262 | # Run webpack-dev-server for development
|
263 | $ npm start
|
264 |
|
265 | # Build
|
266 | $ npm run build
|
267 |
|
268 | # Generate jsdoc
|
269 | $ npm run jsdoc
|
270 | ```
|
271 |
|
272 | Two folders will be created after the build is completed.
|
273 |
|
274 | - **dist** folder: Includes the **billboard.js** and **billboard.min.js** files.
|
275 | - **doc** folder: Includes API documentation. The home page for the documentation is **doc/index.html**.
|
276 |
|
277 | ### Linting
|
278 |
|
279 | To maintain the same code style and quality, we adopted [ESLint](https://eslint.org/). The [rules](https://github.com/naver/eslint-config-naver/tree/master/rules) are based on the [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript) with some modifications.
|
280 | Setup your editor for check or run the below command for linting.
|
281 |
|
282 | ```bash
|
283 | $ npm run lint
|
284 | ```
|
285 |
|
286 | ### Test
|
287 |
|
288 | Once you created a branch and finished the development, you must perform a test with `npm test` command before the push to a remote repository.
|
289 |
|
290 | ```bash
|
291 | $ npm test
|
292 | ```
|
293 | Running the `npm test` command will start [Mocha](https://mochajs.org/) tests via [Karma-runner](https://karma-runner.github.io/).
|
294 |
|
295 | ## Bug Report
|
296 |
|
297 | If you find a bug, please report to us by posting [issues](https://github.com/naver/billboard.js/issues) on GitHub.
|
298 |
|
299 | ## License
|
300 | billboard.js is released under the [MIT license](https://github.com/naver/billboard.js/blob/master/LICENSE).
|
301 |
|
302 | ```
|
303 | Copyright (c) 2017 ~ present NAVER Corp.
|
304 |
|
305 | Permission is hereby granted, free of charge, to any person obtaining a copy
|
306 | of this software and associated documentation files (the "Software"), to deal
|
307 | in the Software without restriction, including without limitation the rights
|
308 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
309 | copies of the Software, and to permit persons to whom the Software is
|
310 | furnished to do so, subject to the following conditions:
|
311 |
|
312 | The above copyright notice and this permission notice shall be included in
|
313 | all copies or substantial portions of the Software.
|
314 |
|
315 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
316 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
317 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
318 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
319 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
320 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
|
321 | THE SOFTWARE.
|
322 | ```
|
323 |
|
324 |
|
325 | [badge-download]: https://img.shields.io/npm/dm/billboard.js.svg?style=flat
|
326 | [badge-jsDelivr]: https://data.jsdelivr.com/v1/package/npm/billboard.js/badge?style=rounded
|
327 | [badge-ci-status]: https://github.com/naver/billboard.js/workflows/CI/badge.svg
|
328 | [badge-coverage]: https://coveralls.io/repos/github/naver/billboard.js/badge.svg
|
329 | [badge-snyk]: https://snyk.io/test/github/naver/billboard.js/badge.svg?targetFile=package.json
|
330 | [badge-gzip-size]: https://img.badgesize.io/https://unpkg.com/billboard.js/dist/billboard.min.js?compression=gzip
|
331 | [badge-latest]: https://img.shields.io/npm/v/billboard.js/latest.svg
|
332 | [badge-next]: https://img.shields.io/npm/v/billboard.js/next.svg
|
333 | [badge-semantic-release]: https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg
|
334 |
|
335 |
|
336 | [link-download]: https://npm-stat.com/charts.html?package=billboard.js&from=2017-06-08
|
337 | [link-jsDelivr]: https://www.jsdelivr.com/package/npm/billboard.js
|
338 | [link-version]: https://www.npmjs.com/package/billboard.js
|
339 | [link-coverage]: https://coveralls.io/github/naver/billboard.js
|
340 | [link-snyk]: https://snyk.io/test/github/naver/billboard.js?targetFile=package.json
|
341 | [link-gzip-size]: https://unpkg.com/billboard.js/dist/billboard.min.js
|
342 | [link-semantic-release]: https://github.com/semantic-release/semantic-release
|
343 |
|
344 | [![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fnaver%2Fbillboard.js.svg?type=large)](https://app.fossa.io/projects/git%2Bgithub.com%2Fnaver%2Fbillboard.js?ref=badge_large)
|