README.md
1# ipywidgets: Interactive HTML Widgets
2
3[](https://pypi.python.org/pypi/ipywidgets)
4[](https://travis-ci.org/jupyter-widgets/ipywidgets)
5[](https://ipywidgets.readthedocs.io/en/latest/?badge=latest)
6[](https://gitter.im/jupyter-widgets/Lobby)
7[](https://mybinder.org/v2/gh/jupyter-widgets/ipywidgets/master?filepath=docs%2Fsource%2Fexamples)
8
9ipywidgets are [interactive HTML widgets](https://github.com/jupyter-widgets/ipywidgets/blob/master/docs/source/examples/Index.ipynb)
10for Jupyter notebooks and the IPython kernel.
11
12Notebooks come alive when interactive widgets are used. Users gain control of
13their data and can visualize changes in the data.
14
15Learning becomes an immersive, plus fun, experience. Researchers can easily see
16how changing inputs to a model impact the results. We hope you will add
17ipywidgets to your notebooks, and we're here to help you get started.
18
19## Core Interactive Widgets
20
21A [demonstration notebook](https://github.com/jupyter-widgets/ipywidgets/blob/master/docs/source/examples/Index.ipynb) provides an overview of the core interactive widgets, including:
22
23- sliders
24- progress bars
25- text boxes
26- toggle buttons and checkboxes
27- display areas
28- and more
29
30## Jupyter Interactive Widgets as a Framework
31
32Besides the widgets already provided with the library, the framework can be
33extended with custom widget libraries.
34
35A template project is available in the form of a cookie cutter [here](https://github.com/jupyter-widgets/widget-ts-cookiecutter).
36
37This project is meant to help custom widget authors get started with the
38packaging and the distribution of Jupyter interactive widgets.
39
40It produces a project for a Jupyter interactive widget library following the
41current best practices for using interactive widgets. An implementation for a
42placeholder "Hello World" widget is provided.
43
44Popular widget libraries such as
45[bqplot](https://github.com/bloomberg/bqplot),
46[pythreejs](https://github.com/jovyan/pythreejs) and
47[ipyleaflet](https://github.com/ellisonbg/ipyleaflet)
48
49follow exactly the same template and directory structure. They can serve as
50more advanced examples of usage of the Jupyter widget infrastructure.
51
52For detailed information, please refer to the [ipywidgets documentation](https://ipywidgets.readthedocs.io/en/latest/).
53
54## More advanced examples
55
56Examples of custom widget libraries built upon ipywidgets are
57
58- [bqplot](https://github.com/bloomberg/bqplot) a 2d data visualization library
59 enabling custom user interactions.
60- [pythreejs](https://github.com/jovyan/pythreejs) a Jupyter - Three.js wrapper,
61 bringing Three.js to the notebook.
62- [ipyleaflet](https://github.com/ellisonbg/ipyleaflet) a leaflet widget for Jupyter.
63
64## Install
65
66Install the current version of ipywidgets using pip or conda.
67
68- With pip:
69
70```
71pip install ipywidgets
72jupyter nbextension enable --py --sys-prefix widgetsnbextension # can be skipped for notebook version 5.3 and above
73```
74
75- With conda:
76
77```
78conda install -c conda-forge ipywidgets
79```
80
81See the [Installation](docs/source/user_install.md) section of the documentation for additional details.
82
83### Installing from git
84
85If you want to install ipywidgets from git, **you will need the
86[yarn](https://yarnpkg.com/) package manager version 1.2.1 or later**.
87Installing from git is more complicated and requires a developer install, see the [developer install](docs/source/dev_install.md) instructions.
88
89To install the latest master version from the root directory of the source
90code, run ``dev-install.sh``. To only build the Python package enter ``pip install -e .``.
91
92#### Compatibility
93
94| ipywidgets version | Required notebook version |
95| ------------------- | ------------------------- |
96| master | 4.4 |
97| 5.x | 4.2 |
98| 4.1.x | 4.1 |
99| 4.0.x | 4.0 |
100
101[Change log](docs/source/changelog.md)
102
103## Usage
104
105See the [examples](docs/source/examples.md) section of the documentation. The widgets are being used in a variety of ways; some uses can be seen in these notebooks:
106
107- [Demo notebook of interactive widgets](https://github.com/jupyter-widgets/ipywidgets/blob/master/docs/source/examples/Index.ipynb)
108
109## Contributing to ipywidgets
110
111- [Developer information](CONTRIBUTING.md)
112
113## License
114
115We use a shared copyright model that enables all contributors to maintain the
116copyright on their contributions.
117
118See the [LICENSE](LICENSE) file in this repository for details.
119
120## Project Jupyter resources
121
122- [Project Jupyter website](https://jupyter.org)
123- [Online Demo of Jupyter Notebook at try.jupyter.org](https://try.jupyter.org)
124- [Documentation for Project Jupyter](https://jupyter.readthedocs.io/en/latest/index.html) [[PDF](https://media.readthedocs.org/pdf/jupyter/latest/jupyter.pdf)]
125- [](https://groups.google.com/forum/#!forum/jupyter)
126
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}