diff --git a/README.md b/README.md
index d46dc2b94..a957c24c6 100644
--- a/README.md
+++ b/README.md
@@ -11,12 +11,14 @@ This is a [monorepo](https://github.com/lerna/lerna#what-does-a-lerna-repo-look-
 | [geojson-extension](packages/geojson-extension) | `application/geo+json` | `.geojson`, `.geo.json` |
 | [json-extension](packages/json-extension) | `application/json` | `.json`, `.ipynb` |
 | [plotly-extension](packages/plotly-extension) | `application/vnd.plotly.v1+json` | `.plotly`, `.plotly.json` |
+| [vdom-extension](packages/vdom-extension) | `application/vdom.v1+json` | `.vdom`, `.vdom.json` |
 
 ## Install
 
 * geojson-extension: `jupyter labextension install @jupyterlab/geojson-extension`
 * json-extension: `jupyter labextension install @jupyterlab/json-extension`
 * plotly-extension: `jupyter labextension install @jupyterlab/plotly-extension`
+* vdom-extension: `jupyter labextension install @jupyterlab/vdom-extension`
 
 ## Contributing
 
diff --git a/packages/vdom-extension/README.md b/packages/vdom-extension/README.md
new file mode 100644
index 000000000..96b81fd19
--- /dev/null
+++ b/packages/vdom-extension/README.md
@@ -0,0 +1,104 @@
+# vdom-extension
+
+A JupyterLab extension for rendering VirtualDOM using React
+
+![demo](http://g.recordit.co/EIwAIBsGBh.gif)
+
+## Prerequisites
+
+* JupyterLab ^0.27.0
+
+## Usage
+
+To render VDOM output in IPython:
+
+```python
+from IPython.display import display
+
+def VDOM(data={}):
+    bundle = {}
+    bundle['application/vdom.v1+json'] = data
+    display(bundle, raw=True)
+
+VDOM({
+    'tagName': 'div',
+    'attributes': {},
+    'children': [{
+        'tagName': 'h1',
+        'attributes': {},
+        'children': 'Our Incredibly Declarative Example',
+        'key': 0
+    }, {
+        'tagName': 'p',
+        'attributes': {},
+        'children': ['Can you believe we wrote this ', {
+            'tagName': 'b',
+            'attributes': {},
+            'children': 'in Python',
+            'key': 1
+        }, '?'],
+        'key': 1
+    }, {
+        'tagName': 'img',
+        'attributes': {
+            'src': 'https://media.giphy.com/media/xUPGcguWZHRC2HyBRS/giphy.gif'
+        },
+        'key': 2
+    }, {
+        'tagName': 'p',
+        'attributes': {},
+        'children': ['What will ', {
+            'tagName': 'b',
+            'attributes': {},
+            'children': 'you',
+            'key': 1
+        }, ' create next?'],
+        'key': 3
+    }]
+})
+```
+
+Using the [vdom Python library](https://github.com/nteract/vdom):
+
+```python
+from vdom import h1, p, img, div, b
+
+div([
+    h1('Our Incredibly Declarative Example'),
+    p(['Can you believe we wrote this ', b('in Python'), '?']),
+    img(src="https://media.giphy.com/media/xUPGcguWZHRC2HyBRS/giphy.gif"),
+    p(['What will ', b('you'), ' create next?']),
+])
+```
+
+To render a `.vdom` or `.vdom.json` file as a tree, simply open it:
+
+## Install
+
+```bash
+jupyter labextension install @jupyterlab/vdom-extension
+```
+
+## Development
+
+```bash
+# Clone the repo to your local environment
+git clone https://github.com/jupyterlab/jupyter-renderers.git
+cd jupyter-renderers
+# Install dependencies
+npm install
+# Build Typescript source
+npm run build
+# Link your development version of the extension with JupyterLab
+jupyter labextension link packages/vdom-extension
+# Rebuild Typescript source after making changes
+npm run build
+# Rebuild JupyterLab after making any changes
+jupyter lab build
+```
+
+## Uninstall
+
+```bash
+jupyter labextension uninstall @jupyterlab/vdom-extension
+```