{"id":13701247,"url":"https://github.com/explosion/displacy","last_synced_at":"2025-09-27T02:31:37.928Z","repository":{"id":57212944,"uuid":"69860607","full_name":"explosion/displacy","owner":"explosion","description":":boom: displaCy.js: An open-source NLP visualiser for the modern web","archived":true,"fork":false,"pushed_at":"2018-04-08T21:10:37.000Z","size":131,"stargazers_count":344,"open_issues_count":8,"forks_count":82,"subscribers_count":19,"default_branch":"master","last_synced_at":"2024-05-09T11:28:29.855Z","etag":null,"topics":["css","javascript","natural-language-processing","nlp","spacy","svg","visualization"],"latest_commit_sha":null,"homepage":"https://demos.explosion.ai/displacy","language":"JavaScript","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/explosion.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-10-03T10:21:46.000Z","updated_at":"2024-03-02T14:27:21.000Z","dependencies_parsed_at":"2022-08-24T21:41:49.326Z","dependency_job_id":null,"html_url":"https://github.com/explosion/displacy","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/explosion%2Fdisplacy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/explosion%2Fdisplacy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/explosion%2Fdisplacy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/explosion%2Fdisplacy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/explosion","download_url":"https://codeload.github.com/explosion/displacy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219871850,"owners_count":16554459,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["css","javascript","natural-language-processing","nlp","spacy","svg","visualization"],"created_at":"2024-08-02T20:01:24.246Z","updated_at":"2025-09-27T02:31:32.627Z","avatar_url":"https://github.com/explosion.png","language":"JavaScript","readme":"\u003ca href=\"https://explosion.ai\"\u003e\u003cimg src=\"https://explosion.ai/assets/img/logo.svg\" width=\"125\" height=\"125\" align=\"right\" /\u003e\u003c/a\u003e\n\n# displaCy.js: An open-source NLP visualiser for the modern web\n\n\u003e ⚠️ **As of v2.0.0, the displaCy visualizers are now integrated into\n\u003e the core library. [See here](https://spacy.io/usage/visualizers) for more \n\u003e details on how to visualize a `Doc` object from within spaCy. We're also\n\u003e working on a new suite of tools for serving and testing spaCy models. The\n\u003e code of the standalone visualizers will still be available on GitHub, just\n\u003e not actively maintained.**\n\n[displaCy.js](https://demos.explosion.ai/displacy) is a modern and service-independent visualisation library. We hope this makes it easy to compare different services, and explore your own in-house models. If you're using [spaCy](https://spacy.io)'s syntactic parser, displaCy should be part of your regular workflow. Because spaCy's parser is statistical, it's often hard to predict how it will analyse a given sentence. Using displaCy, you can simply try and see. You can also share the page for discussion with your team, or save the SVG to use elsewhere. If you're developing your own  model, you can run the service yourself — it's 100% open source.\n\nTo read more about displaCy.js, check out the [blog post](https://explosion.ai/blog/displacy-js-nlp-visualizer).\n\n[![npm](https://img.shields.io/npm/v/displacy.svg)](https://www.npmjs.com/package/displacy)\n\n## Run the demo\n\nThis demo is implemented in [Jade (aka Pug)](https://www.jade-lang.org), an extensible templating language that compiles to HTML, and is built or served by [Harp](https://harpjs.com). To serve it locally on [http://localhost:9000](http://localhost:9000), simply run:\n\n```bash\nsudo npm install --global harp\ngit clone https://github.com/explosion/displacy\ncd displacy\nharp server\n```\n\nOr simply install it from npm:\n\n```bash\nnpm install displacy-demo\n```\n\nThe demo is written in ECMAScript 6. For full, cross-browser compatibility, make sure to use a compiler like [Babel](https://github.com/babel/babel). For more info, see this [compatibility table](https://kangax.github.io/compat-table/es6/).\n\n## Using displacy.js\n\nTo use displaCy in your project, download [`displacy.js`](assets/js/displacy.js) from GitHub or via npm:\n\n```bash\nnpm install displacy\n```\n\nThen include the file and initialize a new instance specifying the API and settings:\n\n```javascript\nconst displacy = new displaCy('http://localhost:8000', {\n    container: '#displacy',\n    format: 'spacy',\n    distance: 300,\n    offsetX: 100\n});\n```\n\nOur service that produces the input data is open source, too. You can find it at [spacy-services](https://github.com/explosion/spacy-services).\n\nThe following settings are available:\n\n| Setting | Description | Default |\n| --- | --- | --- |\n| **container** | element to draw displaCy in, can be any query selector | `#displacy` |\n| **format** | format used to generate parse (`'spacy'` or `'google'`) | `'spacy'` |\n| **defaultText** | text used if displaCy is run without text specified | `'Hello World.'` |\n| **defaultModel** | model used if displaCy is run without model specified | `'en'` |\n| **collapsePunct** |  collapse punctuation | `true` |\n| **collapsePhrase** | collapse phrases | `true` |\n| **distance** | distance between words in px | `300` |\n| **offsetX** | spacing on left side of the SVG in px | `50` |\n| **arrowSpacing** | spacing between arrows in px to avoid overlaps | `20` |\n| **arrowWidth** | width of arrow head in px | `10` |\n| **arrowStroke** | width of arc in px | `2` |\n| **wordSpacing** | spacing between words and arcs in px | `50` |\n| **font** | font face for all text | `'inherit'` |\n| **color** | text color, HEX, RGB or color names | `'#000000'` |\n| **bg** | background color, HEX, RGB or color names | `'#ffffff'` |\n| **onStart** | function to be executed on start of server request | `false` |\n| **onSuccess** | callback function to be executed on successful server response | `false` |\n| **onError** | function to be executed if request fails | `false` |\n\n## Visualising a Parse\n\nThe `parse()` method renders a parse generated by spaCy as an SVG in the container.\n\n```javascript\ndisplacy.parse('This is a sentence.', 'en', {\n    collapsePunct: false,\n    collapsePhrase: false,\n    color: '#ffffff',\n    bg: '#000000'\n});\n```\n\nThe visual settings specified here override the global settings. The available settings are **collapsePunct**, **collapsePhrase**, **font**, **color** and **bg**.\n\n\n## Rendering a Parse Manually\n\nAlternatively, you can use `render()` to manually render a JSON-formatted set of arcs and words:\n\n```javascript\nconst parse = {\n    arcs: [\n        { dir: 'right', end: 1, label: 'npadvmod', start: 0 }\n    ],\n    words: [\n        { tag: 'UH', text: 'Hello' },\n        { tag: 'NNP', text: 'World.' }\n    ]\n};\n\ndisplacy.render(parse, {\n    color: '#ff0000'\n});\n```\n\nThe visual settings specified here override the global settings.  The available settings are **font**, **color** and **bg**.\n\n## Converting output from other formats and adding your own\n\nBy default, displaCy expects spaCy's JSON output in the following style:\n\n```json\n{\n    \"arcs\": [\n        { \"dir\": \"left\", \"end\": 4, \"label\": \"nsubj\", \"start\": 0 }\n    ],\n\n    \"words\": [\n        { \"tag\": \"NNS\", \"text\": \"Robots\" }\n    ]\n}\n```\n\nIf `format` is set to `'google'`, the API response is converted from [Google's format](https://cloud.google.com/natural-language/docs/basics#syntactic_analysis_responses). To add your own conversion rules, add a new case to `handleConversion()`:\n\n```javascript\nhandleConversion(parse) {\n    switch(this.format) {\n        case 'spacy': return parse; break;\n        case 'google': return({ words: ..., arcs: ... }); break;\n        case 'your_format': return({ words: ..., arcs: ... }); break;\n        default: return parse;\n    }\n}\n```\n\nYou can now initialize displaCy with `format: 'your_format'`.\n\n## Changing the theme and colours\n\nYou can find the current theme settings in [`/assets/css/_displacy-theme.sass`](assets/css/_displacy-theme.sass). All elements contained in the SVG output come with tags and data attributes and can be styled flexibly using CSS. By default, the `currentColor` of the element is used for colouring, meaning only need to change the `color` property in CSS.\n\nThe following classes are available:\n\n| Class name | Description |\n| --- | --- |\n| **.displacy-word** | word text\n| **.displacy-tag** | POS tag\n| **.displacy-token** | container of word and POS tag\n| **.displacy-arc** | arrow arc (without label or arrow head)\n| **.displacy-label** | relation type (arrow label)\n| **.displacy-arrowhead** | arrow head\n| **.displacy-arrow** | container of arc, label and arrow head\n\nAdditionally, you can use these attributes as attribute selectors:\n\n| Attribute | Value | On Element |\n| --- | --- | --- |\n| **data-tag** | POS tag value | `.displacy-token`, `.displacy-word`, `.displacy-tag` |\n| **data-label** | relation type value | `.displacy-arrow`, `.displacy-arc`, `.displacy-arrowhead`, `.displacy-label` |\n| **data-dir** | direction of arrow | `.displacy-arrow`, `.displacy-arc`, `.displacy-arrowhead`, `.displacy-label` |\n\nUsing a combination of those selectors and some basic CSS logic, you can create pretty powerful templates to style the elements based on their role and function in the parse. Here are a few examples:\n\n```css\n/* Format all words in 12px Helvetica and grey */\n\n.displacy-word {\n    font: 12px Helvetica, Arial, sans-serif;\n    color: grey;\n}\n\n\n/* Make all noun phrases (tags that start with \"NN\") green */\n\n.displacy-tag[data-tag^=\"NN\"] {\n    color: green;\n}\n\n\n/* Make all right arrows red and hide their labels */\n\n.displacy-arc[data-dir=\"right\"],\n.displacy-arrowhead[data-dir=\"right\"] {\n    color: red;\n}\n\n.displacy-label[data-dir=\"right\"] {\n    display: none;\n}\n\n\n/* Hide all tags for verbs (tags that start with \"VB\") that are NOT the base form (\"VB\") */\n\n.displacy-tag[data-tag^=\"VB\"]:not([data-tag=\"VB\"]) {\n    display: none;\n}\n\n\n/* Only display tags if word is hovered (with smooth transition) */\n\n.displacy-tag {\n    opacity: 0;\n    transition: opacity 0.25s ease;\n}\n\n.displacy-word:hover + .displacy-tag {\n    opacity: 1;\n}\n```\n\n## Adding custom data attributes\n\ndisplaCy lets you define custom attributes via the JSON representation of the parse on both `words` and `arcs`:\n\n```json\n\"words\": [\n    {\n        \"tag\": \"NNS\",\n        \"text\": \"Robots\",\n        \"data\": [\n            [ \"custom\", \"your value here\" ],\n            [ \"example\", \"example text here\" ]\n        ]\n    }\n]\n```\n\nCustom attributes are added as data attributes prefixed with `data-`, so their names shouldn't contain spaces or special characters. If added to `words`, the data attributes are attached to the token (`.displacy-token`), if added to `arcs`, they're attached to the arrow (`.displacy-arrow`):\n\n```html\n\u003ctext class=\"displacy-token\" data-custom=\"your value here\" data-example=\"example text here\"\u003e...\u003c/text\u003e\n```\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexplosion%2Fdisplacy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fexplosion%2Fdisplacy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexplosion%2Fdisplacy/lists"}