{"$schema":"https://echarts.apache.org/doc/json-schem","option":{"type":"Object","properties":{"Get Started with ECharts in 5 minutes":{"type":["*"],"description":"<h2 id=\"installing-echarts\">Installing ECharts</h2>\n<p>First, install Apache ECharts<sup>TM</sup> using one of the following methods:</p>\n<ul>\n<li><p>Download official source release from <a href=\"https://echarts.apache.org/en/download.html\" target=\"_blank\">Apache ECharts website</a>. Then <a href=\"https://github.com/apache/echarts#build\" target=\"_blank\">build</a> from the source release.</p>\n</li>\n<li><p>Download from <a href=\"https://github.com/apache/echarts/releases\" target=\"_blank\">GitHub</a></p>\n</li>\n<li><p>Using npm: <code class=\"codespan\">npm install echarts --save</code>. <a href=\"tutorial.html#Use%20ECharts%20with%20webpack\" target=\"_blank\">Using ECharts with webpack</a></p>\n</li>\n<li><p>Use CDN like <a href=\"https://www.jsdelivr.com/package/npm/echarts\" target=\"_blank\">jsDelivr</a>.</p>\n</li>\n</ul>\n<h2 id=\"including-echarts\">Including ECharts</h2>\n<p>Load <code class=\"codespan\">echarts.min.js</code> with a script tag.</p>\n<pre><code class=\"lang-html\">&lt;!DOCTYPE html&gt;\n&lt;html&gt;\n&lt;head&gt;\n    &lt;meta charset=&quot;utf-8&quot;&gt;\n    &lt;!-- including ECharts file --&gt;\n    &lt;script src=&quot;echarts.min.js&quot;&gt;&lt;/script&gt;\n&lt;/head&gt;\n&lt;/html&gt;\n</code></pre>\n<h2 id=\"draw-a-simple-chart\">Draw a simple chart</h2>\n<p>Before drawing charts, we need to prepare a DOM container with width and height for ECharts.</p>\n<pre><code>&lt;body&gt;\n    &lt;!-- preparing a DOM with width and height for ECharts --&gt;\n    &lt;div id=&quot;main&quot; style=&quot;width:600px; height:400px;&quot;&gt;&lt;/div&gt;\n&lt;/body&gt;\n</code></pre><p>Then we can initialize an ECharts instance using <a href=\"api.html#echarts.init\" target=\"_blank\">echarts.init</a>, and create a simple bar chart with <a href=\"api.html#echartsInstance.setOption\" target=\"_blank\">setOption</a>. Below is the complete code.</p>\n<pre><code class=\"lang-html\">&lt;!DOCTYPE html&gt;\n&lt;html&gt;\n&lt;head&gt;\n    &lt;meta charset=&quot;utf-8&quot;&gt;\n    &lt;title&gt;ECharts&lt;/title&gt;\n    &lt;!-- including ECharts file --&gt;\n    &lt;script src=&quot;echarts.js&quot;&gt;&lt;/script&gt;\n&lt;/head&gt;\n&lt;body&gt;\n    &lt;!-- prepare a DOM container with width and height --&gt;\n    &lt;div id=&quot;main&quot; style=&quot;width: 600px;height:400px;&quot;&gt;&lt;/div&gt;\n    &lt;script type=&quot;text/javascript&quot;&gt;\n        // based on prepared DOM, initialize echarts instance\n        var myChart = echarts.init(document.getElementById(&#39;main&#39;));\n\n        // specify chart configuration item and data\n        var option = {\n            title: {\n                text: &#39;ECharts entry example&#39;\n            },\n            tooltip: {},\n            legend: {\n                data:[&#39;Sales&#39;]\n            },\n            xAxis: {\n                data: [&quot;shirt&quot;,&quot;cardign&quot;,&quot;chiffon shirt&quot;,&quot;pants&quot;,&quot;heels&quot;,&quot;socks&quot;]\n            },\n            yAxis: {},\n            series: [{\n                name: &#39;Sales&#39;,\n                type: &#39;bar&#39;,\n                data: [5, 20, 36, 10, 10, 20]\n            }]\n        };\n\n        // use configuration item and data specified to show chart\n        myChart.setOption(option);\n    &lt;/script&gt;\n&lt;/body&gt;\n&lt;/html&gt;\n</code></pre>\n<p>You&#39;ve made your first chart!</p>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=doc-example/getting-started&reset=1&edit=1\" width=\"600\" height=\"300\" ></iframe>\n\n\n<p>For more examples, go to the <a href=\"https://echarts.apache.org/examples/en/editor.html?c=doc-example/getting-started\" target=\"_blank\">ECharts Gallery</a></p>\n"},"New features in ECharts 5":{"type":["*"],"description":"<p>Data visualization has come a long way in the last few years. Developers no longer expect visualization products to be simple chart creation tools, but have more advanced needs in terms of interaction, performance, data processing, and more.</p>\n<p>Apache ECharts has always been committed to making it easier for developers to create flexible and rich visualizations. In the latest release of Apache ECharts 5, we have focused on enhancing the storytelling of charts, allowing developers to tell the story behind the data in a simpler way.</p>\n<p><img src=\"documents/asset/img/feature-v5/echarts-5-en.png\" width=\"800px\" /></p>\n<p>&quot;The core of Apache ECharts 5 is &quot;Show, do not tell&quot;, which is a comprehensive upgrade of five topics and 15 features around the stroy telling of visualizations, allowing charts to better tell the story behind the data. It helps developers to create visualizations that meet the needs of various scenarios more easily.</p>\n<h2 id=\"storytelling\">Storytelling</h2>\n<p>The importance of animation to human cognition cannot be overstated. In our previous work, we used initialization animations and transition animations to help users understand the connection between data transformations, making the appearance of charts and transformations seem less rigid. This time, we have even enhanced our animation capabilities, even more significantly. We hope to further exploit the role of animation to help users&#39; cognition, and help them understand the story behind the chart more easily with the dynamic stroy function of the chart.</p>\n<h4 id=\"bar-line-racing\">Bar/Line Racing</h4>\n<p>Apache ECharts 5 adds support for dynamically sorted bar-racing and dynamically sorted line-racing charts to help developers easily create time-series charts that show changes in data over time and tell the evolution of data.</p>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=bar-race-country&edit=1&reset=1\" width=\"700\" height=\"400\" ></iframe>\n\n\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=line-race&edit=1&reset=1\" width=\"700\" height=\"400\" ></iframe>\n\n\n<p>The dynamic sorting chart shows the derivation of different categories in the ranking over time. The developer can enable this effect in ECharts with a few simple configuration code.</p>\n<h4 id=\"custom-series-animation\">Custom Series Animation</h4>\n<p>In addition to dynamic sorting charts, Apache ECharts 5 provides even richer and more powerful animations in the custom series, supporting interpolation animations for label value text, transition animations for morph, combine, separate, and other effects of graphics.</p>\n<p>Imagine what amazing visualizations you can create with these dynamic effects!</p>\n<h2 id=\"visual-design\">Visual Design</h2>\n<p>The role of visual design is not only to make the chart look better, but more importantly, a design that conforms to the principles of visualization can help users understand more quickly what the chart is trying to say and eliminate as much misunderstanding as possible from poor design.</p>\n<h4 id=\"overall-design\">Overall Design</h4>\n<p>We have found that a large percentage of developers use the default theme style for ECharts, so it is important to have an elegant default theme design. In Apache ECharts 5, we redesigned the default theme style, optimizing it for different charts and components. For example, we took into account factors such as differentiation between colors, contrast with background colors, and harmony with adjacent colors, and ensured that people with color blindness could clearly distinguish data.</p>\n<p><img src=\"documents/asset/img/feature-v5/theme-color.png\" width=\"400px\" /></p>\n<p>Let&#39;s look at the new version of the light and dark theme styles using the most commonly used bar chart as an example.</p>\n<p><img src=\"documents/asset/img/feature-v5/new-theme-light.png\" width=\"500px\" />\n<img src=\"documents/asset/img/feature-v5/new-theme-dark.png\" width=\"500px\" /></p>\n<p>For the data area zoom, timeline and other interactive components, we also designed a new style and provide a better interactive experience: &lt;img src=&quot;documents/asset/img/feature/v5/new-theme-dark.png</p>\n<p><img src=\"documents/asset/img/feature-v5/dataZoom.png\" width=\"500px\" /></p>\n<p><img src=\"documents/asset/img/feature-v5/timeline.png\" width=\"500px\" /></p>\n<h4 id=\"label\">Label</h4>\n<p>Labels are one of the core elements of a chart, and clear and unambiguous labels help users to have a more accurate understanding of the data. Apache ECharts 5 provides a variety of new labeling features that allow dense labels to be clearly displayed and accurately represented.</p>\n<p>Apache ECharts 5 can be enabled to automatically hide overlapping labels through a configuration item. For labels that exceed the display area, you can choose to automatically truncate or line break them. Dense pie chart labels now have a more aesthetically pleasing automatic layout.</p>\n<p>These features can help avoid text that is too dense and affects readability. And, no additional code needs to be written by the developer for them to take effect by default, greatly simplifying the development cost for developers.</p>\n<p>We also provide several configuration options to allow developers to actively control the layout strategy of tabs, such as tab dragging, overall display at the edge of the canvas, connecting with guide lines and graphical elements, and still linking to highlight the associated relationships.</p>\n<p>The new label feature allows you to have very clear label presentation even in a confined space mobile:</p>\n<p><img src=\"documents/asset/img/feature-v5/pie-label.png\" height=\"150px\" />\n<img src=\"documents/asset/img/feature-v5/pie-label-2.png\" height=\"150px\" /></p>\n<h4 id=\"time-axis\">Time Axis</h4>\n<p>Apache ECharts 5 brings a time axis suitable for expressing timestamp scales. The default design of the time axis highlights important information more prominently and provides more flexible customization capabilities, allowing developers to tailor the time axis&#39;s label content to different needs.</p>\n<p>First of all, the time axis is no longer split absolutely evenly as before, but instead selects more meaningful points like year, month, day, and whole point to display, and can show different levels of scales at the same time. The <code class=\"codespan\">formatter</code> of labels supports templates for time (e.g. <code class=\"codespan\">{yyyy}-{MM}-{dd}</code>), and different <code class=\"codespan\">formatter</code> can be specified for labels with different time granularity, which can be combined with rich text labels to create eye-catching and diverse time effects.</p>\n<p>The display of the time scale at different dataZoom granularities.</p>\n<p><img src=\"documents/asset/img/feature-v5/time-axis.png\" width=\"600px\" /></p>\n<p><img src=\"documents/asset/img/feature-v5/time-axis-2.png\" width=\"600px\" /></p>\n<h4 id=\"tooltip\">Tooltip</h4>\n<p>Tooltip is one of the most commonly used visualization components to help users interactively understand the details of data. In Apache ECharts 5, we have optimized the style of the tooltip, making the default display of the tooltip elegant and clear by adjusting the font style, color, arrow pointing to the graph, border color following the graph color, and other features. The rendering logic of rich text has been improved to ensure that the display is consistent with the HTML way, allowing users to choose different technical solutions to achieve the same effect in different scenarios.</p>\n<p><img src=\"documents/asset/img/feature-v5/new-tooltip.png\" height=\"200px\" />\n<img src=\"documents/asset/img/feature-v5/new-tooltip-2.png\" height=\"200px\" /></p>\n<p>In addition to this, we have also added the ability to sort the list in the tip box by value size or category order this time.</p>\n<h4 id=\"gauge\">Gauge</h4>\n<p>We have seen a lot of cool gauge charts created by community users, but the way they are configured is often complex and tricky. Therefore, we have upgraded the gauge to support image or vector path drawing pointers, anchor configurations, progress bars, rounded corner effects, and more.</p>\n<p>Different styles of gauge pointers.</p>\n<p><img src=\"documents/asset/img/feature-v5/gauge-pointer.png\" width=\"600px\" /></p>\n<p>These upgrades not only allow developers to achieve cool effects with simpler configuration items, but also bring richer customization capabilities.</p>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=gauge-clock&edit=1&reset=1\" width=\"600\" height=\"600\" ></iframe>\n\n\n<h4 id=\"round-corner\">Round Corner</h4>\n<p>Apache ECharts 5 supports round corner for pie charts, sunburst charts, and treemap charts. Don&#39;t underestimate the simplicity of the rounded corners configuration, but combine them with other effects to create a more personalized visualization.</p>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=sunburst-borderRadius&edit=1&reset=1\" width=\"400\" height=\"400\" ></iframe>\n\n\n\n<h2 id=\"interactivity\">Interactivity</h2>\n<p>The interactivity of the visualization helps users explore the work and deepen their understanding of the main idea of the diagram.</p>\n<h4 id=\"multi-state\">Multi-State</h4>\n<p>In ECharts 4, there were two interactive states, <code class=\"codespan\">emphasis</code> and <code class=\"codespan\">normal</code>, graph will enter the <code class=\"codespan\">emphasis</code> state when the mouse hovered to distinguish the data.</p>\n<p>This time in Apache ECharts 5, we have added a new effect of <strong>blur</strong> other non-related elements to the original mouse hover highlighting, so that the target data can be focused.</p>\n<p>For example, in this <a href=\"https://echarts.apache.org/examples/zh/editor.html?c=bar-y-category-stack\" target=\"_blank\">bar chart</a> example, when the mouse hovers over a series, other non-related series will fade out, thus highlighting more clearly the comparison of data in the focused series. of data in the comparison. On diagrams with more complex data structures such as relationship, tree, sunburst, sankey, etc., it is also possible to see the connections between data by fading out non-related elements. Also, colors, shadows, and other styles that can be set in <code class=\"codespan\">emphasis</code> can now be set in <code class=\"codespan\">blur</code>.</p>\n<p>In addition, we&#39;ve added <strong>click to select</strong> to all series, an interaction that was previously only available in a few series such as pie charts and maps, allowing developers to set it to single or multiple selection mode, and to listen to the <code class=\"codespan\">selectchanged</code> event to get all the selected shapes for further processing. As with <code class=\"codespan\">emphasis</code> and <code class=\"codespan\">blur</code>, the selection style can also be configured in <code class=\"codespan\">select</code>.</p>\n<h4 id=\"performance-improvements\">Performance improvements</h4>\n<h5 id=\"dirty-rectangle-rendering\">Dirty Rectangle Rendering</h5>\n<p>Apache ECharts 5 has new support for dirty rectangle rendering to address performance bottlenecks in large scenes with only local changes. When using the Canvas renderer, the dirty rectangle rendering technique detects and updates only the parts of the view that have changed, rather than any changes causing a complete redraw of the canvas. This can help improve rendering frame rates in some special scenarios, such as scenes where the mouse frequently triggers some graphical highlighting many times. In the past for such scenes, additional Canvas layers were used to optimize performance, but this approach is not universal for all scenes and does not work well for complex styles. Dirty Rectangle rendering does a good job of satisfying both performance and display correctness.</p>\n<p>A visual demonstration of a dirty rectangle, with the red boxed area redrawn for the frame.</p>\n<p><img src=\"documents/asset/img/feature-v5/dirty-rect.gif\" width=\"500px\" /></p>\n<p>You can see the effect by enable dirty rectangle optimization on the new example page.</p>\n<h5 id=\"line-chart-performance-optimization-for-real-time-time-series-data\">Line Chart Performance Optimization for Real-Time Time-Series Data</h5>\n<p>In addition, the performance of line graphs with large amounts of data has also seen a significant performance improvement. We often encounter the need for high-performance plotting of large amounts of real-time time-series data, which will be updated every hundreds or tens of milliseconds.</p>\n<p>Apache ECharts 5 deeply optimizes CPU consumption, memory usage, and initialization time in these scenarios, enabling real-time updates (less than 30ms per update) for millions of data, and even rendering within 1s for ten millions of data, with low memory usage and smooth tooltip interactions.</p>\n<h2 id=\"development-experience\">Development Experience</h2>\n<p>We want such a powerful visualization tool to be used by more developers in a simpler way, so the developer experience is also a very important aspect for us.</p>\n<h4 id=\"datasets\">Datasets</h4>\n<p>ECharts 5 enhances the data transformation capabilities of datasets, allowing developers to implement common data processing such as filtering, sorting, aggregating, histogram, simple clustering, regression, etc. in a simple way. Developers can use these functions in a uniform and declarative way, and can easily implement common data operations.</p>\n<h4 id=\"internationalization\">Internationalization</h4>\n<p>The original internationalization implementation of ECharts takes the form of different distribution files packaged according to different language parameters. In this way, the dynamic language and main code are bound together, and the only way to switch languages when using ECharts is to reload different language versions of ECharts distributions.</p>\n<p>Therefore, starting with Apache ECharts 5, the dynamic language is separated from the main code. To switch languages, you only need to load the corresponding language, use the <code class=\"codespan\">registerLocale</code> function to mount the language object in a similar way to mount the theme, and then reinitialize it to complete the language switch.</p>\n<pre><code class=\"lang-js\">// import the lang object and set when init\necharts.registerLocale(&#39;DE&#39;, lang).\necharts.init(DomElement, null, {\n   locale: &#39;DE&#39;\n});\n</code></pre>\n<h4 id=\"typescript-refactoring\">TypeScript Refactoring</h4>\n<p>In order to continue to refactor and develop new features more safely and efficiently, we started the development of Apache ECharts 5 by rewriting the code using TypeScript. The strong typing brought by TypeScript gave us the confidence to refactor the code drastically to achieve more exciting features during the development of ECharts 5.</p>\n<p>For developers, we can also generate better and more code-compliant <code class=\"codespan\">DTS</code> type description files directly from TypeScript code. Until now, ECharts type description files have been maintained by community developers and published to <a href=\"https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/echarts\" target=\"_blank\">DefinityTyped</a>, which is a lot of work, so thanks for your contribution.</p>\n<p>In addition, if a developer&#39;s component is introduced on-demand, we provide a <code class=\"codespan\">ComposeOption</code> type method that can combine a configuration item type that contains only the introduced components, which can bring stricter type checking and help you detect unintroduced component types in advance.</p>\n<h2 id=\"accessibility\">Accessibility</h2>\n<p>Apache ECharts has always taken accessibility design seriously, and we want to make the information conveyed by charts equally to be accessed. We also want to make this possible for chart developers at a very low development cost, thus making developers more willing to support the accessibility.</p>\n<p>In the last major release, we supported automatic intelligent generation of chart descriptions based on different chart types and data, making it very easy for developers to support DOM description information for charts. In ECharts 5, we have also made more accessibility improvements to help people with visual impairments better understand the chart content.</p>\n<h4 id=\"theme-colors\">Theme Colors</h4>\n<p>We took accessibility into account when designing the new default theme, and we repeatedly tested the brightness and color values of the colors to help accessibility users clearly identify the chart data.</p>\n<p>Moreover, for developers with further accessibility needs, we also provide special high-contrast themes to further differentiate the data with higher contrast colors.</p>\n<h4 id=\"decal-patterns\">Decal Patterns</h4>\n<p>ECharts 5 also provides a new feature of decals to help users further differentiate data by using patterns to assist with color representation.</p>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=doc-example/aria-decal-simple&edit=1&reset=1\" width=\"600\" height=\"350\" ></iframe>\n\n\n<p>In addition, decal patterns can also help in some other scenarios, such as: helping to better distinguish data in printed materials like newspapers and books that have only a single color or very few colors; using graphical elements to facilitate a more intuitive understanding of the data by the user.</p>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=doc-example/aria-decal-newspaper&edit=1&reset=1\" width=\"600\" height=\"350\" ></iframe>\n\n\n\n\n<h2 id=\"summary\">Summary</h2>\n<p>In addition to the features described above, Apache ECharts has been improved in a very large number of details to help developers more easily create charts that good by default, are flexible in configuration, and tell the story behind the data with charts.</p>\n<p>Thank you to all the developers who have used ECharts, and even participated in community contributions, for making Apache ECharts 5 possible. We&#39;ll be working on future developments with even more enthusiasm, and we&#39;ll see you all in 6 with even more enthusiasm!</p>\n"},"ECharts 5 Upgrade Guide":{"type":["*"],"description":"<p>This guide is for those who want to upgrade from echarts 4.x (hereafter <code class=\"codespan\">v4</code>) to echarts 5.x (hereafter <code class=\"codespan\">v5</code>). You can find out what new features <code class=\"codespan\">v5</code> brings that are worth upgrading in <a href=\"tutorial.html#ECharts%205%20Upgrade%20Guide\" target=\"_blank\">New Features in ECharts 5</a>. In most cases, developers won&#39;t need to do anything extra for this upgrade, as echarts has always tried to keep the API as stable and backward-compatible as possible. However, <code class=\"codespan\">v5</code> still brings some breaking changes that require special attention. In addition, in some cases, <code class=\"codespan\">v5</code> provides a better API to replace the previous one, and these superseded APIs will no longer be recommended (though we have tried to be as compatible as possible with these changes). We&#39;ll try to explain these changes in detail in this document.</p>\n<p>Since we added the new <a href=\"tutorial.html#Use%20ECharts%20with%20bundler%20and%20NPM\" target=\"_blank\">tree-shaking API</a> in <code class=\"codespan\">v5.0.1</code>, this documentation is based on <code class=\"codespan\">v5.0.1</code> or higher.</p>\n<h2 id=\"breaking-changes\">Breaking Changes</h2>\n<h4 id=\"default-theme\">Default theme</h4>\n<p>First of all, the default theme has been changed. <code class=\"codespan\">v5</code> has made a lot of changes and optimizations on the theme design. If you still want to keep the colors of the old version, you can manually declare the colors as follows.</p>\n<pre><code class=\"lang-js\">chart.setOption({\n    color: [\n        &#39;#c23531&#39;, &#39;#2f4554&#39;, &#39;#61a0a8&#39;, &#39;#d48265&#39;, &#39;#91c7ae&#39;, &#39;#749f83&#39;,\n        &#39;#ca8622&#39;, &#39;#bda29a&#39;, &#39;#6e7074&#39;, &#39;#546570&#39;, &#39;#c4ccd3&#39;\n    ],\n    // ...\n});\n</code></pre>\n<p>Or, to make a simple <code class=\"codespan\">v4</code> theme.</p>\n<pre><code class=\"lang-js\">var themeEC4 = {\n    color: [\n        &#39;#c23531&#39;, &#39;#2f4554&#39;, &#39;#61a0a8&#39;, &#39;#d48265&#39;, &#39;#91c7ae&#39;, &#39;#749f83&#39;,\n        &#39;#ca8622&#39;, &#39;#bda29a&#39;, &#39;#6e7074&#39;, &#39;#546570&#39;, &#39;#c4ccd3&#39;\n    ]\n};\nvar chart = echarts.init(dom, themeEC4);\nchart.setOption(/* ... */);\n</code></pre>\n<h4 id=\"importing-echarts\">Importing ECharts</h4>\n<h5 id=\"removing-support-for-default-exports\">Removing support for default exports</h5>\n<p>Since <code class=\"codespan\">v5</code>, echarts only provides <code class=\"codespan\">named exports</code>.</p>\n<p>So if you are importing <code class=\"codespan\">echarts</code> like this:</p>\n<pre><code class=\"lang-js\">import echarts from &#39;echarts&#39;;\n// Or import core module\nimport echarts from &#39;echarts/lib/echarts&#39;;\n</code></pre>\n<p>It will throw error in <code class=\"codespan\">v5</code>. You need to change the code as follows to import the entire module.</p>\n<pre><code class=\"lang-js\">import * as echarts from &#39;echarts&#39;;\n// Or\nimport * as echarts from &#39;echarts/lib/echarts&#39;;\n</code></pre>\n<h5 id=\"tree-shaking-api\">tree-shaking API</h5>\n<p>In 5.0.1, we introduced the new <a href=\"tutorial.html#Use%20ECharts%20with%20bundler%20and%20NPM\" target=\"_blank\">tree-shaking API</a></p>\n<pre><code class=\"lang-js\">import * as echarts from &#39;echarts/core&#39;;\nimport { BarChart } from &#39;echarts/charts&#39;;\nimport { GridComponent } from &#39;echarts/components&#39;;\n// Note that the Canvas renderer is no longer included by default and needs to be imported explictly, or import the SVGRenderer if you need to use the SVG rendering mode\nimport { CanvasRenderer } from &#39;echarts/renderers&#39;;\n\necharts.use([BarChart, GridComponent, CanvasRenderer]);\n</code></pre>\n<p>To make it easier for you to know which modules you need to import based on your option, our new example page adds a new feature to generate the three-shakable code, you can check the <code class=\"codespan\">Full Code</code> tab on the example page to see the modules you need to introduce and the related code.</p>\n<p>In most cases, we recommend using the new tree-shaking interface whenever possible, as it maximizes the power of the packaging tool tree-shaking and effectively resolves namespace conflicts and prevents the exposure of internal structures. If you are still using the CommonJS method of writing modules, the previous approach is still supported:</p>\n<pre><code class=\"lang-js\">const echarts = require(&#39;echarts/lib/echarts&#39;);\nrequire(&#39;echarts/lib/chart/bar&#39;);\nrequire(&#39;echarts/lib/component/grid&#39;);\n</code></pre>\n<p>Second, because our source code has been rewritten using TypeScript, <code class=\"codespan\">v5</code> will no longer support importing files from <code class=\"codespan\">echarts/src</code>. You need to change it to import from <code class=\"codespan\">echarts/lib</code>.</p>\n<h5 id=\"dependency-adjustment\">dependency adjustment</h5>\n<blockquote>\n<p>Note: This section is only for developers who use tree-shaking interfaces to ensure a minimal bundle size, not for those who imports the whole package.</p>\n</blockquote>\n<p>In order to keep the size of the bundle small enough, we remove some dependencies that would have been imported by default. For example, as mentioned above, when using the new on-demand interface, <code class=\"codespan\">CanvasRenderer</code> is no longer introduced by default, which ensures that unneeded Canvas rendering code is not imported when only SVG rendering mode is used, and in addition, the following dependencies are adjusted.</p>\n<ul>\n<li>The right-angle coordinate system component is no longer introduced by default when using line charts and bar charts, so the following introduction method was used before<pre><code class=\"lang-js\">const echarts = require(&#39;echarts/lib/echarts&#39;);\nrequire(&#39;echarts/lib/chart/bar&#39;);\nrequire(&#39;echarts/lib/chart/line&#39;);\n</code></pre>\nNeed to introduce the <code class=\"codespan\">grid</code> component separately again<pre><code class=\"lang-js\">require(&#39;echarts/lib/component/grid&#39;);\n</code></pre>\n</li>\n</ul>\n<p>Reference issues: <a href=\"https://github.com/apache/echarts/issues/14080\" target=\"_blank\">#14080</a>, <a href=\"https://github.com/apache/echarts/issues/13764\" target=\"_blank\">#13764</a></p>\n<ul>\n<li><code class=\"codespan\">aria</code> components are no longer imported by default. You need import it manually if necessary.<pre><code class=\"lang-js\">import { AriaComponent } from &#39;echarts/components&#39;;\necharts.use(AriaComponent);\n</code></pre>\nOr<pre><code class=\"lang-js\">require(&#39;echarts/lib/component/aria&#39;);\n</code></pre>\n</li>\n</ul>\n<h4 id=\"removes-built-in-geojson\">removes built-in geoJSON</h4>\n<p><code class=\"codespan\">v5</code> removes the built-in geoJSON (previously in the <code class=\"codespan\">echarts/map</code> folder). These geoJSON files were always sourced from third parties. If users still need them, they can go get them from the old version, or find more appropriate data and register it with ECharts via the registerMap interface.</p>\n<h4 id=\"browser-compatibility\">Browser Compatibility</h4>\n<p>IE8 is no longer supported by <code class=\"codespan\">v5</code>. We no longer maintain and upgrade the previous <a href=\"https://github.com/ecomfe/zrender/tree/4.3.2/src/vml\" target=\"_blank\">VML renderer</a> for IE8 compatibility. If developers have a strong need for a VML renderer, they are welcome to submit a pull request to upgrade the VML renderer or maintain a separate third-party VML renderer, as we support registration of standalone renderers starting with <code class=\"codespan\">v5.0.1</code>.</p>\n<h4 id=\"echarts-configuration-item-adjustment\">ECharts configuration item adjustment</h4>\n<h5 id=\"visual-style-settings-priority-change\">Visual style settings priority change</h5>\n<p>The priority of the visuals between <a href=\"option.html#visualMap\" target=\"_blank\">visualMap component</a> and <a href=\"option.html#series-scatter.itemStyle\" target=\"_blank\">itemStyle</a> | <a href=\"option.html#series-scatter.lineStyle\" target=\"_blank\">lineStyle</a> | <a href=\"option.html#series-scatter.areaStyle\" target=\"_blank\">areaStyle</a> are reversed since <code class=\"codespan\">v5</code>.</p>\n<p>That is, previously in <code class=\"codespan\">v4</code>, the visuals (i.e., color, symbol, symbolSize, ...) that generated by <a href=\"option.html#visualMap\" target=\"_blank\">visualMap component</a> has the highest priority, which will overwrite the same visuals settings in <a href=\"option.html#series-scatter.itemStyle\" target=\"_blank\">itemStyle</a> | <a href=\"option.html#series-scatter.lineStyle\" target=\"_blank\">lineStyle</a> | <a href=\"option.html#series-scatter.areaStyle\" target=\"_blank\">areaStyle</a>. That brought troubles when needing to specify specific style to some certain data items while using <a href=\"option.html#visualMap\" target=\"_blank\">visualMap component</a>. Since <code class=\"codespan\">v5</code>, the visuals specified in <a href=\"option.html#series-scatter.itemStyle\" target=\"_blank\">itemStyle</a> | <a href=\"option.html#series-scatter.lineStyle\" target=\"_blank\">lineStyle</a> | <a href=\"option.html#series-scatter.areaStyle\" target=\"_blank\">areaStyle</a> has the highest priority.</p>\n<p>In most cases, users will probably not notice this change when migrating from <code class=\"codespan\">v4</code> to <code class=\"codespan\">v5</code>. But users can still check that if <a href=\"option.html#visualMap\" target=\"_blank\">visualMap component</a> and <a href=\"option.html#series-scatter.itemStyle\" target=\"_blank\">itemStyle</a> | <a href=\"option.html#series-scatter.lineStyle\" target=\"_blank\">lineStyle</a> | <a href=\"option.html#series-scatter.areaStyle\" target=\"_blank\">areaStyle</a> are both specified.</p>\n<h5 id=\"padding-for-rich-text\"><code class=\"codespan\">padding</code> for rich text</h5>\n<p><code class=\"codespan\">v5</code> adjusts the <a href=\"option.html#series-scatter.label.rich.&lt;style_name&gt;.padding\" target=\"_blank\">rich.?.padding</a> to make it more compliant with CSS specifications. In <code class=\"codespan\">v4</code>, for example <code class=\"codespan\">rich. .padding: [11, 22, 33, 44]</code> means that <code class=\"codespan\">padding-top</code> is <code class=\"codespan\">33</code> and <code class=\"codespan\">padding-bottom</code> is <code class=\"codespan\">11</code>. The position of the top and bottom is adjusted in <code class=\"codespan\">v5</code>, <code class=\"codespan\">rich. .padding: [11, 22, 33, 44]</code> means that <code class=\"codespan\">padding-top</code> is <code class=\"codespan\">11</code> and <code class=\"codespan\">padding-bottom</code> is <code class=\"codespan\">33</code>.</p>\n<p>If the user is using <a href=\"option.html#series-scatter.label.rich.&lt;style_name&gt;.padding\" target=\"_blank\">rich.?.padding</a>, this order needs to be adjusted.</p>\n<h2 id=\"echarts-related-extensions\">ECharts Related Extensions</h2>\n<p>These extensions need to be upgraded to new version to support echarts <code class=\"codespan\">v5</code>:</p>\n<ul>\n<li><a href=\"https://github.com/ecomfe/echarts-gl\" target=\"_blank\">echarts-gl</a></li>\n<li><a href=\"https://github.com/ecomfe/echarts-wordcloud\" target=\"_blank\">echarts-wordcloud</a></li>\n<li><a href=\"https://github.com/ecomfe/echarts-liquidfill\" target=\"_blank\">echarts-liquidfill</a></li>\n</ul>\n<h2 id=\"deprecated-api\">Deprecated API</h2>\n<p>Some of the API and echarts options are deprecated since <code class=\"codespan\">v5</code>, but are still backward compatible. Users can <strong>keep using these deprecated API</strong>, with only some warning will be printed to console in dev mode. But if users have spare time, it is recommended to upgraded to new API for the consideration of long term maintenance.</p>\n<p>The deprecated API and their corresponding new API are listed as follows:</p>\n<ul>\n<li>Transform related props of a graphic element are changed:<ul>\n<li>Changes:<ul>\n<li><code class=\"codespan\">position: [number, number]</code> are changed to <code class=\"codespan\">x: number</code>/<code class=\"codespan\">y: number</code>.</li>\n<li><code class=\"codespan\">scale: [number, number]</code> are changed to <code class=\"codespan\">scaleX: number</code>/<code class=\"codespan\">scaleY: number</code>.</li>\n<li><code class=\"codespan\">origin: [number, number]</code> are changed to <code class=\"codespan\">originX: number</code>/<code class=\"codespan\">originY: number</code>.</li>\n</ul>\n</li>\n<li>The <code class=\"codespan\">position</code>, <code class=\"codespan\">scale</code> and <code class=\"codespan\">origin</code> are still supported but deprecated.</li>\n<li>It effects these places:<ul>\n<li>In the <code class=\"codespan\">graphic</code> components: the declarations of each element.</li>\n<li>In <code class=\"codespan\">custom series</code>: the declarations of each element in the return of <code class=\"codespan\">renderItem</code>.</li>\n<li>Directly use zrender graphic elements.</li>\n</ul>\n</li>\n</ul>\n</li>\n<li>Text related props on graphic elements are changed:<ul>\n<li>Changes:<ul>\n<li>The declaration of attached text (or say, rect text) are changed.<ul>\n<li>Prop <code class=\"codespan\">style.text</code> are deprecated in elements except <code class=\"codespan\">Text</code>. Instead, Prop set <code class=\"codespan\">textContent</code> and <code class=\"codespan\">textConfig</code> are provided to support more powerful capabilities.</li>\n<li>These related props at the left part below are deprecated. Use the right part below instead.<ul>\n<li>textPosition =&gt; textConfig.position</li>\n<li>textOffset =&gt; textConfig.offset</li>\n<li>textRotation =&gt; textConfig.rotation</li>\n<li>textDistance =&gt; textConfig.distance</li>\n</ul>\n</li>\n</ul>\n</li>\n<li>The props at the left part below are deprecated in <code class=\"codespan\">style</code> and <code class=\"codespan\">style.rich.?</code>. Use the props at the right part below instead.<ul>\n<li>textFill =&gt; fill</li>\n<li>textStroke =&gt; stroke</li>\n<li>textFont =&gt; font</li>\n<li>textStrokeWidth =&gt; lineWidth</li>\n<li>textAlign =&gt; align</li>\n<li>textVerticalAlign =&gt; verticalAlign);</li>\n<li>textLineHeight =&gt;</li>\n<li>textWidth =&gt; width</li>\n<li>textHeight =&gt; hight</li>\n<li>textBackgroundColor =&gt; backgroundColor</li>\n<li>textPadding =&gt; padding</li>\n<li>textBorderColor =&gt; borderColor</li>\n<li>textBorderWidth =&gt; borderWidth</li>\n<li>textBorderRadius =&gt; borderRadius</li>\n<li>textBoxShadowColor =&gt; shadowColor</li>\n<li>textBoxShadowBlur =&gt; shadowBlur</li>\n<li>textBoxShadowOffsetX =&gt; shadowOffsetX</li>\n<li>textBoxShadowOffsetY =&gt; shadowOffsetY</li>\n</ul>\n</li>\n<li>Note: these props are not changed:<ul>\n<li>textShadowColor</li>\n<li>textShadowBlur</li>\n<li>textShadowOffsetX</li>\n<li>textShadowOffsetY</li>\n</ul>\n</li>\n</ul>\n</li>\n<li>It effects these places:<ul>\n<li>In the <code class=\"codespan\">graphic</code> components: the declarations of each element. [compat, but not accurately the same in some complicated cases.]</li>\n<li>In <code class=\"codespan\">custom series</code>: the declarations of each element in the return of <code class=\"codespan\">renderItem</code>. [compat, but not accurately the same in some complicated cases].</li>\n<li>Directly use zrender API to create graphic elements. [No compat, breaking change].</li>\n</ul>\n</li>\n</ul>\n</li>\n<li>API on chart instance:<ul>\n<li><code class=\"codespan\">chart.one(...)</code> is deprecated.</li>\n</ul>\n</li>\n<li><code class=\"codespan\">label</code>:<ul>\n<li>In props <code class=\"codespan\">color</code>, <code class=\"codespan\">textBorderColor</code>, <code class=\"codespan\">backgroundColor</code> and <code class=\"codespan\">borderColor</code>, the value <code class=\"codespan\">&#39;auto&#39;</code> is deprecated. Use the value <code class=\"codespan\">&#39;inherit&#39;</code> instead.</li>\n</ul>\n</li>\n<li><code class=\"codespan\">hoverAnimation</code>:<ul>\n<li>option <code class=\"codespan\">series.hoverAnimation</code> is deprecated. Use <code class=\"codespan\">series.emphasis.scale</code> instead.</li>\n</ul>\n</li>\n<li><code class=\"codespan\">line series</code>:<ul>\n<li>option <code class=\"codespan\">series.clipOverflow</code> is deprecated. Use <code class=\"codespan\">series.clip</code> instead.</li>\n</ul>\n</li>\n<li><code class=\"codespan\">custom series</code>:<ul>\n<li>In <code class=\"codespan\">renderItem</code>, the <code class=\"codespan\">api.style(...)</code> and <code class=\"codespan\">api.styleEmphasis(...)</code> are deprecated. Because it is not really necessary and hard to ensure backward compatibility. Users can fetch system designated visual by <code class=\"codespan\">api.visual(...)</code>.</li>\n</ul>\n</li>\n<li><code class=\"codespan\">sunburst series</code>:<ul>\n<li>Action type <code class=\"codespan\">highlight</code> is deprecated. Use <code class=\"codespan\">sunburstHighlight</code> instead.</li>\n<li>Action type <code class=\"codespan\">downplay</code> is deprecated. Use <code class=\"codespan\">sunburstUnhighlight</code> instead.</li>\n<li>option <code class=\"codespan\">series.downplay</code> is deprecated. Use <code class=\"codespan\">series.blur</code> instead.</li>\n<li>option <code class=\"codespan\">series.highlightPolicy</code> is deprecated. Use <code class=\"codespan\">series.emphasis.focus</code> instead.</li>\n</ul>\n</li>\n<li><code class=\"codespan\">pie series</code>:<ul>\n<li>The action type at the left part below are deprecated. Use the right part instead:<ul>\n<li><code class=\"codespan\">pieToggleSelect</code> =&gt; <code class=\"codespan\">toggleSelect</code></li>\n<li><code class=\"codespan\">pieSelect</code> =&gt; <code class=\"codespan\">select</code></li>\n<li><code class=\"codespan\">pieUnSelect</code> =&gt; <code class=\"codespan\">unselect</code></li>\n</ul>\n</li>\n<li>The event type at the left part below are deprecated. Use the right part instead:<ul>\n<li><code class=\"codespan\">pieselectchanged</code> =&gt; <code class=\"codespan\">selectchanged</code></li>\n<li><code class=\"codespan\">pieselected</code> =&gt; <code class=\"codespan\">selected</code></li>\n<li><code class=\"codespan\">pieunselected</code> =&gt; <code class=\"codespan\">unselected</code></li>\n</ul>\n</li>\n<li>option <code class=\"codespan\">series.label.margin</code> is deprecated. Use <code class=\"codespan\">series.label.edgeDistance</code> instead.</li>\n<li>option <code class=\"codespan\">series.clockWise</code> is deprecated. Use <code class=\"codespan\">series.clockwise</code> instead.</li>\n<li>option <code class=\"codespan\">series.hoverOffset</code> is deprecated. Use <code class=\"codespan\">series.emphasis.scaleSize</code> instead.</li>\n</ul>\n</li>\n<li><code class=\"codespan\">map series</code>:<ul>\n<li>The action type at the left part below are deprecated. Use the right part instead:<ul>\n<li><code class=\"codespan\">mapToggleSelect</code> =&gt; <code class=\"codespan\">toggleSelect</code></li>\n<li><code class=\"codespan\">mapSelect</code> =&gt; <code class=\"codespan\">select</code></li>\n<li><code class=\"codespan\">mapUnSelect</code> =&gt; <code class=\"codespan\">unselect</code></li>\n</ul>\n</li>\n<li>The event type at the left part below are deprecated. Use the right part instead:<ul>\n<li><code class=\"codespan\">mapselectchanged</code> =&gt; <code class=\"codespan\">selectchanged</code></li>\n<li><code class=\"codespan\">mapselected</code> =&gt; <code class=\"codespan\">selected</code></li>\n<li><code class=\"codespan\">mapunselected</code> =&gt; <code class=\"codespan\">unselected</code></li>\n</ul>\n</li>\n<li>option <code class=\"codespan\">series.mapType</code> is deprecated. Use <code class=\"codespan\">series.map</code> instead.</li>\n<li>option <code class=\"codespan\">series.mapLocation</code> is deprecated.</li>\n</ul>\n</li>\n<li><code class=\"codespan\">graph series</code>:<ul>\n<li>option <code class=\"codespan\">series.focusNodeAdjacency</code> is deprecated. Use <code class=\"codespan\">series.emphasis: { focus: &#39;adjacency&#39;}</code> instead.</li>\n</ul>\n</li>\n<li><code class=\"codespan\">gauge series</code>:<ul>\n<li>option <code class=\"codespan\">series.clockWise</code> is deprecated. Use <code class=\"codespan\">series.clockwise</code> instead.</li>\n<li>option <code class=\"codespan\">series.hoverOffset</code> is deprecated. Use <code class=\"codespan\">series.emphasis.scaleSize</code> instead.</li>\n</ul>\n</li>\n<li><code class=\"codespan\">dataZoom component</code>:<ul>\n<li>option <code class=\"codespan\">dataZoom.handleIcon</code> need prefix <code class=\"codespan\">path://</code> if using SVGPath.</li>\n</ul>\n</li>\n<li><code class=\"codespan\">radar</code>:<ul>\n<li>option <code class=\"codespan\">radar.name</code> is deprecated. Use <code class=\"codespan\">radar.axisName</code> instead.</li>\n<li>option <code class=\"codespan\">radar.nameGap</code> is deprecated. Use <code class=\"codespan\">radar.axisNameGap</code> instead.</li>\n</ul>\n</li>\n<li>Parse and format:<ul>\n<li><code class=\"codespan\">echarts.format.formatTime</code> is deprecated. Use <code class=\"codespan\">echarts.time.format</code> instead.</li>\n<li><code class=\"codespan\">echarts.number.parseDate</code> is deprecated. Use <code class=\"codespan\">echarts.time.parse</code> instead.</li>\n<li><code class=\"codespan\">echarts.format.getTextRect</code> is deprecated.</li>\n</ul>\n</li>\n</ul>\n"},"Use ECharts with bundler and NPM":{"type":["*"],"description":"<p>If your development environment uses a package management tool like <code class=\"codespan\">npm</code> or <code class=\"codespan\">yarn</code> and builds with a packaging tool like Webpack, this article will describe how to get a minimal bundle of Apache ECharts<sup>TM</sup> via treeshaking.</p>\n<h2 id=\"npm-installation-of-echarts\">NPM installation of ECharts</h2>\n<p>You can install ECharts via npm using the following command</p>\n<pre><code class=\"lang-shell\">npm install echarts --save\n</code></pre>\n<h2 id=\"introduce-echarts\">Introduce ECharts</h2>\n<pre><code class=\"lang-js\">import * as echarts from &#39;echarts&#39;;\n\n// initialize the echarts instance\nvar myChart = echarts.init(document.getElementById(&#39;main&#39;));\n// Draw the chart\nmyChart.setOption({\n    title: {\n        text: &#39;ECharts Getting Started Example&#39;\n    },\n    tooltip: {},\n    xAxis: {\n        data: [&#39;shirt&#39;, &#39;cardigan&#39;, &#39;chiffon&#39;, &#39;pants&#39;, &#39;heels&#39;, &#39;socks&#39;]\n    },\n    yAxis: {},\n    series: [{\n        name: &#39;sales&#39;,\n        type: &#39;bar&#39;,\n        data: [5, 20, 36, 10, 10, 20]\n    }]\n});\n</code></pre>\n<h2 id=\"importing-required-charts-and-components-to-have-minimal-bundle-\">Importing required charts and components to have minimal bundle.</h2>\n<p>The above code will import all the charts and components in ECharts, but if you don&#39;t want to bring in all the components, you can use the tree-shakeable interface provided by ECharts to bundle the required components and get a minimal bundle.</p>\n<pre><code class=\"lang-js\">// Import the echarts core module, which provides the necessary interfaces for using echarts.\nimport * as echarts from &#39;echarts/core&#39;;\n// Import bar charts, all with Chart suffix\nimport {\n    BarChart\n} from &#39;echarts/charts&#39;;\n// import the tooltip, title, and rectangular coordinate system components, all suffixed with Component\nimport {\n    TitleComponent,\n    TooltipComponent,\n    GridComponent\n} from &#39;echarts/components&#39;;\n// Import the Canvas renderer, note that introducing the CanvasRenderer or SVGRenderer is a required step\nimport {\n    CanvasRenderer\n} from &#39;echarts/renderers&#39;;\n\n// Register the required components\necharts.use(\n    [TitleComponent, TooltipComponent, GridComponent, BarChart, CanvasRenderer]\n);\n\n// The next step is the same as before, initialize the chart and set the configuration items\nvar myChart = echarts.init(document.getElementById(&#39;main&#39;));\nmyChart.setOption({\n    ...\n});\n</code></pre>\n<blockquote>\n<p>Note that in order to keep the size of the package to a minimum, ECharts does not provide any renderer in tree-shakeable interface, so you need to choose to import <code class=\"codespan\">CanvasRenderer</code> or <code class=\"codespan\">SVGRenderer</code> as the renderer. The advantage of this is that if you only need to use the svg rendering mode, the bundle will not include the <code class=\"codespan\">CanvasRenderer</code> module, which is not needed.</p>\n</blockquote>\n<p>The &quot;Full Code&quot; tab on our sample editor page provides a very convenient way to generate a tree-shakable code. It will generate tree-shakable code based on the current option dynamically. You can use it directly in your project.</p>\n<h2 id=\"minimal-option-type-in-typescript\">Minimal Option Type in TypeScript</h2>\n<p>For developers who are using TypeScript to develop ECharts, we provide a type interface to combine the minimal <code class=\"codespan\">EChartsOption</code> type. This stricter type can effectively help you check for missing components or charts.</p>\n<pre><code class=\"lang-ts\">import * as echarts from &#39;echarts/core&#39;;\nimport {\n    BarChart,\n    // The series types are defined with the SeriesOption suffix\n    BarSeriesOption,\n    LineChart,\n    LineSeriesOption\n} from &#39;echarts/charts&#39;;\nimport {\n    TitleComponent,\n    // The component types are defined with the suffix ComponentOption\n    TitleComponentOption,\n    GridComponent,\n    GridComponentOption\n} from &#39;echarts/components&#39;;\nimport {\n    CanvasRenderer\n} from &#39;echarts/renderers&#39;;\n\n// Combine an Option type with only required components and charts via ComposeOption\ntype ECOption = echarts.ComposeOption&lt;\n  BarSeriesOption | LineSeriesOption | TitleComponentOption | GridComponentOption\n&gt;;\n\n// Register the required components\necharts.use(\n    [TitleComponent, TooltipComponent, GridComponent, BarChart, CanvasRenderer]\n);\n\nvar option: ECOption = {\n    ...\n}\n</code></pre>\n"},"ECharts Basic Concepts Overview":{"type":["*"],"description":"<p>This chapter describes some of the common concepts and terms of Apache ECharts<sup>TM</sup>.</p>\n<h2 id=\"echarts-instance\">ECharts instance</h2>\n<p>We can create multiple <code class=\"codespan\">echarts instances</code> in a webpage. In each <code class=\"codespan\">echarts instance</code> we can create multiple diagrams, coordinate systems, etc. (described by <code class=\"codespan\">option</code>). With a DOM element prepared (as the container of an echarts instance), we can create a <code class=\"codespan\">echarts instance</code> based on that element. Each <code class=\"codespan\">echarts instance</code> takes its DOM element exclusively.</p>\n<p><br></p>\n<p><img width=\"500\" height=\"auto\" src=\"documents/asset/img/basic-concepts-overview/multiple-ec-instance.jpg\"></p>\n<h2 id=\"series\">Series</h2>\n<p><a href=\"option.html#series\" target=\"_blank\">series</a> is a very common term. In echarts, <a href=\"option.html#series\" target=\"_blank\">series</a> represents a series of value and the diagram generated from them. So the concept <a href=\"option.html#series\" target=\"_blank\">series</a> includes these key points: a series of value, the type of the diagram (<code class=\"codespan\">series.type</code>) and other parameters specified for the mapping from the values to a diagram.</p>\n<p>In echarts, the <code class=\"codespan\">series.type</code> and the &quot;diagram type&quot; are the same concept. <code class=\"codespan\">series.type</code> includes: <a href=\"option.html#series-line\" target=\"_blank\">line</a> (line plot), <a href=\"option.html#series-bar\" target=\"_blank\">bar</a> (bar chart), <a href=\"option.html#series-pie\" target=\"_blank\">pie</a> (pie chart), <a href=\"option.html#series-scatter\" target=\"_blank\">scatter</a> (scatter plot), <a href=\"option.html#series-graph\" target=\"_blank\">graph</a> (graph plot), <a href=\"option.html#series-tree\" target=\"_blank\">tree</a> (tree plot), etc.</p>\n<p>In the example below, there are three <a href=\"option.html#series\" target=\"_blank\">series</a> (<a href=\"option.html#series-pie\" target=\"_blank\">pie</a>, <a href=\"option.html#series-line\" target=\"_blank\">line</a>, <a href=\"option.html#series-bar\" target=\"_blank\">bar</a>) declared in the <code class=\"codespan\">option</code> on the right, where <a href=\"option.html#series.data\" target=\"_blank\">series.data</a> are declared in each series:</p>\n<p><br></p>\n<p><img width=\"700\" height=\"auto\" src=\"documents/asset/img/basic-concepts-overview/series-all-a.jpg\"></p>\n<p><br></p>\n<p>Similarly, the following example shows another style of <code class=\"codespan\">option</code>, where each series retrieves data from <a href=\"option.html#dataset\" target=\"_blank\">dataset</a>:</p>\n<p><br></p>\n<p><img width=\"600\" height=\"auto\" src=\"documents/asset/img/basic-concepts-overview/series-all-b.jpg\"></p>\n<h2 id=\"component\">Component</h2>\n<p>Over series, the entities in echarts are abstracted using the term &quot;component&quot;. For example, echarts includes these components: <a href=\"option.html#xAxis\" target=\"_blank\">xAxis</a> (the x axis of Cartesian coordinate system), <a href=\"option.html#yAxis\" target=\"_blank\">yAxis</a> (the y axis of Cartesian coordinate system), <a href=\"option.html#grid\" target=\"_blank\">grid</a> (the baseboard of Cartesian coordinate system), <a href=\"option.html#angleAxis\" target=\"_blank\">angleAxis</a> (the angle axis of polar coordinate system), <a href=\"option.html#radiusAxis\" target=\"_blank\">radiusAxis</a> (the radius axis of polar coordinate system), <a href=\"option.html#polar\" target=\"_blank\">polar</a> (the baseboard of polar coordinate system), <a href=\"option.html#geo\" target=\"_blank\">geo</a> (GEO coordinate system), <a href=\"option.html#dataZoom\" target=\"_blank\">dataZoom</a> (the component for changing the displayed range of data), <a href=\"option.html#visualMap\" target=\"_blank\">visualMap</a> (the component for specifying the visual mapping), <a href=\"option.html#tooltip\" target=\"_blank\">tooltip</a> (the tooltip component), <a href=\"option.html#toolbox\" target=\"_blank\">toolbox</a> (the toolbox component), <a href=\"option.html#series\" target=\"_blank\">series</a>, etc.</p>\n<p>Notice that <a href=\"option.html#series\" target=\"_blank\">series</a> is a kind of component, a component for rendering diagram.</p>\n<p>Check the example below. Components (including series) are declared in <code class=\"codespan\">option</code> on the right, and the are finally rendered in the echarts instance.</p>\n<p><br></p>\n<p><img width=\"800\" height=\"auto\" src=\"documents/asset/img/basic-concepts-overview/components.jpg\"></p>\n<p><br></p>\n<p>Notice: although <a href=\"option.html#series\" target=\"_blank\">series</a> is a kind of component, sometimes we can see phrases like &quot;series and components&quot;. The term &quot;component&quot; in this context actually means &quot;components except series&quot;.</p>\n<h2 id=\"define-charts-using-option\">Define charts using option</h2>\n<p>We have met the term <code class=\"codespan\">option</code> above. Users should use <code class=\"codespan\">option</code> to describe all of their requirements and input it to echarts. The requirements includes: &quot;what does the data like&quot;, &quot;what the diagram we need&quot;, &quot;what components we need&quot;, &quot;what the user interactions we need&quot;, etc. In short, <code class=\"codespan\">option</code> defines: <code class=\"codespan\">data</code>, <code class=\"codespan\">visual mapping</code>, <code class=\"codespan\">interaction</code>.</p>\n<pre><code class=\"lang-js\">// Create an echarts instance.\nvar dom = document.getElementById(&#39;dom-id&#39;);\nvar chart = echarts.init(dom);\n\n// Use option to describe `data`, `visual mapping`, `interaction`, ...\n// `option` is a big JavaScript object.\nvar option = {\n    // Each property represents a kind of components.\n    legend: {...},\n    grid: {...},\n    tooltip: {...},\n    toolbox: {...},\n    dataZoom: {...},\n    visualMap: {...},\n    // If there are more than one components in one kind, we use an array.\n    // For example, there are three x axes here.\n    xAxis: [\n        // Each item represents an instance of component.\n        // `type` is used to indicate the sub-type of the component.\n        {type: &#39;category&#39;, ...},\n        {type: &#39;category&#39;, ...},\n        {type: &#39;value&#39;, ...}\n    ],\n    yAxis: [{...}, {...}],\n    // There are multiple series, using an array.\n    series: [\n        // `type` is also used to indicate the sub-type\n        // (i.e., diagram type) of each series.\n        {type: &#39;line&#39;, data: [[&#39;AA&#39;, 332], [&#39;CC&#39;, 124], [&#39;FF&#39;, 412], ... ]},\n        {type: &#39;line&#39;, data: [2231, 1234, 552, ... ]},\n        {type: &#39;line&#39;, data: [[4, 51], [8, 12], ... ]}\n    }]\n};\n\n// Call `setOption` and input the `option`. And then the\n// echarts instance processes data and renders charts.\nchart.setOption(option);\n</code></pre>\n<p>Data is put in <a href=\"option.html#series.data\" target=\"_blank\">series.data</a> in the above example. And we give another example showing another way, where each series retrieves data from <a href=\"option.html#dataset\" target=\"_blank\">dataset</a>:</p>\n<pre><code class=\"lang-js\">var option = {\n    dataset: {\n        source: [\n            [121, &#39;XX&#39;, 442, 43.11],\n            [663, &#39;ZZ&#39;, 311, 91.14],\n            [913, &#39;ZZ&#39;, 312, 92.12],\n            ...\n        ]\n    },\n    xAxis: {},\n    yAxis: {},\n    series: [\n        // Each series retrieves data from `dataset`. The values in `encode`\n        // are the indices of the dimensions (i.e., column) of `dataset.source`.\n        {type: &#39;bar&#39;, encode: {x: 1, y: 0}},\n        {type: &#39;bar&#39;, encode: {x: 1, y: 2}},\n        {type: &#39;scatter&#39;, encode: {x: 1, y: 3}},\n        ...\n    ]\n};\n</code></pre>\n<h2 id=\"position-a-component\">Position a component</h2>\n<p>These approaches are used to Position a component.</p>\n<p><br></p>\n<p><strong>[Absolute positioning like CSS]</strong></p>\n<p><br></p>\n<p>Most components and series can be absolutely positioned according to <code class=\"codespan\">top</code> / <code class=\"codespan\">right</code> / <code class=\"codespan\">down</code> / <code class=\"codespan\">left</code> / <code class=\"codespan\">width</code> / <code class=\"codespan\">height</code>. This approach is like the absolute positioning in CSS. The absolute positioning is based on the container DOM element of the echarts.</p>\n<p>The value of each attribute can be:</p>\n<ul>\n<li>Absolute value (like <code class=\"codespan\">bottom: 54</code>, means: the distance from the boundary of the echarts container to bottom boundary of the component is <code class=\"codespan\">54</code> pixel).</li>\n<li>Or the percentage based on the width/height of the echarts container (like <code class=\"codespan\">right: &#39;20%&#39;</code>, means: the distance from the boundary of the echarts container to the right boundary of this component is <code class=\"codespan\">20%</code> of the width of the echarts container).</li>\n</ul>\n<p>Check the example below, where the <a href=\"option.html#grid\" target=\"_blank\">grid</a> component (that is the baseboard of a Cartesian coordinate system) are configured with <code class=\"codespan\">left</code>、<code class=\"codespan\">right</code>、<code class=\"codespan\">height</code>、<code class=\"codespan\">bottom</code>.</p>\n<p><br></p>\n<p><img width=\"800\" height=\"auto\" src=\"documents/asset/img/basic-concepts-overview/locate.jpg\"></p>\n<p><br></p>\n<p>Note that <code class=\"codespan\">left</code> <code class=\"codespan\">right</code> <code class=\"codespan\">width</code> are one group of attributes for horizontal layout, while <code class=\"codespan\">top</code> <code class=\"codespan\">bottom</code> <code class=\"codespan\">height</code> are another group of attributes for vertical layout. The two groups have nothing to do with each other. In each group, it is enough to set only one or at most two attributes. For example, when <code class=\"codespan\">left</code> and <code class=\"codespan\">right</code> have been specified, <code class=\"codespan\">width</code> can be automatically calculated by them.</p>\n<p><br></p>\n<p><strong>[Center-radius positioning]</strong></p>\n<p><br></p>\n<p>A few circular components or series need to be positioned by &quot;center&quot; and &quot;radius&quot;. For example, <a href=\"option.html#series-pie\" target=\"_blank\">pie</a> (pie chart)、<a href=\"option.html#series-sunburst\" target=\"_blank\">sunburst</a> (sunburst chart)、<a href=\"option.html#polar\" target=\"_blank\">polar</a> (polar coordinate system).</p>\n<p>As the name implies, it position the component according to <a href=\"option.html#series-pie.center\" target=\"_blank\">center</a> and <a href=\"option.html#series-pie.radius\" target=\"_blank\">radius</a>.</p>\n<p><br></p>\n<p><strong>[Other positioning]</strong></p>\n<p><br></p>\n<p>A few other components may has their own specific positioning approach. Check their docs before using them.</p>\n<h2 id=\"coordinate-system\">Coordinate system</h2>\n<p>Many series, like <a href=\"option.html#series-line\" target=\"_blank\">line</a>, <a href=\"option.html#series-bar\" target=\"_blank\">bar</a>, <a href=\"option.html#series-scatter\" target=\"_blank\">scatter</a>, <a href=\"option.html#series-heatmap\" target=\"_blank\">heatmap</a>, etc., need to work on a coordinate system. Coordinate system is used to layout each graphic elements and display some ticks and labels. For example, echarts at least provides these coordinate systems: <a href=\"option.html#grid\" target=\"_blank\">Cartesian coordinate system</a>, <a href=\"option.html#polar\" target=\"_blank\">polar coordinate system</a>, <a href=\"option.html#geo\" target=\"_blank\">GEO coordinate system</a>, <a href=\"option.html#singleAxis\" target=\"_blank\">single axis coordinate system</a>, <a href=\"option.html#calendar\" target=\"_blank\">calendar coordinate system</a>, etc. Some other series like <a href=\"option.html#series-pie\" target=\"_blank\">pie</a>, <a href=\"option.html#series-tree\" target=\"_blank\">tree</a>, work independently without any coordinate systems. And still some other series like <a href=\"option.html#series-graph\" target=\"_blank\">graph</a> are available either independently or on some coordinate system, depending on user settings.</p>\n<p>A coordinate system may consist of several components. For example, Cartesian coordinate system consists of <a href=\"option.html#xAxis\" target=\"_blank\">xAxis</a>, <a href=\"option.html#yAxis\" target=\"_blank\">yAxis</a> and <a href=\"option.html#grid\" target=\"_blank\">grid</a> (the baseboard). <a href=\"option.html#xAxis\" target=\"_blank\">xAxis</a> and <a href=\"option.html#yAxis\" target=\"_blank\">yAxis</a> are referenced and assembled by <code class=\"codespan\">grid</code> and work together cooperatively.</p>\n<p>The following example demonstrates the most simple way to use a Cartesian coordinate system, where only <a href=\"option.html#xAxis\" target=\"_blank\">xAxis</a>, <a href=\"option.html#yAxis\" target=\"_blank\">yAxis</a> and a <a href=\"option.html#series-scatter\" target=\"_blank\">scatter series</a> are declared, and <code class=\"codespan\">echarts</code> create and a <code class=\"codespan\">grid</code> implicitly to link them.</p>\n<p><br></p>\n<p><img width=\"450\" height=\"auto\" src=\"documents/asset/img/basic-concepts-overview/coord-sys-0.jpg\"></p>\n<p><br></p>\n<p>And the following example demonstrates a more complicated case, where two <a href=\"option.html#yAxis\" target=\"_blank\">yAxis</a> share one <a href=\"option.html#xAxis\" target=\"_blank\">xAxis</a>. And the two <code class=\"codespan\">series</code> are also share the <a href=\"option.html#xAxis\" target=\"_blank\">xAxis</a>, but use different <a href=\"option.html#yAxis\" target=\"_blank\">yAxis</a> respectively. The property <a href=\"option.html#series-line.yAxisIndex\" target=\"_blank\">yAxisIndex</a> is used to specify which <a href=\"option.html#yAxis\" target=\"_blank\">yAxis</a> is used.</p>\n<p><br></p>\n<p><img width=\"600\" height=\"auto\" src=\"documents/asset/img/basic-concepts-overview/coord-sys-1.jpg\"></p>\n<p><br></p>\n<p>The following echarts instance contain more than one <a href=\"option.html#grid\" target=\"_blank\">grid</a>. Each <a href=\"option.html#grid\" target=\"_blank\">grid</a> has its own <a href=\"option.html#xAxis\" target=\"_blank\">xAxis</a> and <a href=\"option.html#yAxis\" target=\"_blank\">yAxis</a>. The properties <a href=\"option.html#series-line.xAxisIndex\" target=\"_blank\">xAxisIndex</a>, <a href=\"option.html#series-line.yAxisIndex\" target=\"_blank\">yAxisIndex</a> and <a href=\"option.html#yAxis.gridIndex\" target=\"_blank\">gridIndex</a> are used to specify the reference relationships.</p>\n<p><br></p>\n<p><img width=\"600\" height=\"auto\" src=\"documents/asset/img/basic-concepts-overview/coord-sys-2.jpg\"></p>\n<p><br></p>\n<p>Moreover, a type of series is usually available on various coordinate systems. For example, a <a href=\"option.html#series-scatter\" target=\"_blank\">scatter series</a> can work on <a href=\"option.html#grid\" target=\"_blank\">Cartesian coordinate system</a>, <a href=\"option.html#polar\" target=\"_blank\">polar coordinate system</a>, <a href=\"option.html#geo\" target=\"_blank\">GEO coordinate system</a> or other coordinate systems. Similarly, a coordinate system can serve different type of series. As the examples shown above, a <a href=\"option.html#grid\" target=\"_blank\">Cartesian coordinate system</a> serves several <a href=\"option.html#series-line\" target=\"_blank\">line series</a> and <a href=\"option.html#series-bar\" target=\"_blank\">bar series</a>.</p>\n"},"Customized Chart Styles":{"type":["*"],"description":"<p>Apache ECharts<sup>TM</sup> provides a rich amount of configurable items, which can be set in global, series, and data three different levels. Next, let&#39;s see an example of how to use ECharts to implement the following Nightingale rose chart:</p>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=doc-example/tutorial-styling-step5&edit=1&reset=1\" width=\"500\" height=\"400\" ></iframe>\n\n\n<h2 id=\"drawing-nightingale-rose-chart\">Drawing Nightingale Rose Chart</h2>\n<p><a href=\"#Get%20Started%20with%20ECharts%20in%205%20minutes\">Getting started tutorial</a> introduced how to make a simple bar chart. This time, we are going to make a pie chart. Pie charts use arc length of fans to represent ratio of a certain series in total share. It&#39;s data format is simpler than bar chart, because it only contains one dimension without category. Besides, since it&#39;s not in rectangular system, it doesn&#39;t need <code class=\"codespan\">xAxis</code>、<code class=\"codespan\">yAxis</code> either.</p>\n<pre><code class=\"lang-js\">myChart.setOption({\n    series : [\n        {\n            name: &#39;Reference Page&#39;,\n            type: &#39;pie&#39;,\n            radius: &#39;55%&#39;,\n            data:[\n                {value:400, name:&#39;Searching Engine&#39;},\n                {value:335, name:&#39;Direct&#39;},\n                {value:310, name:&#39;Email&#39;},\n                {value:274, name:&#39;Alliance Advertisement&#39;},\n                {value:235, name:&#39;Video Advertisement&#39;}\n            ]\n        }\n    ]\n})\n</code></pre>\n<p>With the above code, we can create a simple pie chart:</p>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=doc-example/tutorial-styling-step0&edit=1&reset=1\" width=\"400\" height=\"300\" ></iframe>\n\n\n<p>Here, the value of <code class=\"codespan\">data</code> is not a single value, as that of the example in get started. Instead, it&#39;s an object containing <code class=\"codespan\">name</code> and <code class=\"codespan\">value</code>. Data in ECharts can always be a single value, or a configurable object with name, style and label. You may refer to <a href=\"option.html#series-pie.data\" target=\"_blank\">data</a> for more information.</p>\n<p><a href=\"option.html#series-pie\" target=\"_blank\">Pie charts</a> of EChart can be made into Nightingale rose charts with <a href=\"option.html#series-pie.roseType\" target=\"_blank\">roseType</a> field.</p>\n<pre><code class=\"lang-js\">roseType: &#39;angle&#39;\n</code></pre>\n<p>Nightingale rose charts use radius to represent data value.</p>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=doc-example/tutorial-styling-step1&edit=1&reset=1\" width=\"400\" height=\"300\" ></iframe>\n\n\n<h2 id=\"configuring-shadow\">Configuring Shadow</h2>\n<p>Commonly used styles of ECharts, like shadow, opacity, color, border-color, border-width, and etc., are set by <a href=\"#series-pie.itemStyle\">itemStyle</a> in series.</p>\n<pre><code class=\"lang-js\">itemStyle: {\n    // shadow size\n    shadowBlur: 200,\n    // horizontal offset of shadow\n    shadowOffsetX: 0,\n    // vertical offset of shadow\n    shadowOffsetY: 0,\n    // shadow color\n    shadowColor: &#39;rgba(0, 0, 0, 0.5)&#39;\n}\n</code></pre>\n<p>The effect after added shadow is:</p>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=doc-example/tutorial-styling-step2&edit=1&reset=1\" width=\"400\" height=\"300\" ></iframe>\n\n\n<p>Each <code class=\"codespan\">itemStyle</code> has <code class=\"codespan\">emphasis</code> as the highlighted style when mouse hovered. The last example shows the effect of adding shadow by default. But in most situations, we may probably need to add shadow to emphasis when mouse is hovered.</p>\n<pre><code class=\"lang-js\">itemStyle: {\n    emphasis: {\n        shadowBlur: 200,\n        shadowColor: &#39;rgba(0, 0, 0, 0.5)&#39;\n    }\n}\n</code></pre>\n<h2 id=\"dark-background-and-light-text\">Dark Background and Light Text</h2>\n<p>Now, we need to change the whole theme as that shown in the example at the beginning of this tutorial. This can be achieved by changing background color and text color.</p>\n<p>Background is a global configurable object, so we can set it directly with <a href=\"option.html#backgroundColor\" target=\"_blank\">backgroundColor</a> of option.</p>\n<pre><code class=\"lang-js\">setOption({\n    backgroundColor: &#39;#2c343c&#39;\n})\n</code></pre>\n<p>Text style can also be set globally in <a href=\"option.html#textStyle\" target=\"_blank\">textStyle</a>.</p>\n<pre><code class=\"lang-js\">setOption({\n    textStyle: {\n        color: &#39;rgba(255, 255, 255, 0.3)&#39;\n    }\n})\n</code></pre>\n<p>On the other hand, we can also set them in <a href=\"option.html#series-pie.label.textStyle\" target=\"_blank\">label.textStyle</a> of each series.</p>\n<pre><code class=\"lang-js\">label: {\n    textStyle: {\n        color: &#39;rgba(255, 255, 255, 0.3)&#39;\n    }\n}\n</code></pre>\n<p>We also need to set line color of pie chart to be lighter.</p>\n<pre><code class=\"lang-js\">labelLine: {\n    lineStyle: {\n        color: &#39;rgba(255, 255, 255, 0.3)&#39;\n    }\n}\n</code></pre>\n<p>Thus, we can get the following effect.</p>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=doc-example/tutorial-styling-step3&edit=1&reset=1\" width=\"400\" height=\"300\" ></iframe>\n\n\n<p>Similar to <code class=\"codespan\">itemStyle</code>, <code class=\"codespan\">label</code> and <code class=\"codespan\">labelLine</code> also have <code class=\"codespan\">emphasis</code> children.</p>\n<h2 id=\"setting-fan-colors\">Setting Fan Colors</h2>\n<p>Fan colors can be set in <code class=\"codespan\">itemStyle</code>:</p>\n<pre><code class=\"lang-js\">itemStyle: {\n    // 设置扇形的颜色\n    color: &#39;#c23531&#39;,\n    shadowBlur: 200,\n    shadowColor: &#39;rgba(0, 0, 0, 0.5)&#39;\n}\n</code></pre>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=doc-example/tutorial-styling-step4&edit=1&reset=1\" width=\"400\" height=\"300\" ></iframe>\n\n\n<p>This is quite similar to our expect effect, except that fan colors should be made darker within shadow area, so as to make a sense of layering and space with blocked light.</p>\n<p>Each fan&#39;s color can be set under <code class=\"codespan\">data</code>:</p>\n<pre><code class=\"lang-js\">data: [{\n    value:400,\n    name:&#39;搜索引擎&#39;,\n    itemStyle: {\n        color: &#39;#c23531&#39;\n    }\n}, ...]\n</code></pre>\n<p>But since we only need the variation of color in this example, there&#39;s a simpler way to map data value to lightness through <a href=\"option.html#visualMap\" target=\"_blank\">visualMap</a>.</p>\n<pre><code class=\"lang-js\">visualMap: {\n    // hide visualMap component; use lightness mapping only\n    show: false,\n    // mapping with min value at 80\n    min: 80,\n    // mapping with max value at 600\n    max: 600,\n    inRange: {\n        // mapping lightness from 0 to 1\n        colorLightness: [0, 1]\n    }\n}\n</code></pre>\n<p>The final effect is:</p>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=doc-example/tutorial-styling-step5&edit=1&reset=1\" width=\"500\" height=\"400\" ></iframe>\n\n\n\n\n\n"},"Overview of Style Customization":{"type":["*"],"description":"<p>This article provides an overview of the different approaches about Apache ECharts<sup>TM</sup> style customization. For example, how to config the color, size, shadow of the graphic elements and labels.</p>\n<blockquote>\n<p>The term &quot;style&quot; may not follow the convention of data visualization, but we use it in this article because it is popular and easy to understand.</p>\n</blockquote>\n<p>These approaches below will be introduced. The functionalities of them might be overlapped, but they are suitable for different scenarios.</p>\n<ul>\n<li>Theme</li>\n<li>Pallette</li>\n<li>Customize style explicitly (itemStyle, lineStyle, areaStyle, label, ...)</li>\n<li>Visual encoding (visualMap component)</li>\n</ul>\n<p>Other article about styling can be check in <a href=\"#Customized%20Chart%20Styles\">Customized Chart Styles</a> and <a href=\"#Visual%20Map%20of%20Data\">Visual Map of Data</a>.</p>\n<p><br></p>\n<hr>\n<p><br></p>\n<p><strong>Theme</strong></p>\n<p>Setting a theme is the simplest way to change the color style. For example, in <a href=\"https://echarts.apache.org/examples/en/index.html\" target=\"_blank\">Examples page</a>, &quot;Theme&quot; can be selected, and view the result directly.</p>\n<p>Since ECharts4, besides the original default theme, ECharts provide another two built-in themes, named &#39;<code class=\"codespan\">&#39;light&#39;</code> and <code class=\"codespan\">&#39;dark&#39;</code>. They can be used as follows:</p>\n<pre><code class=\"lang-js\">var chart = echarts.init(dom, &#39;light&#39;);\n</code></pre>\n<p>or</p>\n<pre><code class=\"lang-js\">var chart = echarts.init(dom, &#39;dark&#39;);\n</code></pre>\n<p>Other themes are not included in ECharts package by default, and need to load them ourselves if we want to use them. Themes can be visited and downloaded in <a href=\"https://echarts.apache.org/en/theme-builder.html\" target=\"_blank\">Theme Builder</a>. Theme can also be created or edited in it. The downloaded theme can be used as follows:</p>\n<p>If a theme is downloaded as a JSON file, we should register it by ourselves, for example:</p>\n<pre><code class=\"lang-js\">var xhr = new XMLHttpRequest();\n// Assume the theme name is &quot;vintage&quot;.\nxhr.open(&#39;GET&#39;, &#39;xxx/xxx/vintage.json&#39;, true);\nxhr.onload = function () {\n    var themeJSON = this.response;\n    echarts.registerTheme(&#39;vintage&#39;, JSON.parse(themeJSON))\n    var chart = echarts.init(dom, &#39;vintage&#39;);\n    // ...\n});\nxhr.send();\n</code></pre>\n<p>If a them is downloaded as a JS file, it will auto register itself:</p>\n<pre><code class=\"lang-js\">// Import the `vintage.js` file in HTML, then:\nvar chart = echarts.init(dom, &#39;vintage&#39;);\n// ...\n</code></pre>\n<p><br></p>\n<hr>\n<p><br></p>\n<p><strong>Palette</strong></p>\n<p>Pallettes can be given in option. They provide a group of colors, which will be auto picked by series and data. We can give a global palette, or exclusive pallette for certain series.</p>\n<pre><code class=\"lang-js\">option = {\n    // Global palette:\n    color: [&#39;#c23531&#39;,&#39;#2f4554&#39;, &#39;#61a0a8&#39;, &#39;#d48265&#39;, &#39;#91c7ae&#39;,&#39;#749f83&#39;,  &#39;#ca8622&#39;, &#39;#bda29a&#39;,&#39;#6e7074&#39;, &#39;#546570&#39;, &#39;#c4ccd3&#39;],\n\n    series: [{\n        type: &#39;bar&#39;,\n        // A palette only work for the series:\n        color: [&#39;#dd6b66&#39;,&#39;#759aa0&#39;,&#39;#e69d87&#39;,&#39;#8dc1a9&#39;,&#39;#ea7e53&#39;,&#39;#eedd78&#39;,&#39;#73a373&#39;,&#39;#73b9bc&#39;,&#39;#7289ab&#39;, &#39;#91ca8c&#39;,&#39;#f49f42&#39;],\n        ...\n    }, {\n        type: &#39;pie&#39;,\n        // A palette only work for the series:\n        color: [&#39;#37A2DA&#39;, &#39;#32C5E9&#39;, &#39;#67E0E3&#39;, &#39;#9FE6B8&#39;, &#39;#FFDB5C&#39;,&#39;#ff9f7f&#39;, &#39;#fb7293&#39;, &#39;#E062AE&#39;, &#39;#E690D1&#39;, &#39;#e7bcf3&#39;, &#39;#9d96f5&#39;, &#39;#8378EA&#39;, &#39;#96BFFF&#39;],\n        ...\n    }]\n}\n</code></pre>\n<p><br></p>\n<hr>\n<p><br></p>\n<p><strong>Customize style explicitly (itemStyle, lineStyle, areaStyle, label, ...)</strong></p>\n<p>It is a common way to set style explicitly. Throughout ECharts <a href=\"option.html\" target=\"_blank\">option</a>, style related options can be set in various place, including <a href=\"option.html#series.itemStyle\" target=\"_blank\">itemStyle</a>, <a href=\"option.html#series-line.lineStyle\" target=\"_blank\">lineStyle</a>, <a href=\"option.html#series-line.areaStyle\" target=\"_blank\">areaStyle</a>, <a href=\"option.html#series.label\" target=\"_blank\">label</a>, etc.</p>\n<p>Generally speaking, all of the built-in components and series follow the naming convention like <code class=\"codespan\">itemStyle</code>, <code class=\"codespan\">lineStyle</code>, <code class=\"codespan\">areaStyle</code>, <code class=\"codespan\">label</code> etc., although they may occur in different place according to different series or components.</p>\n<p>There is another article for style setting, <a href=\"#Customized%20Chart%20Styles\">Customized Chart Styles</a>.</p>\n<p><br></p>\n<hr>\n<p><br></p>\n<p><strong>Style of emphasis state</strong></p>\n<p>When mouse hovering a graphic elements, usually the emphasis style will be displayed. By default, the emphasis style is auto generated by the normal style. However they can be specified by <a href=\"option.html#series-scatter.emphasis\" target=\"_blank\">emphasis</a> property. The options in <a href=\"option.html#series-scatter.emphasis\" target=\"_blank\">emphasis</a> is the same as the ones for normal state, for example:</p>\n<pre><code class=\"lang-js\">option = {\n    series: {\n        type: &#39;scatter&#39;,\n\n        // Styles for normal state.\n        itemStyle: {\n            // Color of the point.\n            color: &#39;red&#39;\n        },\n        label: {\n            show: true,\n            // Text of labels.\n            formatter: &#39;This is a normal label.&#39;\n        },\n\n        // Styles for emphasis state.\n        emphasis: {\n            itemStyle: {\n                // Color in emphasis state.\n                color: &#39;blue&#39;\n            },\n            label: {\n                show: true,\n                // Text in emphasis.\n                formatter: &#39;This is a emphasis label.&#39;\n            }\n        }\n    }\n}\n</code></pre>\n<p>Notice: Before ECharts4, the emphasis style should be written like this:</p>\n<pre><code class=\"lang-js\">option = {\n    series: {\n        type: &#39;scatter&#39;,\n\n        itemStyle: {\n            // Styles for normal state.\n            normal: {\n                color: &#39;red&#39;\n            },\n            // Styles for emphasis state.\n            emphasis: {\n                color: &#39;blue&#39;\n            }\n        },\n\n        label: {\n            // Styles for normal state.\n            normal: {\n                show: true,\n                formatter: &#39;This is a normal label.&#39;\n            },\n            // Styles for emphasis state.\n            emphasis: {\n                show: true,\n                formatter: &#39;This is a emphasis label.&#39;\n            }\n        }\n    }\n}\n</code></pre>\n<p>The option format is still <strong>compatible</strong>, but not recommended. In fact, in most cases, users only set normal style, and use the default emphasis style. So since ECharts4, we support to write style without the &quot;normal&quot; term, which makes the option more simple and neat.</p>\n<p><br></p>\n<hr>\n<p><br></p>\n<p><strong>Visual encoding (visualMap component)</strong></p>\n<p><a href=\"option.html#visualMap\" target=\"_blank\">visualMap component</a> supports config the rule that mapping value to visual channel (color, size, ...). More details can be check in <a href=\"#Visual%20Map%20of%20Data\">Visual Map of Data</a>.</p>\n"},"Loading and Updating of Asynchronous Data":{"type":["*"],"description":"<h2 id=\"asynchronous-loading\">Asynchronous Loading</h2>\n<p>Data in <a href=\"#getting-started\">Get started</a> is directly filled in <code class=\"codespan\">setOption</code> after initialization, but in some cases, data may be filled after asynchronous loading. Data updating asynchronously in Apache ECharts<sup>TM</sup> is very easy. After initialization, you can pass in data and configuration item through <code class=\"codespan\">setOption</code> after data obtained through  jQuery and other tools at any time.</p>\n<pre><code class=\"lang-js\">var myChart = echarts.init(document.getElementById(&#39;main&#39;));\n\n$.get(&#39;data.json&#39;).done(function (data) {\n    myChart.setOption({\n        title: {\n            text: &#39;asynchronous data loading example&#39;\n        },\n        tooltip: {},\n        legend: {\n            data:[&#39;Sales&#39;]\n        },\n        xAxis: {\n            data: data.categories\n        },\n        yAxis: {},\n        series: [{\n            name: &#39;Sales&#39;,\n            type: &#39;bar&#39;,\n            data: data.data\n        }]\n    });\n});\n</code></pre>\n<p>Or, you may set other styles, displaying an empty rectangular axis, and then fill in data when ready.</p>\n<pre><code class=\"lang-js\">var myChart = echarts.init(document.getElementById(&#39;main&#39;));\n// show title. legend and empty axis\nmyChart.setOption({\n    title: {\n        text: &#39;asynchronous data loading example&#39;\n    },\n    tooltip: {},\n    legend: {\n        data:[&#39;Sales&#39;]\n    },\n    xAxis: {\n        data: []\n    },\n    yAxis: {},\n    series: [{\n        name: &#39;Sales&#39;,\n        type: &#39;bar&#39;,\n        data: []\n    }]\n});\n\n// Asynchronous data loading\n$.get(&#39;data.json&#39;).done(function (data) {\n    // fill in data\n    myChart.setOption({\n        xAxis: {\n            data: data.categories\n        },\n        series: [{\n            // find series by name\n            name: &#39;Sales&#39;,\n            data: data.data\n        }]\n    });\n});\n</code></pre>\n<p>For example:</p>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=doc-example/tutorial-async&edit=1&reset=1\" width=\"400\" height=\"300\" ></iframe>\n\n\n<p>In ECharts, updating data need to find the corresponding series through <code class=\"codespan\">name</code>. In the above example, updating can be performed correctly according to series order if <code class=\"codespan\">name</code> is not defined. But in most cases, it is recommended to update data with series <code class=\"codespan\">name</code> information.</p>\n<h2 id=\"loading-animation\">Loading Animation</h2>\n<p>If data loading time is too long, an empty axis on the canvas may confuse users. In this case, a loading animation is needed to tell the user that it&#39;s still loading.</p>\n<p>ECharts provides a simple loading animation by default. You only need <a href=\"api.html#echartsInstance.showLoading\" target=\"_blank\">showLoading</a> to show, and then use <a href=\"api.html#echartsInstance.hideLoading\" target=\"_blank\">hideLoading</a> to hide loading animation after data loading.</p>\n<pre><code class=\"lang-js\">myChart.showLoading();\n$.get(&#39;data.json&#39;).done(function (data) {\n    myChart.hideLoading();\n    myChart.setOption(...);\n});\n</code></pre>\n<p>Effects are as followed:</p>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=doc-example/tutorial-loading&edit=1&reset=1\" width=\"400\" height=\"300\" ></iframe>\n\n\n<h2 id=\"dynamic-data-updating\">Dynamic Data Updating</h2>\n<p>ECharts is driven by data. Change of data changes the presentation of chart, therefore, implementing dynamic data updating is extremely easy.</p>\n<p>All data updating are through <a href=\"#api.html#echartsInstance.setOption\">setOption</a>. You only need to get data as you wish, fill in data to <a href=\"#api.html#echartsInstance.setOption\">setOption</a> without considering the changes brought by data, ECharts will find the difference between two group of data and present the difference through proper animation.</p>\n<blockquote>\n<p>In ECharts 3, addData in ECharts 2 is removed.If a single data needs to be added, you can first data.push(value) and then setOption.</p>\n</blockquote>\n<p>See details in the following example:</p>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=doc-example/tutorial-dynamic-data&edit=1&reset=1\" width=\"400\" height=\"300\" ></iframe>\n\n\n\n"},"Dataset":{"type":["*"],"description":"<p><code class=\"codespan\">dataset</code> component is published since Apache ECharts<sup>TM</sup> 4. <code class=\"codespan\">dataset</code> brings convenience in data management separated with styles and enables data reuse by different series. More importantly, it enables data encoding from data to visual, which brings convenience in some scenarios.</p>\n<p>Before ECharts 4, data was only able to declared in each series, for example:</p>\n<pre><code class=\"lang-js\">option = {\n    xAxis: {\n        type: &#39;category&#39;,\n        data: [&#39;Matcha Latte&#39;, &#39;Milk Tea&#39;, &#39;Cheese Cocoa&#39;, &#39;Walnut Brownie&#39;]\n    },\n    yAxis: {},\n    series: [\n        {\n            type: &#39;bar&#39;,\n            name: &#39;2015&#39;,\n            data: [89.3, 92.1, 94.4, 85.4]\n        },\n        {\n            type: &#39;bar&#39;,\n            name: &#39;2016&#39;,\n            data: [95.8, 89.4, 91.2, 76.9]\n        },\n        {\n            type: &#39;bar&#39;,\n            name: &#39;2017&#39;,\n            data: [97.7, 83.1, 92.5, 78.1]\n        }\n    ]\n}\n</code></pre>\n<p>This approach is easy to be understand and is flexible when some series needs special data definitions. But the shortcomings are also obvious: some data extra works are usually needed to split the original data to each series, and it not supports sharing data in different series, moreover, it is not good for encode.</p>\n<p>ECharts4 starts to provide <code class=\"codespan\">dataset</code> component, which brings benefits below:</p>\n<ul>\n<li>Benefit from <code class=\"codespan\">dataset</code>, we can follow the common methodology of data visualization: based on data, specify the mapping (via the option <a href=\"option.html#series.encode\" target=\"_blank\">encode</a>) from data to visual.</li>\n<li>Data can be managed and configured separately from other configurations.</li>\n<li>Data can be reused by different series and components.</li>\n<li>Support more common data format (like 2d-array, object-array), to avoid data transform works for users.</li>\n</ul>\n<h2 id=\"get-started\">Get started</h2>\n<p>This is a simplest example of <code class=\"codespan\">dataset</code>:</p>\n<pre><code class=\"lang-js\">option = {\n    legend: {},\n    tooltip: {},\n    dataset: {\n        // Provide data.\n        source: [\n            [&#39;product&#39;, &#39;2015&#39;, &#39;2016&#39;, &#39;2017&#39;],\n            [&#39;Matcha Latte&#39;, 43.3, 85.8, 93.7],\n            [&#39;Milk Tea&#39;, 83.1, 73.4, 55.1],\n            [&#39;Cheese Cocoa&#39;, 86.4, 65.2, 82.5],\n            [&#39;Walnut Brownie&#39;, 72.4, 53.9, 39.1]\n        ]\n    },\n    // Declare X axis, which is a category axis, mapping\n    // to the first column by default.\n    xAxis: {type: &#39;category&#39;},\n    // Declare Y axis, which is a value axis.\n    yAxis: {},\n    // Declare several series, each of them mapped to a\n    // column of the dataset by default.\n    series: [\n        {type: &#39;bar&#39;},\n        {type: &#39;bar&#39;},\n        {type: &#39;bar&#39;}\n    ]\n}\n</code></pre>\n<p>This is the result:</p>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=dataset-simple0&edit=1&reset=1\" width=\"500\" height=\"300\" ></iframe>\n\n\n<p>Or the common format object-array is also supported:</p>\n<pre><code class=\"lang-js\">option = {\n    legend: {},\n    tooltip: {},\n    dataset: {\n        // Here the declared `dimensions` is mainly for providing the order of\n        // the dimensions, which enables ECharts to apply the default mapping\n        // from dimensions to axes.\n        // Alternatively, we can declare `series.encode` to specify the mapping,\n        // which will be introduced later.\n        dimensions: [&#39;product&#39;, &#39;2015&#39;, &#39;2016&#39;, &#39;2017&#39;],\n        source: [\n            {product: &#39;Matcha Latte&#39;, &#39;2015&#39;: 43.3, &#39;2016&#39;: 85.8, &#39;2017&#39;: 93.7},\n            {product: &#39;Milk Tea&#39;, &#39;2015&#39;: 83.1, &#39;2016&#39;: 73.4, &#39;2017&#39;: 55.1},\n            {product: &#39;Cheese Cocoa&#39;, &#39;2015&#39;: 86.4, &#39;2016&#39;: 65.2, &#39;2017&#39;: 82.5},\n            {product: &#39;Walnut Brownie&#39;, &#39;2015&#39;: 72.4, &#39;2016&#39;: 53.9, &#39;2017&#39;: 39.1}\n        ]\n    },\n    xAxis: {type: &#39;category&#39;},\n    yAxis: {},\n    series: [\n        {type: &#39;bar&#39;},\n        {type: &#39;bar&#39;},\n        {type: &#39;bar&#39;}\n    ]\n};\n</code></pre>\n<h2 id=\"mapping-from-data-to-graphic\">Mapping from data to graphic</h2>\n<p>In this tutorial, we make charts following this methodology: base on data, config the rule to map data to graphic, namely, encode the data to graphic.</p>\n<p>Generally, this mapping can be performed:</p>\n<ul>\n<li>Configure whether columns or rows of a dataset will mapped to series, namely, the series layout on the columns or rows of a dataset. This can be specified by <a href=\"option.html#series.seriesLayoutBy\" target=\"_blank\">series.seriesLayoutBy</a>. <code class=\"codespan\">&#39;column&#39;</code> is the default value.</li>\n<li>Configure the mapping rule from dimensions (a dimension means a column/row) to axes in coordinate system, tooltip, labels, color, symbol size, etc. This can be specified by <a href=\"option.html#series.encode\" target=\"_blank\">series.encode</a> and <a href=\"option.html#visualMap\" target=\"_blank\">visualMap</a> (if visual encoding is required). The example above does not give a mapping rule, so ECharts make default mapping by common sense: because x axis is a category axis, the first column is mapped to the x axis, and each series use each subsequent column in order.</li>\n</ul>\n<p>Let&#39;s illustrate them in detail below.</p>\n<h2 id=\"mapping-by-column-or-row\">Mapping by column or row</h2>\n<p>Giving dataset, users can configure whether columns or rows of a dataset will be mapped to series, namely, the series layout on the columns or rows of a dataset. This can be specified by <a href=\"option.html#series.seriesLayoutBy\" target=\"_blank\">series.seriesLayoutBy</a>. The optional values are:</p>\n<ul>\n<li>&#39;column&#39;: series are positioned on each columns of the dataset. Default value.</li>\n<li>&#39;row&#39;: series are positioned on each row of the dataset.</li>\n</ul>\n<p>See the example below:</p>\n<pre><code class=\"lang-js\">option = {\n    legend: {},\n    tooltip: {},\n    dataset: {\n        source: [\n            [&#39;product&#39;, &#39;2012&#39;, &#39;2013&#39;, &#39;2014&#39;, &#39;2015&#39;],\n            [&#39;Matcha Latte&#39;, 41.1, 30.4, 65.1, 53.3],\n            [&#39;Milk Tea&#39;, 86.5, 92.1, 85.7, 83.1],\n            [&#39;Cheese Cocoa&#39;, 24.1, 67.2, 79.5, 86.4]\n        ]\n    },\n    xAxis: [\n        {type: &#39;category&#39;, gridIndex: 0},\n        {type: &#39;category&#39;, gridIndex: 1}\n    ],\n    yAxis: [\n        {gridIndex: 0},\n        {gridIndex: 1}\n    ],\n    grid: [\n        {bottom: &#39;55%&#39;},\n        {top: &#39;55%&#39;}\n    ],\n    series: [\n        // These series is in the first cartesian (grid), and each\n        // is mapped to a row.\n        {type: &#39;bar&#39;, seriesLayoutBy: &#39;row&#39;},\n        {type: &#39;bar&#39;, seriesLayoutBy: &#39;row&#39;},\n        {type: &#39;bar&#39;, seriesLayoutBy: &#39;row&#39;},\n        // These series is in the second cartesian (grid), and each\n        // is mapped to a column.\n        {type: &#39;bar&#39;, xAxisIndex: 1, yAxisIndex: 1},\n        {type: &#39;bar&#39;, xAxisIndex: 1, yAxisIndex: 1},\n        {type: &#39;bar&#39;, xAxisIndex: 1, yAxisIndex: 1},\n        {type: &#39;bar&#39;, xAxisIndex: 1, yAxisIndex: 1}\n    ]\n}\n</code></pre>\n<p>This is the result:</p>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=dataset-series-layout-by&edit=1&reset=1\" width=\"800\" height=\"600\" ></iframe>\n\n\n\n<h2 id=\"dimension\">Dimension</h2>\n<p>Before introducing <code class=\"codespan\">encode</code>, we should clarify the concept of <code class=\"codespan\">dimension</code>.</p>\n<p>Most of common charts describe data in the format of &quot;two-dimensions table&quot; (note that the meaning of the word &quot;dimension&quot; in &quot;two-dimension table&quot; is not the same as the dimensions in ECharts. \bIn order not to be confusing, we use &quot;2d-table&quot;, &quot;2d-array&quot; below). In the examples above, we use 2d-array to carry the 2d-table. When we set <code class=\"codespan\">seriesLayoutBy</code> as <code class=\"codespan\">&#39;column&#39;</code>, namely, mapping columns to series, each column is called a dimension, and each row is a data item. When we set <code class=\"codespan\">seriesLayoutBy</code> as <code class=\"codespan\">&#39;row&#39;</code>, namely, mapping rows to series, each row is called a dimension, and each column is a data item.</p>\n<p>Dimension can have its name to displayed on charts. Dimension name can be defined on the first row/column. Take the code above as an example, <code class=\"codespan\">&#39;score&#39;</code>、<code class=\"codespan\">&#39;amount&#39;</code>、<code class=\"codespan\">&#39;product&#39;</code> are dimension names, and data start from the second row. By default ECharts auto detect whether the first row/column of <code class=\"codespan\">dataset.source</code> is dimension name or data. Use can also set <code class=\"codespan\">dataset.sourceHeader</code> as <code class=\"codespan\">true</code> to mandatorily specify the first row/column is dimension name, or set as <code class=\"codespan\">false</code> to indicate the data start from the first row/column.</p>\n<p>The definitions of the dimensions can also be provided separately in <code class=\"codespan\">dataset.dimensions</code> or <code class=\"codespan\">series.dimensions</code>, where not only dimension name, but also dimension type can be specified:</p>\n<pre><code class=\"lang-js\">var option1 = {\n    dataset: {\n        dimensions: [\n            // Each item can be object or string.\n            {name: &#39;score&#39;},\n            // A string indicates the dimension name.\n            &#39;amount&#39;,\n            // Dimension type can be specified.\n            {name: &#39;product&#39;, type: &#39;ordinal&#39;}\n        ],\n        source: [...]\n    },\n    ...\n};\n\nvar option2 = {\n    dataset: {\n        source: [...]\n    },\n    series: {\n        type: &#39;line&#39;,\n        // Dimensions declared in series will be adapted with higher priority.\n        dimensions: [\n            null, // Set as null means we dont want to set dimension name.\n            &#39;amount&#39;,\n            {name: &#39;product&#39;, type: &#39;ordinal&#39;}\n        ]\n    },\n    ...\n};\n</code></pre>\n<p>Generally, we do not need to set dimensions types, because it can be auto detected based on data by ECharts. But in some cases, for example, the data is empty, the detection might not be accurate, where dimension type can be set manually.</p>\n<p>The optional values of dimension types can be:</p>\n<ul>\n<li><code class=\"codespan\">&#39;number&#39;</code>: Normal data, default value.</li>\n<li><code class=\"codespan\">&#39;ordinal&#39;</code>: Represents string data like category data or text data. ECharts will auto detect them by default. They can be set manually if the detection fail.</li>\n<li><code class=\"codespan\">&#39;time&#39;</code>: Represents time data, where it is supported that parse time string to timestamp. For example, if users need to parse &#39;2017-05-10&#39; to timestamp, it should be set as <code class=\"codespan\">time</code> type. If the dimension is used on a time axis (<a href=\"option.html#xAxis.type\" target=\"_blank\">axis.type</a> is <code class=\"codespan\">&#39;time&#39;</code>), it will be auto set to <code class=\"codespan\">time</code> type. The supported time string is listed in <a href=\"option.html#series.data\" target=\"_blank\">data</a>.</li>\n<li><code class=\"codespan\">&#39;float&#39;</code>: If set as <code class=\"codespan\">&#39;float&#39;</code>, it will be stored in <code class=\"codespan\">TypedArray</code>, which is good for performance optimization.</li>\n<li><code class=\"codespan\">&#39;int&#39;</code>: If set as <code class=\"codespan\">&#39;int&#39;</code>, it will be stored in <code class=\"codespan\">TypedArray</code>, which is good for performance optimization.</li>\n</ul>\n<h2 id=\"mapping-from-data-to-graphic-encode-\">Mapping from data to graphic (encode)</h2>\n<p>Having the concept of dimension clarified, we can use <a href=\"option.html#series.encode\" target=\"_blank\">encode</a> to map data to graphic:</p>\n<pre><code class=\"lang-js\">var option = {\n    dataset: {\n        source: [\n            [&#39;score&#39;, &#39;amount&#39;, &#39;product&#39;],\n            [89.3, 58212, &#39;Matcha Latte&#39;],\n            [57.1, 78254, &#39;Milk Tea&#39;],\n            [74.4, 41032, &#39;Cheese Cocoa&#39;],\n            [50.1, 12755, &#39;Cheese Brownie&#39;],\n            [89.7, 20145, &#39;Matcha Cocoa&#39;],\n            [68.1, 79146, &#39;Tea&#39;],\n            [19.6, 91852, &#39;Orange Juice&#39;],\n            [10.6, 101852, &#39;Lemon Juice&#39;],\n            [32.7, 20112, &#39;Walnut Brownie&#39;]\n        ]\n    },\n    xAxis: {},\n    yAxis: {type: &#39;category&#39;},\n    series: [\n        {\n            type: &#39;bar&#39;,\n            encode: {\n                // Map dimension &quot;amount&quot; to the X axis.\n                x: &#39;amount&#39;,\n                // Map dimension &quot;product&quot; to the Y axis.\n                y: &#39;product&#39;\n            }\n        }\n    ]\n};\n</code></pre>\n<p>This is the result:</p>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=doc-example/dataset-encode-simple0&edit=1&reset=1\" width=\"500\" height=\"300\" ></iframe>\n\n\n\n<p>The basic structure of <a href=\"option.html#series.encode\" target=\"_blank\">encode</a> is illustrated as follows, where the left part of colon is the name of axis like <code class=\"codespan\">&#39;x&#39;</code>, <code class=\"codespan\">&#39;y&#39;</code>, <code class=\"codespan\">&#39;radius&#39;</code>, <code class=\"codespan\">&#39;angle&#39;</code> or some special reserved names like &quot;tooltip&quot;, &quot;itemName&quot; etc., and the right part of the colon is the dimension names or dimension indices (based on 0). One or more dimensions can be specified. Usually not all of mappings need to be specified, only specify needed ones.</p>\n<p>The properties available in <code class=\"codespan\">encode</code> listed as follows:</p>\n<pre><code class=\"lang-js\">// In any of the series and coordinate systems,\n// these properties are available:\nencode: {\n    // Display dimension &quot;product&quot; and &quot;score&quot; in the tooltip.\n    tooltip: [&#39;product&#39;, &#39;score&#39;]\n    // Set the series name as the concat of the names of dimensions[1] and dimensions[3].\n    // (sometimes the dimension names are too long to type in series.name manually).\n    seriesName: [1, 3],\n    // Using dimensions[2] as the id of each data item. This is useful when dynamically\n    // update data by `chart.setOption()`, where the new and old data item can be\n    // corresponded by id, by which the appropriate animation can be performed when updating.\n    itemId: 2,\n    // Using dimensions[3] as the name of each data item. This is useful in charts like\n    // &#39;pie&#39;, &#39;funnel&#39;, where data item name can be displayed in legend.\n    itemName: 3\n}\n\n// These properties only work in cartesian(grid) coordinate system:\nencode: {\n    // Map dimensions[1], dimensions[5] and dimension &quot;score&quot; to the X axis.\n    x: [1, 5, &#39;score&#39;],\n    // Map dimensions[0] to the Y axis.\n    y: 0\n}\n\n// These properties only work in polar coordinate system:\nencode: {\n    radius: 3,\n    angle: 2,\n    ...\n}\n\n// These properties only work in geo coordinate system:\nencode: {\n    lng: 3,\n    lat: 2\n}\n\n// For some type of series that are not in any coordinate system,\n// like &#39;pie&#39;, &#39;funnel&#39; etc.:\nencode: {\n    value: 3\n}\n</code></pre>\n<p>There is an other example for <code class=\"codespan\">encode</code>:</p>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=dataset-encode1&edit=1&reset=1\" width=\"800\" height=\"600\" ></iframe>\n\n\n\n\n\n<h2 id=\"visual-encoding-color-symbol-etc-\">Visual encoding (color, symbol, etc.)</h2>\n<p>We can use <a href=\"option.html#visualMap\" target=\"_blank\">visualMap</a> component to map data to visual channel like color, symbol size, etc.. More info about it can be checked in its <a href=\"option.html#visualMap\" target=\"_blank\">doc</a>.</p>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=dataset-encode0&edit=1&reset=1\" width=\"500\" height=\"400\" ></iframe>\n\n\n\n\n<h2 id=\"default-encoding\">Default encoding</h2>\n<p>For some common cases (line chart, bar chart, scatter plot, candlestick, pie, funnel, etc.), EChart provides default encoding settings, by which chart will be displayed even if no <code class=\"codespan\">encode</code> option is specified. (If <code class=\"codespan\">encode</code> option is specified, default encoding will not be applied.) The rule of default encoding should not be too complicated. Basically it is:</p>\n<ul>\n<li>In coordinate system (like cartesian(grid), polar):<ul>\n<li>If category axis (i.e., axis.type is <code class=\"codespan\">&#39;category&#39;</code>) exists, map the first column/row to the axis, and each series use a following column/row.</li>\n<li>If no category axis exists, and the coordinate system contains two axis (like X Y in cartesian), each series use two columns/rows, one for a axis.</li>\n</ul>\n</li>\n<li>If no coordinate system (like pie chart):<ul>\n<li>Use the first column/row as item name, and the second column/row as item value.</li>\n</ul>\n</li>\n</ul>\n<p>If the default rule does not meet the requirements, configure the <code class=\"codespan\">encode</code> yourself please.</p>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=dataset-default&edit=1&reset=1\" width=\"800\" height=\"400\" ></iframe>\n\n\n\n<h2 id=\"q-a\">Q &amp; A</h2>\n<p>Q: How to map the third column to X axis, and map the fifth column to Y axis?</p>\n<p>A:</p>\n<pre><code class=\"lang-js\">series: {\n    // Notice that the dimension index is based on 0,\n    // thus the third column is dimensions[2].\n    encode: {x: 2, y: 4},\n    ...\n}\n</code></pre>\n<p>Q: How to map the third row th X axis, and map the fifth row to Y axis?</p>\n<p>A:</p>\n<pre><code class=\"lang-js\">series: {\n    encode: {x: 2, y: 4},\n    seriesLayoutBy: &#39;row&#39;,\n    ...\n}\n</code></pre>\n<p>Q: How to use the values in the second column in label.</p>\n<p>A:\nThe <a href=\"option.html#series.label.formatter\" target=\"_blank\">label.formatter</a> supports refer value in a certain dimension. For example:</p>\n<pre><code class=\"lang-js\">series: {\n    label: {\n        // `&#39;{@score}&#39;` means use the value in the &quot;score&quot; dimension.\n        // `&#39;{@[4]}&#39;` means use the value in dimensions[4].\n        formatter: &#39;aaa{@product}bbb{@score}ccc{@[4]}ddd&#39;\n    }\n}\n</code></pre>\n<p>Q: How to display the second column and the third column in tooltip?</p>\n<p>A:</p>\n<pre><code class=\"lang-js\">series: {\n    encode: {\n        tooltip: [1, 2]\n        ...\n    },\n    ...\n}\n</code></pre>\n<p>Q: If there is no dimension name in dataset.source, how to give dimension name?</p>\n<p>A:</p>\n<pre><code class=\"lang-js\">dataset: {\n    dimensions: [&#39;score&#39;, &#39;amount&#39;],\n    source: [\n        [89.3, 3371],\n        [92.1, 8123],\n        [94.4, 1954],\n        [85.4, 829]\n    ]\n}\n</code></pre>\n<p>Q: How to encode the third column in bubble size in bubble plot?</p>\n<p>A:</p>\n<pre><code class=\"lang-js\">var option = {\n    dataset: {\n        source: [\n            [12, 323, 11.2],\n            [23, 167, 8.3],\n            [81, 284, 12],\n            [91, 413, 4.1],\n            [13, 287, 13.5]\n        ]\n    },\n    // Use visualMap to perform visual encoding.\n    visualMap: {\n        show: false,\n        dimension: 2, // Encode the third column.\n        min: 2, // Min value is required in visualMap component.\n        max: 15, // Max value is required in visualMap component.\n        inRange: {\n            // The range of bubble size, from 5 pixel to 60 pixel.\n            symbolSize: [5, 60]\n        }\n    },\n    xAxis: {},\n    yAxis: {},\n    series: {\n        type: &#39;scatter&#39;\n    }\n};\n</code></pre>\n<p>Q: We have specified <code class=\"codespan\">encode</code>, but why it does not work?</p>\n<p>A: Maybe we can try to check typo, for example, the dimension name is <code class=\"codespan\">&#39;Life Expectancy&#39;</code>, be we typed <code class=\"codespan\">&#39;Life Expectency&#39;</code> in <code class=\"codespan\">encode</code> option.</p>\n<h2 id=\"various-formats-in-dataset\">Various formats in dataset</h2>\n<p>In lots of cases, data is described in 2d-table. For example, some data processing software like MS Excel, Numbers are based on 2d-table. The data can be exported as JSON format and input to <code class=\"codespan\">dataset.source</code>.</p>\n<blockquote>\n<p>Some csv tools can be used to export the table data to JSON, for example, <a href=\"https://github.com/d3/d3-dsv\" target=\"_blank\">dsv</a> or <a href=\"https://github.com/mholt/PapaParse\" target=\"_blank\">PapaParse</a>.</p>\n</blockquote>\n<p>In common used data transfer formats in JavaScript, 2d-array is a good choice to carry table data, which has been illustrated in the examples above.</p>\n<p>Besides, 2d-array, <code class=\"codespan\">dataset</code> also support key-value format as follows, which is also commonly used. But notice, the option <a href=\"option.html#series.seriesLayoutBy\" target=\"_blank\">seriesLayoutBy</a> is not supported in this format.</p>\n<pre><code class=\"lang-js\">dataset: [{\n    // Row based key-value format, namely, object array, is a commonly used format.\n    source: [\n        {product: &#39;Matcha Latte&#39;, count: 823, score: 95.8},\n        {product: &#39;Milk Tea&#39;, count: 235, score: 81.4},\n        {product: &#39;Cheese Cocoa&#39;, count: 1042, score: 91.2},\n        {product: &#39;Walnut Brownie&#39;, count: 988, score: 76.9}\n    ]\n}, {\n    // Column based key-value format is also supported.\n    source: {\n        &#39;product&#39;: [&#39;Matcha Latte&#39;, &#39;Milk Tea&#39;, &#39;Cheese Cocoa&#39;, &#39;Walnut Brownie&#39;],\n        &#39;count&#39;: [823, 235, 1042, 988],\n        &#39;score&#39;: [95.8, 81.4, 91.2, 76.9]\n    }\n}]\n</code></pre>\n<h2 id=\"multiple-datasets-and-references\">Multiple datasets and references</h2>\n<p>Multiple datasets can be defined, and series can refer them by <a href=\"option.html#series.datasetIndex\" target=\"_blank\">series.datasetIndex</a>.</p>\n<pre><code class=\"lang-js\">var option = {\n    dataset: [{\n        source: [...],\n    }, {\n        source: [...]\n    }, {\n        source: [...]\n    }],\n    series: [{\n        // Use the third dataset.\n        datasetIndex: 2\n    }, {\n        // Use the second dataset.\n        datasetIndex: 1\n    }]\n}\n</code></pre>\n<h2 id=\"data-transform\">Data transform</h2>\n<p><code class=\"codespan\">Data transform</code> has been supported since Apache ECharts<sup>TM</sup> 5. In echarts, the term <code class=\"codespan\">data transform</code> means that generate new data from user provided source data and transform functions. This feature is enable users to process data in declarative way, and provides users some common &quot;transform functions&quot; to make that kind of tasks &quot;out-of-the-box&quot;.</p>\n<p>See the details of data transform in this <a href=\"#data-transform\">doc</a>.</p>\n<h2 id=\"echarts3-data-setting-approach-series-data-can-be-used-normally\">ECharts3 data setting approach (series.data) can be used normally</h2>\n<p>The data setting approach before ECharts4 can still be used normally. If a series has declared <a href=\"option.html#series.data\" target=\"_blank\">series.data</a>, it will be used but not <code class=\"codespan\">dataset</code>.</p>\n<pre><code class=\"lang-js\">{\n    xAxis: {\n        type: &#39;category&#39;\n        data: [&#39;Matcha Latte&#39;, &#39;Milk Tea&#39;, &#39;Cheese Cocoa&#39;, &#39;Walnut Brownie&#39;]\n    },\n    yAxis: {},\n    series: [{\n        type: &#39;bar&#39;,\n        name: &#39;2015&#39;,\n        data: [89.3, 92.1, 94.4, 85.4]\n    }, {\n        type: &#39;bar&#39;,\n        name: &#39;2016&#39;,\n        data: [95.8, 89.4, 91.2, 76.9]\n    }, {\n        type: &#39;bar&#39;,\n        name: &#39;2017&#39;,\n        data: [97.7, 83.1, 92.5, 78.1]\n    }]\n}\n</code></pre>\n<p>In fact, setting data via <a href=\"option.html#series.data\" target=\"_blank\">series.data</a> is not deprecated and useful in some cases. For example, for some charts, like <a href=\"option.html#series-treemap\" target=\"_blank\">treemap</a>, <a href=\"option.html#series-graph\" target=\"_blank\">graph</a>, <a href=\"option.html#series-lines\" target=\"_blank\">lines</a>, that do not apply table data, <code class=\"codespan\">dataset</code> is not supported for yet. Moreover, for the case of large data rendering (for example, millions of data), <a href=\"api.html#echartsInstance.appendData\" target=\"_blank\">appendData</a> is probably needed to load data incrementally. <code class=\"codespan\">dataset</code> is not supported in the case.</p>\n<h2 id=\"data-transform\">Data transform</h2>\n<p>See <a href=\"#Data%20Transform\">data transform</a>.</p>\n<h2 id=\"others\">Others</h2>\n<p>Currently, not all types of series support dataset. Series that support dataset includes:</p>\n<p><code class=\"codespan\">line</code>, <code class=\"codespan\">bar</code>, <code class=\"codespan\">pie</code>, <code class=\"codespan\">scatter</code>, <code class=\"codespan\">effectScatter</code>, <code class=\"codespan\">parallel</code>, <code class=\"codespan\">candlestick</code>, <code class=\"codespan\">map</code>, <code class=\"codespan\">funnel</code>, <code class=\"codespan\">custom</code>.</p>\n<p>More types of series will support dataset in our further work.</p>\n<p>Finally, this is an example, multiple series sharing one <code class=\"codespan\">dataset</code> and having interactions:</p>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=dataset-link&edit=1&reset=1\" width=\"800\" height=\"500\" ></iframe>\n\n\n\n\n"},"Data Transform":{"type":["*"],"description":"<p><code class=\"codespan\">Data transform</code> has been supported since Apache ECharts<sup>TM</sup> 5. In echarts, the term <code class=\"codespan\">data transform</code> means that generate new data from user provided source data and transform functions. both This feature is enable users to process data in declarative way, and provides users some common &quot;transform functions&quot; to make that kind of tasks &quot;out-of-the-box&quot;. (For consistency in the context, the noun form of the word we keep using the &quot;transform&quot; rather than &quot;transformation&quot;).</p>\n<p>The abstract formula of data transform is: <code class=\"codespan\">outData = f(inputData)</code>, where the transform function <code class=\"codespan\">f</code> can be like <code class=\"codespan\">filter</code>, <code class=\"codespan\">sort</code>, <code class=\"codespan\">regression</code>, <code class=\"codespan\">boxplot</code>, <code class=\"codespan\">cluster</code>, <code class=\"codespan\">aggregate</code>(todo) ...\nWith the help of those transform methods, users can be implements the features like:</p>\n<ul>\n<li>Partition data into multiple series.</li>\n<li>Make some statistics and visualize the result.</li>\n<li>Adapt some visualization algorithms to data and display the result.</li>\n<li>Sort data.</li>\n<li>Remove or choose some kind of empty or special datums.</li>\n<li>...</li>\n</ul>\n<h2 id=\"get-started-to-data-transform\">Get started to data transform</h2>\n<p>In echarts, data transform is implemented based on the concept of <a href=\"#dataset\">dataset</a>. A <a href=\"option.html#dataset.transform\" target=\"_blank\">dataset.transform</a> can be configured in a dataset instance to indicate that this dataset is to be generated from this <code class=\"codespan\">transform</code>. For example:</p>\n<pre><code class=\"lang-js\">var option = {\n    dataset: [{\n        // This dataset is on `datasetIndex: 0`.\n        source: [\n            [&#39;Product&#39;, &#39;Sales&#39;, &#39;Price&#39;, &#39;Year&#39;],\n            [&#39;Cake&#39;, 123, 32, 2011],\n            [&#39;Cereal&#39;, 231, 14, 2011],\n            [&#39;Tofu&#39;, 235, 5, 2011],\n            [&#39;Dumpling&#39;, 341, 25, 2011],\n            [&#39;Biscuit&#39;, 122, 29, 2011],\n            [&#39;Cake&#39;, 143, 30, 2012],\n            [&#39;Cereal&#39;, 201, 19, 2012],\n            [&#39;Tofu&#39;, 255, 7, 2012],\n            [&#39;Dumpling&#39;, 241, 27, 2012],\n            [&#39;Biscuit&#39;, 102, 34, 2012],\n            [&#39;Cake&#39;, 153, 28, 2013],\n            [&#39;Cereal&#39;, 181, 21, 2013],\n            [&#39;Tofu&#39;, 395, 4, 2013],\n            [&#39;Dumpling&#39;, 281, 31, 2013],\n            [&#39;Biscuit&#39;, 92, 39, 2013],\n            [&#39;Cake&#39;, 223, 29, 2014],\n            [&#39;Cereal&#39;, 211, 17, 2014],\n            [&#39;Tofu&#39;, 345, 3, 2014],\n            [&#39;Dumpling&#39;, 211, 35, 2014],\n            [&#39;Biscuit&#39;, 72, 24, 2014],\n        ],\n        // id: &#39;a&#39;\n    }, {\n        // This dataset is on `datasetIndex: 1`.\n        // A `transform` is configured to indicate that the\n        // final data of this dataset is transformed via this\n        // transform function.\n        transform: {\n            type: &#39;filter&#39;,\n            config: { dimension: &#39;Year&#39;, value: 2011 }\n        },\n        // There can be optional properties `fromDatasetIndex` or `fromDatasetId`\n        // to indicate that where is the input data of the transform from.\n        // For example, `fromDatasetIndex: 0` specify the input data is from\n        // the dataset on `datasetIndex: 0`, or `fromDatasetId: &#39;a&#39;` specify the\n        // input data is from the dataset having `id: &#39;a&#39;`.\n        // [DEFAULT_RULE]\n        // If both `fromDatasetIndex` and `fromDatasetId` are omitted,\n        // `fromDatasetIndex: 0` are used by default.\n    }, {\n        // This dataset is on `datasetIndex: 2`.\n        // Similarly, if neither `fromDatasetIndex` nor `fromDatasetId` is\n        // specified, `fromDatasetIndex: 0` is used by default\n        transform: {\n            // The &quot;filter&quot; transform filters and gets data items only match\n            // the given condition in property `config`.\n            type: &#39;filter&#39;,\n            // Transforms has a property `config`. In this &quot;filter&quot; transform,\n            // the `config` specify the condition that each result data item\n            // should be satisfied. In this case, this transform get all of\n            // the data items that the value on dimension &quot;Year&quot; equals to 2012.\n            config: { dimension: &#39;Year&#39;, value: 2012 }\n        }\n    }, {\n        // This dataset is on `datasetIndex: 3`\n        transform: {\n            type: &#39;filter&#39;,\n            config: { dimension: &#39;Year&#39;, value: 2013 }\n        }\n    }],\n    series: [{\n        type: &#39;pie&#39;, radius: 50, center: [&#39;25%&#39;, &#39;50%&#39;],\n        // In this case, each &quot;pie&quot; series reference to a dataset that has\n        // the result of its &quot;filter&quot; transform.\n        datasetIndex: 1\n    }, {\n        type: &#39;pie&#39;, radius: 50, center: [&#39;50%&#39;, &#39;50%&#39;],\n        datasetIndex: 2\n    }, {\n        type: &#39;pie&#39;, radius: 50, center: [&#39;75%&#39;, &#39;50%&#39;],\n        datasetIndex: 3\n    }]\n};\n</code></pre>\n<p>The case shows how we get three pies, representing the data from 2011, 2012, 2013.</p>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=data-transform-multiple-pie&reset=1&edit=1\" width=\"800\" height=\"300\" ></iframe>\n\n\n\n<p>Let&#39;s summarize the key points of using data transform:</p>\n<ul>\n<li>Generate new data from existing declared data via the declaration of <code class=\"codespan\">transform</code>, <code class=\"codespan\">fromDatasetIndex</code>/<code class=\"codespan\">fromDatasetId</code> in some blank dataset.</li>\n<li>Series references these datasets to show the result.</li>\n</ul>\n<h2 id=\"advanced-usage\">Advanced usage</h2>\n<h4 id=\"piped-transform\">Piped transform</h4>\n<p>There is a syntactic sugar that pipe transforms like:</p>\n<pre><code class=\"lang-js\">option: {\n    dataset: [{\n        source: [ ... ] // The original data\n    }, {\n        // Declare transforms in an array to pipe multiple transforms,\n        // which makes them execute one by one and take the output of\n        // the previous transform as the input of the next transform.\n        transform: [{\n            type: &#39;filter&#39;,\n            config: { dimension: &#39;Product&#39;, value: &#39;Tofu&#39; }\n        }, {\n            type: &#39;sort&#39;,\n            config: { dimension: &#39;Year&#39;, order: &#39;desc&#39; }\n        }]\n    }],\n    series: {\n        type: &#39;pie&#39;,\n        // Display the result of the piped transform.\n        datasetIndex: 1\n    }\n}\n</code></pre>\n<blockquote>\n<p>Note: theoretically any type of transform is able to have multiple input data and multiple output data. But when a transform is piped, it is only able to take one input (except it is the first transform of the pipe) and product one output (except it is the last transform of the pipe).</p>\n</blockquote>\n<h4 id=\"output-multiple-data\">Output multiple data</h4>\n<p>In most cases, transform functions only need to produce one data. But there is indeed scenarios that a transform function needs to produce multiple data, each of whom might be used by different series.</p>\n<p>For example, in the built-in boxplot transform, besides boxplot data produced, the outlier data are also produced, which can be used in a scatter series. See the <a href=\"https://echarts.apache.org/examples/en/editor.html?c=boxplot-light-velocity&amp;edit=1&amp;reset=1\" target=\"_blank\">example</a>.</p>\n<p>We use prop <a href=\"option.html#dataset.fromTransformResult\" target=\"_blank\">dataset.fromTransformResult</a> to satisfy this requirement. For example:</p>\n<pre><code class=\"lang-js\">option = {\n    dataset: [{\n        // Original source data.\n        source: [...]\n    }, {\n        transform: {\n            type: &#39;boxplot&#39;\n        }\n        // After this &quot;boxplot transform&quot; two result data generated:\n        // result[0]: The boxplot data\n        // result[1]: The outlier data\n        // By default, when series or other dataset reference this dataset,\n        // only result[0] can be visited.\n        // If we need to visit result[1], we have to use another dataset\n        // as follows:\n    }, {\n        // This extra dataset references the dataset above, and retrieves\n        // the result[1] as its own data. Thus series or other dataset can\n        // reference this dataset to get the data from result[1].\n        fromDatasetIndex: 1,\n        fromTransformResult: 1\n    }],\n    xAxis: {\n        type: &#39;category&#39;\n    },\n    yAxis: {\n    },\n    series: [{\n        name: &#39;boxplot&#39;,\n        type: &#39;boxplot&#39;,\n        // Reference the data from result[0].\n        datasetIndex: 1\n    }, {\n        name: &#39;outlier&#39;,\n        type: &#39;scatter&#39;,\n        // Reference the data from result[1].\n        datasetIndex: 2\n    }]\n};\n</code></pre>\n<p>What more, <a href=\"option.html#dataset.fromTransformResult\" target=\"_blank\">dataset.fromTransformResult</a> and <a href=\"option.html#dataset.transform\" target=\"_blank\">dataset.transform</a> can both appear in one dataset, which means that the input of the transform is from retrieved from the upstream result specified by <code class=\"codespan\">fromTransformResult</code>. For example:</p>\n<pre><code class=\"lang-js\">{\n    fromDatasetIndex: 1,\n    fromTransformResult: 1,\n    transform: {\n        type: &#39;sort&#39;,\n        config: { dimension: 2, order: &#39;desc&#39; }\n    }\n}\n</code></pre>\n<h4 id=\"debug-in-develop-environment\">Debug in develop environment</h4>\n<p>When using data transform, we might run into the trouble that the final chart do not display correctly but we do not know where the config is wrong. There is a property <code class=\"codespan\">transform.print</code> might help in such case. (<code class=\"codespan\">transform.print</code> is only available in dev environment).</p>\n<pre><code class=\"lang-js\">option = {\n    dataset: [{\n        source: [ ... ]\n    }, {\n        transform: {\n            type: &#39;filter&#39;,\n            config: { ... }\n            // The result of this transform will be printed\n            // in dev tool via `console.log`.\n            print: true\n        }\n    }],\n    ...\n}\n</code></pre>\n<h2 id=\"the-transform-filter\">The transform &quot;filter&quot;</h2>\n<p>Transform type &quot;filter&quot; is a built-in transform that provide data filter according to specified conditions. The basic option is like:</p>\n<pre><code class=\"lang-js\">option = {\n    dataset: [{\n        source: [\n            [&#39;Product&#39;, &#39;Sales&#39;, &#39;Price&#39;, &#39;Year&#39;],\n            [&#39;Cake&#39;, 123, 32, 2011],\n            [&#39;Latte&#39;, 231, 14, 2011],\n            [&#39;Tofu&#39;, 235, 5, 2011],\n            [&#39;Milk Tee&#39;, 341, 25, 2011],\n            [&#39;Porridge&#39;, 122, 29, 2011],\n            [&#39;Cake&#39;, 143, 30, 2012],\n            [&#39;Latte&#39;, 201, 19, 2012],\n            [&#39;Tofu&#39;, 255, 7, 2012],\n            [&#39;Milk Tee&#39;, 241, 27, 2012],\n            [&#39;Porridge&#39;, 102, 34, 2012],\n            [&#39;Cake&#39;, 153, 28, 2013],\n            [&#39;Latte&#39;, 181, 21, 2013],\n            [&#39;Tofu&#39;, 395, 4, 2013],\n            [&#39;Milk Tee&#39;, 281, 31, 2013],\n            [&#39;Porridge&#39;, 92, 39, 2013],\n            [&#39;Cake&#39;, 223, 29, 2014],\n            [&#39;Latte&#39;, 211, 17, 2014],\n            [&#39;Tofu&#39;, 345, 3, 2014],\n            [&#39;Milk Tee&#39;, 211, 35, 2014],\n            [&#39;Porridge&#39;, 72, 24, 2014]\n        ]\n    }, {\n        transform: {\n            type: &#39;filter&#39;,\n            config: { dimension: &#39;Year&#39;, &#39;=&#39;: 2011 }\n            // The config is the &quot;condition&quot; of this filter.\n            // This transform traverse the source data and\n            // and retrieve all the items that the &quot;Year&quot;\n            // is `2011`.\n        }\n    }],\n    series: {\n        type: &#39;pie&#39;,\n        datasetIndex: 1\n    }\n};\n</code></pre>\n<p><br>\n<br>\nThis is another example of filter transform:</p>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=data-transform-filter&reset=1&edit=1\" width=\"600\" height=\"350\" ></iframe>\n\n\n\n<p><strong>About dimension:</strong></p>\n<p>The <code class=\"codespan\">config.dimension</code> can be:</p>\n<ul>\n<li>Dimension name declared in dataset, like <code class=\"codespan\">config: { dimension: &#39;Year&#39;, &#39;=&#39;: 2011 }</code>. Dimension name declaration is not mandatory.</li>\n<li>Dimension index (start from 0), like <code class=\"codespan\">config: { dimension: 3, &#39;=&#39;: 2011 }</code>.</li>\n</ul>\n<p><strong>About relational operator:</strong></p>\n<p>The relational operator can be:\n<code class=\"codespan\">&gt;</code>(<code class=\"codespan\">gt</code>), <code class=\"codespan\">&gt;=</code>(<code class=\"codespan\">gte</code>), <code class=\"codespan\">&lt;</code>(<code class=\"codespan\">lt</code>), <code class=\"codespan\">&lt;=</code>(<code class=\"codespan\">lte</code>), <code class=\"codespan\">=</code>(<code class=\"codespan\">eq</code>), <code class=\"codespan\">!=</code>(<code class=\"codespan\">ne</code>, <code class=\"codespan\">&lt;&gt;</code>), <code class=\"codespan\">reg</code>. (The name in the parentheses are aliases). They follows the common semantics.\nBesides the common number comparison, there is some extra features:</p>\n<ul>\n<li>Multiple operators are able to appear in one {} item like <code class=\"codespan\">{ dimension: &#39;Price&#39;, &#39;&gt;=&#39;: 20, &#39;&lt;&#39;: 30 }</code>, which means logical &quot;and&quot; (Price &gt;= 20 and Price &lt; 30).</li>\n<li>The data value can be &quot;numeric string&quot;. Numeric string is a string that can be converted to number. Like &#39; 123 &#39;. White spaces and line breaks will be auto trimmed in the conversion.</li>\n<li>If we need to compare &quot;JS <code class=\"codespan\">Date</code> instance&quot; or date string (like &#39;2012-05-12&#39;), we need to specify <code class=\"codespan\">parser: &#39;time&#39;</code> manually, like <code class=\"codespan\">config: { dimension: 3, lt: &#39;2012-05-12&#39;, parser: &#39;time&#39; }</code>.</li>\n<li>Pure string comparison is supported but can only be used in <code class=\"codespan\">=</code>, <code class=\"codespan\">!=</code>. <code class=\"codespan\">&gt;</code>, <code class=\"codespan\">&gt;=</code>, <code class=\"codespan\">&lt;</code>, <code class=\"codespan\">&lt;=</code> do not support pure string comparison (the &quot;right value&quot; of the four operators can not be a &quot;string&quot;).</li>\n<li>The operator <code class=\"codespan\">reg</code> can be used to make regular expression test. Like using <code class=\"codespan\">{ dimension: &#39;Name&#39;, reg: /\\s+Müller\\s*$/ }</code> to select all data items that the &quot;Name&quot; dimension contains family name Müller.</li>\n</ul>\n<p><strong>About logical relationship:</strong></p>\n<p>Sometimes we also need to express logical relationship ( <code class=\"codespan\">and</code> / <code class=\"codespan\">or</code> / <code class=\"codespan\">not</code> ):</p>\n<pre><code class=\"lang-js\">option = {\n    dataset: [{\n        source: [...]\n    }, {\n        transform: {\n            type: &#39;filter&#39;,\n            config: {\n                // Use operator &quot;and&quot;.\n                // Similarly, we can also use &quot;or&quot;, &quot;not&quot; in the same place.\n                // But &quot;not&quot; should be followed with a {...} rather than `[...]`.\n                and: [\n                    { dimension: &#39;Year&#39;, &#39;=&#39;: 2011 },\n                    { dimension: &#39;Price&#39;, &#39;&gt;=&#39;: 20, &#39;&lt;&#39;: 30 }\n                ]\n            }\n            // The condition is &quot;Year&quot; is 2011 and &quot;Price&quot; is greater\n            // or equal to 20 but less than 30.\n        }\n    }],\n    series: {\n        type: &#39;pie&#39;,\n        datasetIndex: 1\n    }\n};\n</code></pre>\n<p><code class=\"codespan\">and</code>/<code class=\"codespan\">or</code>/<code class=\"codespan\">not</code> can be nested like:</p>\n<pre><code class=\"lang-js\">transform: {\n    type: &#39;filter&#39;,\n    config: {\n        or: [{\n            and: [{\n                dimension: &#39;Price&#39;, &#39;&gt;=&#39;: 10, &#39;&lt;&#39;: 20\n            }, {\n                dimension: &#39;Sales&#39;, &#39;&lt;&#39;: 100\n            }, {\n                not: { dimension: &#39;Product&#39;, &#39;=&#39;: &#39;Tofu&#39; }\n            }]\n        }, {\n            and: [{\n                dimension: &#39;Price&#39;, &#39;&gt;=&#39;: 10, &#39;&lt;&#39;: 20\n            }, {\n                dimension: &#39;Sales&#39;, &#39;&lt;&#39;: 100\n            }, {\n                not: { dimension: &#39;Product&#39;, &#39;=&#39;: &#39;Cake&#39; }\n            }]\n        }]\n    }\n}\n</code></pre>\n<p><strong>About parser:</strong></p>\n<p>Some &quot;parser&quot; can be specified when make value comparison. At present only supported:</p>\n<ul>\n<li><code class=\"codespan\">parser: &#39;time&#39;</code>: Parse the value to date time before comparing. The parser rule is the same as <code class=\"codespan\">echarts.time.parse</code>, where JS <code class=\"codespan\">Date</code> instance, timestamp number (in millisecond) and time string (like <code class=\"codespan\">&#39;2012-05-12 03:11:22&#39;</code>) are supported to be parse to timestamp number, while other value will be parsed to <code class=\"codespan\">NaN</code>.</li>\n<li><code class=\"codespan\">parser: &#39;trim&#39;</code>: Trim the string before making comparison. For non-string, return the original value.</li>\n<li><code class=\"codespan\">parser: &#39;number&#39;</code>: Force to convert the value to number before making comparison. If not possible to be converted to a meaningful number, converted to <code class=\"codespan\">NaN</code>. In most cases it is not necessary, because by default the value will be auto converted to number if possible before making comparison. But the default conversion is strict while this parser provide a loose strategy. If we meet the case that number string with unit suffix (like <code class=\"codespan\">&#39;33%&#39;</code>, <code class=\"codespan\">12px</code>), we should use <code class=\"codespan\">parser: &#39;number&#39;</code> to convert them to number before making comparison.</li>\n</ul>\n<p>This is an example to show the <code class=\"codespan\">parser: &#39;time&#39;</code>:</p>\n<pre><code class=\"lang-js\">option = {\n    dataset: [{\n        source: [\n            [&#39;Product&#39;, &#39;Sales&#39;, &#39;Price&#39;, &#39;Date&#39;],\n            [&#39;Milk Tee&#39;, 311, 21, &#39;2012-05-12&#39;],\n            [&#39;Cake&#39;, 135, 28, &#39;2012-05-22&#39;],\n            [&#39;Latte&#39;, 262, 36, &#39;2012-06-02&#39;],\n            [&#39;Milk Tee&#39;, 359, 21, &#39;2012-06-22&#39;],\n            [&#39;Cake&#39;, 121, 28, &#39;2012-07-02&#39;],\n            [&#39;Latte&#39;, 271, 36, &#39;2012-06-22&#39;],\n            ...\n        ]\n    }, {\n        transform: {\n            type: &#39;filter&#39;,\n            config: {\n                { dimension: &#39;Date&#39;, &#39;&gt;=&#39;: &#39;2012-05&#39;, &#39;&lt;&#39;: &#39;2012-06&#39;, parser: &#39;time&#39; }\n            }\n        }\n    }]\n}\n</code></pre>\n<p><strong>Formally definition:</strong></p>\n<p>Finally, we give the formally definition of the filter transform config here:</p>\n<pre><code class=\"lang-ts\">type FilterTransform = {\n    type: &#39;filter&#39;;\n    config: ConditionalExpressionOption;\n};\ntype ConditionalExpressionOption =\n    true | false | RelationalExpressionOption | LogicalExpressionOption;\ntype RelationalExpressionOption = {\n    dimension: DimensionName | DimensionIndex;\n    parser?: &#39;time&#39; | &#39;trim&#39; | &#39;number&#39;;\n    lt?: DataValue; // less than\n    lte?: DataValue; // less than or equal\n    gt?: DataValue; // greater than\n    gte?: DataValue; // greater than or equal\n    eq?: DataValue; // equal\n    ne?: DataValue; // not equal\n    &#39;&lt;&#39;?: DataValue; // lt\n    &#39;&lt;=&#39;?: DataValue; // lte\n    &#39;&gt;&#39;?: DataValue; // gt\n    &#39;&gt;=&#39;?: DataValue; // gte\n    &#39;=&#39;?: DataValue; // eq\n    &#39;!=&#39;?: DataValue; // ne\n    &#39;&lt;&gt;&#39;?: DataValue; // ne (SQL style)\n    reg?: RegExp | string; // RegExp\n};\ntype LogicalExpressionOption = {\n    and?: ConditionalExpressionOption[];\n    or?: ConditionalExpressionOption[];\n    not?: ConditionalExpressionOption;\n};\ntype DataValue = string | number | Date;\ntype DimensionName = string;\ntype DimensionIndex = number;\n</code></pre>\n<h2 id=\"the-transform-sort\">The transform &quot;sort&quot;</h2>\n<p>Another built-in transform is &quot;sort&quot;.</p>\n<pre><code class=\"lang-js\">option = {\n    dataset: [{\n        dimensions: [&#39;name&#39;, &#39;age&#39;, &#39;profession&#39;, &#39;score&#39;, &#39;date&#39;],\n        source: [\n            [&#39; Hannah Krause &#39;, 41, &#39;Engineer&#39;, 314, &#39;2011-02-12&#39;],\n            [&#39;Zhao Qian &#39;, 20, &#39;Teacher&#39;, 351, &#39;2011-03-01&#39;],\n            [&#39; Jasmin Krause &#39;, 52, &#39;Musician&#39;, 287, &#39;2011-02-14&#39;],\n            [&#39;Li Lei&#39;, 37, &#39;Teacher&#39;, 219, &#39;2011-02-18&#39;],\n            [&#39; Karle Neumann &#39;, 25, &#39;Engineer&#39;, 253, &#39;2011-04-02&#39;],\n            [&#39; Adrian Groß&#39;, 19, &#39;Teacher&#39;, null, &#39;2011-01-16&#39;],\n            [&#39;Mia Neumann&#39;, 71, &#39;Engineer&#39;, 165, &#39;2011-03-19&#39;],\n            [&#39; Böhm Fuchs&#39;, 36, &#39;Musician&#39;, 318, &#39;2011-02-24&#39;],\n            [&#39;Han Meimei &#39;, 67, &#39;Engineer&#39;, 366, &#39;2011-03-12&#39;],\n        ]\n    }, {\n        transform: {\n            type: &#39;sort&#39;,\n            // Sort by score.\n            config: { dimension: &#39;score&#39;, order: &#39;asc&#39; }\n        }\n    }],\n    series: {\n        type: &#39;bar&#39;,\n        datasetIndex: 1\n    },\n    ...\n};\n</code></pre>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=data-transform-sort-bar&reset=1&edit=1\" width=\"600\" height=\"350\" ></iframe>\n\n\n\n\n<p>Some extra features about &quot;sort transform&quot;:</p>\n<ul>\n<li>Order by multiple dimensions is supported. See examples below.</li>\n<li>The sort rule:<ul>\n<li>By default &quot;numeric&quot; (that is, number and numeric-string like <code class=\"codespan\">&#39; 123 &#39;</code>) are able to sorted by numeric order.</li>\n<li>Otherwise &quot;non-numeric-string&quot; are also able to be ordered among themselves. This might help to the case like grouping data items with the same tag, especially when multiple dimensions participated in the sort (See example below).</li>\n<li>When &quot;numeric&quot; is compared with &quot;non-numeric-string&quot;, or either of them is compared with other types of value, they are not comparable. So we call the latter one as &quot;incomparable&quot; and treat it as &quot;min value&quot; or &quot;max value&quot; according to the prop <code class=\"codespan\">incomparable: &#39;min&#39; | &#39;max&#39;</code>. This feature usually helps to decide whether to put the empty values (like <code class=\"codespan\">null</code>, <code class=\"codespan\">undefined</code>, <code class=\"codespan\">NaN</code>, <code class=\"codespan\">&#39;&#39;</code>, <code class=\"codespan\">&#39;-&#39;</code>) or other illegal values to the head or tail.</li>\n</ul>\n</li>\n<li><code class=\"codespan\">filter: &#39;time&#39; | &#39;trim&#39; | &#39;number&#39;</code> can be used, the same as &quot;filter transform&quot;.<ul>\n<li>If intending to sort time values (JS <code class=\"codespan\">Date</code> instance or time string like <code class=\"codespan\">&#39;2012-03-12 11:13:54&#39;</code>), <code class=\"codespan\">parser: &#39;time&#39;</code> should be specified. Like <code class=\"codespan\">config: { dimension: &#39;date&#39;, order: &#39;desc&#39;, parser: &#39;time&#39; }</code></li>\n<li>If intending to sort values with unit suffix (like <code class=\"codespan\">&#39;33%&#39;</code>, <code class=\"codespan\">&#39;16px&#39;</code>), need to use <code class=\"codespan\">parser: &#39;number&#39;</code>.</li>\n</ul>\n</li>\n</ul>\n<p>See an example of multiple order:</p>\n<pre><code class=\"lang-js\">option = {\n    dataset: [{\n        dimensions: [&#39;name&#39;, &#39;age&#39;, &#39;profession&#39;, &#39;score&#39;, &#39;date&#39;],\n        source: [\n            [&#39; Hannah Krause &#39;, 41, &#39;Engineer&#39;, 314, &#39;2011-02-12&#39;],\n            [&#39;Zhao Qian &#39;, 20, &#39;Teacher&#39;, 351, &#39;2011-03-01&#39;],\n            [&#39; Jasmin Krause &#39;, 52, &#39;Musician&#39;, 287, &#39;2011-02-14&#39;],\n            [&#39;Li Lei&#39;, 37, &#39;Teacher&#39;, 219, &#39;2011-02-18&#39;],\n            [&#39; Karle Neumann &#39;, 25, &#39;Engineer&#39;, 253, &#39;2011-04-02&#39;],\n            [&#39; Adrian Groß&#39;, 19, &#39;Teacher&#39;, null, &#39;2011-01-16&#39;],\n            [&#39;Mia Neumann&#39;, 71, &#39;Engineer&#39;, 165, &#39;2011-03-19&#39;],\n            [&#39; Böhm Fuchs&#39;, 36, &#39;Musician&#39;, 318, &#39;2011-02-24&#39;],\n            [&#39;Han Meimei &#39;, 67, &#39;Engineer&#39;, 366, &#39;2011-03-12&#39;],\n        ]\n    }, {\n        transform: {\n            type: &#39;sort&#39;,\n            config: [\n                // Sort by the two dimensions.\n                { dimension: &#39;profession&#39;, order: &#39;desc&#39; },\n                { dimension: &#39;score&#39;, order: &#39;desc&#39; }\n            ]\n        }\n    }],\n    series: {\n        type: &#39;bar&#39;,\n        datasetIndex: 1\n    },\n    ...\n};\n</code></pre>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=doc-example/data-transform-multiple-sort-bar&reset=1&edit=1\" width=\"600\" height=\"350\" ></iframe>\n\n\n\n<p>Finally, we give the formally definition of the sort transform config here:</p>\n<pre><code class=\"lang-ts\">type SortTransform = {\n    type: &#39;filter&#39;;\n    config: OrderExpression | OrderExpression[];\n};\ntype OrderExpression = {\n    dimension: DimensionName | DimensionIndex;\n    order: &#39;asc&#39; | &#39;desc&#39;;\n    incomparable?: &#39;min&#39; | &#39;max&#39;;\n    parser?: &#39;time&#39; | &#39;trim&#39; | &#39;number&#39;;\n};\ntype DimensionName = string;\ntype DimensionIndex = number;\n</code></pre>\n<h2 id=\"use-external-transforms\">Use external transforms</h2>\n<p>Besides built-in transforms (like &#39;filter&#39;, &#39;sort&#39;), we can also use external transforms to provide more powerful functionalities. Here we use a third-party library <a href=\"https://github.com/ecomfe/echarts-stat\" target=\"_blank\">ecStat</a> as an example:</p>\n<p>This case show how to make a regression line via ecStat:</p>\n<pre><code class=\"lang-js\">// Register the external transform at first.\necharts.registerTransform(ecStatTransform(ecStat).regression);\n</code></pre>\n<pre><code class=\"lang-js\">option = {\n    dataset: [{\n        source: rawData\n    }, {\n        transform: {\n            // Reference the registered external transform.\n            // Note that external transform has a namespace (like &#39;ecStat:xxx&#39;\n            // has namespace &#39;ecStat&#39;).\n            // built-in transform (like &#39;filter&#39;, &#39;sort&#39;) does not have a namespace.\n            type: &#39;ecStat:regression&#39;,\n            config: {\n                // Parameters needed by the external transform.\n                method: &#39;exponential&#39;\n            }\n        }\n    }],\n    xAxis: { type: &#39;category&#39; },\n    yAxis: {},\n    series: [{\n        name: &#39;scatter&#39;,\n        type: &#39;scatter&#39;,\n        datasetIndex: 0\n    }, {\n        name: &#39;regression&#39;,\n        type: &#39;line&#39;,\n        symbol: &#39;none&#39;,\n        datasetIndex: 1\n    }]\n};\n</code></pre>\n<p>Examples with echarts-stat:</p>\n<ul>\n<li><a href=\"https://echarts.apache.org/examples/en/editor.html?c=bar-histogram&amp;edit=1&amp;reset=1\" target=\"_blank\">Bar histogram</a></li>\n<li><a href=\"https://echarts.apache.org/examples/en/editor.html?c=scatter-clustering&amp;edit=1&amp;reset=1\" target=\"_blank\">Scatter clustering</a></li>\n<li><a href=\"https://echarts.apache.org/examples/en/editor.html?c=scatter-linear-regression&amp;edit=1&amp;reset=1\" target=\"_blank\">Scatter linear regression</a></li>\n<li><a href=\"https://echarts.apache.org/examples/en/editor.html?c=scatter-exponential-regression&amp;edit=1&amp;reset=1\" target=\"_blank\">Scatter exponential regression</a></li>\n<li><a href=\"https://echarts.apache.org/examples/en/editor.html?c=scatter-logarithmic-regression&amp;edit=1&amp;reset=1\" target=\"_blank\">Scatter logarithmic regression</a></li>\n<li><a href=\"https://echarts.apache.org/examples/en/editor.html?c=scatter-polynomial-regression&amp;edit=1&amp;reset=1\" target=\"_blank\">Scatter polynomial regression</a></li>\n</ul>\n"},"Add interaction to the chart component":{"type":["*"],"description":"<p>Apache ECharts<sup>TM</sup> provides many interaction components besides chart. For example:</p>\n<p><code class=\"codespan\">legend component</code> <a href=\"option.html#legend\" target=\"_blank\">legend</a>、<code class=\"codespan\">title component</code> <a href=\"option.html#title\" target=\"_blank\">title</a>、<code class=\"codespan\">visualmap component</code> <a href=\"option.html#visualMap\" target=\"_blank\">visualMap</a>、<code class=\"codespan\">datazoom component</code> <a href=\"option.html#dataZoom\" target=\"_blank\">dataZoom</a>、<code class=\"codespan\">dataline component</code> <a href=\"option.html#timeline\" target=\"_blank\">timeline</a></p>\n<p>Following is an example of <code class=\"codespan\">datazoom component</code> <a href=\"option.html#dataZoom\" target=\"_blank\">dataZoom</a> as an introduction of how to add this kind of component.</p>\n<h2 id=\"introduction-of-data-zoom-component-datazoom-\">Introduction of data zoom component (dataZoom)</h2>\n<p>Data overview by default, and detail by requirement is a basic interaction need of data visualization. <code class=\"codespan\">dataZoom</code> component can implement this function in rectangular coordinate (<a href=\"option.html#grid\" target=\"_blank\">grid</a>) and polar coordinate (<a href=\"option.html#polar\" target=\"_blank\">polar</a>.</p>\n<p><strong>For example: </strong></p>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=doc-example/scatter-dataZoom-all&edit=1&reset=1\" width=\"600\" height=\"400\" ></iframe>\n\n\n<p><br></p>\n<ul>\n<li><code class=\"codespan\">dataZoom</code> component operates <em>data window zoom</em> and <em>data window translation</em> on <code class=\"codespan\">axis</code>.</li>\n</ul>\n<blockquote>\n<p>Use <a href=\"option.html#dataZoom.xAxisIndex\" target=\"_blank\">dataZoom.xAxisIndex</a>, <a href=\"option.html#dataZoom.yAxisIndex\" target=\"_blank\">dataZoom.yAxisIndex</a> to specify which axis <code class=\"codespan\">dataZoom</code> controls.</p>\n</blockquote>\n<ul>\n<li><p>Multiple <code class=\"codespan\">dataZoom</code> components can exist at the same time to control function together. Components controling the same axis will be connected automatically. The example below explains in detail.</p>\n</li>\n<li><p>Operation principle of <code class=\"codespan\">dataZoom</code> achieves <em>data window zooming</em> through <em>data filtering</em>.</p>\n<p>  Different settings of data filtering modes lead to different data window zooming effects, please see: <a href=\"option.html#dataZoom.filterMode\" target=\"_blank\">dataZoom.filterMode</a>.</p>\n</li>\n<li><p>Setting of <code class=\"codespan\">dataZoom</code> data window range supports two formats currently:</p>\n<ul>\n<li><p>Percentage: see <a href=\"option.html#dataZoom.start\" target=\"_blank\">dataZoom.start</a> and <a href=\"option.html#dataZoom.end\" target=\"_blank\">dataZoom.end</a>.</p>\n</li>\n<li><p>Absolute value: see <a href=\"option.html#dataZoom.startValue\" target=\"_blank\">dataZoom.startValue</a> and <a href=\"option.html#dataZoom.endValue\" target=\"_blank\">dataZoom.endValue</a>.</p>\n</li>\n</ul>\n</li>\n</ul>\n<p><strong>dataZoom component supports several child components: </strong></p>\n<ul>\n<li><p><a href=\"option.html#dataZoom-inside\" target=\"_blank\">Inside data zoom component (dataZoomInside)</a>: inside coordinates.</p>\n</li>\n<li><p><a href=\"option.html#dataZoom-slider\" target=\"_blank\">Slider data zoom component (dataZoomSlider)</a>: has seperate slide option.</p>\n</li>\n<li><p><a href=\"option.html#toolbox.feature.dataZoom\" target=\"_blank\">Select data zoom component (dataZoomSelect)</a>: full-screen box for zoom data area. Entrance and configuration item are both in <code class=\"codespan\">toolbox</code>.</p>\n</li>\n</ul>\n<h2 id=\"adding-datazoom-component\">Adding dataZoom component</h2>\n<p>First, only add dataZoom component to x-axis. Following examples shows the code.</p>\n<pre><code class=\"lang-javascript\">\noption = {\n    xAxis: {\n        type: &#39;value&#39;\n    },\n    yAxis: {\n        type: &#39;value&#39;\n    },\n    dataZoom: [\n        {   // This dataZoom component controls x-axis by dafault\n            type: &#39;slider&#39;, // this dataZoom component is dataZoom component of slider\n            start: 10,      // the left is located at 10%\n            end: 60         // the right is located at 60%\n        }\n    ],\n    series: [\n        {\n            type: &#39;scatter&#39;, // this is scatter chart\n            itemStyle: {\n                opacity: 0.8\n            },\n            symbolSize: function (val) {\n                return val[2] * 40;\n            },\n            data: [[&quot;14.616&quot;,&quot;7.241&quot;,&quot;0.896&quot;],[&quot;3.958&quot;,&quot;5.701&quot;,&quot;0.955&quot;],[&quot;2.768&quot;,&quot;8.971&quot;,&quot;0.669&quot;],[&quot;9.051&quot;,&quot;9.710&quot;,&quot;0.171&quot;],[&quot;14.046&quot;,&quot;4.182&quot;,&quot;0.536&quot;],[&quot;12.295&quot;,&quot;1.429&quot;,&quot;0.962&quot;],[&quot;4.417&quot;,&quot;8.167&quot;,&quot;0.113&quot;],[&quot;0.492&quot;,&quot;4.771&quot;,&quot;0.785&quot;],[&quot;7.632&quot;,&quot;2.605&quot;,&quot;0.645&quot;],[&quot;14.242&quot;,&quot;5.042&quot;,&quot;0.368&quot;]]\n        }\n    ]\n}\n</code></pre>\n<p>which will show the following result:</p>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=doc-example/scatter-tutorial-dataZoom-1&edit=1&reset=1\" width=\"600\" height=\"300\" ></iframe>\n\n\n<p><br></p>\n<p>The chart above can only change window by dragging dataZoom component. If you want to drag in coordinate, or use mouse wheel (or slides with two fingers on mobile) to zoom, then another inside dataZoom component needs to be added. You can just add in the <code class=\"codespan\">option.dataZoom</code> above:</p>\n<pre><code class=\"lang-javascript\">option = {\n    ...,\n    dataZoom: [\n        {   // this dataZoom component controls x-axis by dafault\n            type: &#39;slider&#39;, // this dataZoom component is dataZoom component of slider\n            start: 10,      // the left is located at 10%\n            end: 60         // the right is located at 60%\n        },\n        {   // This dataZoom component controls x-axis by dafault\n            type: &#39;inside&#39;, // this dataZoom component is dataZoom component of inside\n            start: 10,      // the left is located at 10%\n            end: 60         // the right is located at 60%\n        }\n    ],\n    ...\n}\n</code></pre>\n<p>Following results can be seen (you can now slide or use mouse wheel to zoom in coordinate) :</p>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=doc-example/scatter-tutorial-dataZoom-2&edit=1&reset=1\" width=\"600\" height=\"300\" ></iframe>\n\n\n\n<p><br></p>\n<p>If you want to enable zooming on y-axis, then you need to add dataZoom componet on y-axis:</p>\n<pre><code class=\"lang-javascript\">option = {\n    ...,\n    dataZoom: [\n        {\n            type: &#39;slider&#39;,\n            xAxisIndex: 0,\n            start: 10,\n            end: 60\n        },\n        {\n            type: &#39;inside&#39;,\n            xAxisIndex: 0,\n            start: 10,\n            end: 60\n        },\n        {\n            type: &#39;slider&#39;,\n            yAxisIndex: 0,\n            start: 30,\n            end: 80\n        },\n        {\n            type: &#39;inside&#39;,\n            yAxisIndex: 0,\n            start: 30,\n            end: 80\n        }\n    ],\n    ...\n}\n</code></pre>\n<p>Following result can be seen:</p>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=doc-example/scatter-tutorial-dataZoom-3&edit=1&reset=1\" width=\"600\" height=\"300\" ></iframe>\n\n\n\n\n\n\n\n\n"},"Responsive Mobile-End":{"type":["*"],"description":"<p>Apache ECharts<sup>TM</sup> works in DOM nodes with user defined width and height. ECharts <em>component</em> and <em>series</em> are both in this DOM node, whose location can be assigned by user seperately. Inner components of charts are not suitable for implementing DOM flow layout. Instead, we use a simpler and more understandable layout similar to absolute layout. But sometimes when container is of extreme size, this method cannot avoid component overlapping automatically, especially on small screens on mobile-end.</p>\n<p>Besides, sometimes one chart may need to be displayed on both PC and mobile-end, which involves the ability of ECharts inner components to be responsive with different container sizes.</p>\n<p>To solve this problem, ECharts improved component location algorithm, and implemented responsive ability similar to <a href=\"https://www.w3.org/TR/css3-mediaqueries/\" target=\"_blank\">CSS Media Query</a>.</p>\n<h2 id=\"location-and-layout-of-echarts-components\">Location and layout of ECharts components</h2>\n<p>Most <em>component</em> and <em>series</em> follow two locating methods:</p>\n<p><br>\n<strong>left/right/top/bottom/width/height locating method:</strong></p>\n<p>Each of those six parameters can be <em>absolute value</em> or <em>percentage</em> or <em>location description</em>.</p>\n<ul>\n<li><p>Absolute value</p>\n<p>  in browser pixels (px); in form of <code class=\"codespan\">number</code> (no unit); e.g.: <code class=\"codespan\">{left: 23, height: 400}</code>.</p>\n</li>\n<li><p>Percentage</p>\n<p>  to the width and height of DOM container; in form of <code class=\"codespan\">string</code>; e.g.: <code class=\"codespan\">{right: &#39;30%&#39;, bottom: &#39;40%&#39;}</code>.</p>\n</li>\n<li><p>Location Description</p>\n<ul>\n<li>can be set to <code class=\"codespan\">left: &#39;center&#39;</code>, for horizontally centering.</li>\n<li>can be set to <code class=\"codespan\">top: &#39;middle&#39;</code>, for vertically centering.</li>\n</ul>\n</li>\n</ul>\n<p>The concept of these six parameters is similar to that in CSS:</p>\n<ul>\n<li>left: distance to left border of DOM container.</li>\n<li>right: distance to right border of DOM container.</li>\n<li>top: distance to top border of DOM container.</li>\n<li>bottom: distance to bottom border of DOM container.</li>\n<li>width: width.</li>\n<li>height: height.</li>\n</ul>\n<p>Two out of the three horizontal parameters, <code class=\"codespan\">left</code>, <code class=\"codespan\">right</code>, <code class=\"codespan\">width</code>, are enough to determine the component location. For example, <code class=\"codespan\">left</code> and <code class=\"codespan\">right</code>, or <code class=\"codespan\">right</code> and <code class=\"codespan\">width</code> can both determine component location and size.\nThe same goes for vertical paramters <code class=\"codespan\">top</code>, <code class=\"codespan\">bottom</code> and <code class=\"codespan\">height</code>.</p>\n<p><br>\n<strong>Locating method of <code class=\"codespan\">center</code> / <code class=\"codespan\">radius</code>: </strong></p>\n<ul>\n<li><p><code class=\"codespan\">center</code></p>\n<p>  an array in form of <code class=\"codespan\">[x, y]</code>, in which <code class=\"codespan\">x</code> and <code class=\"codespan\">y</code> can either be <em>absolute value</em> or <em>percentage</em>, as described above.</p>\n</li>\n<li><p><code class=\"codespan\">radius</code></p>\n<p>  an array in form of <code class=\"codespan\">[innerRadius, outerRadius]</code>, in which <code class=\"codespan\">innerRadius</code> and <code class=\"codespan\">outerRadius</code> can either be <em>absolute value</em> or <em>percentage</em>, as described above.</p>\n<p>  Percentage location turns out to be very useful for responsive positioning.</p>\n</li>\n</ul>\n<p><br>\n<strong>Horizontal and vertical</strong></p>\n<p>Most of ECharts&#39;s long and narrow components (such as <code class=\"codespan\">legend</code>,<code class=\"codespan\">visualMap</code>,<code class=\"codespan\">dataZoom</code>,<code class=\"codespan\">timeline</code> and so on), provide option to set them to be horizontal or vertical. For example, long and narrow screen of mobile-end, vertical layout may be a more suitable choice, while horizontal may more suit for PC&#39;s wide screen.</p>\n<p>Setting of horizontal or vertical layout is usually with component or series&#39;s <code class=\"codespan\">orient</code> or <code class=\"codespan\">layout</code> option, which can be set to <code class=\"codespan\">&#39;horizontal&#39;</code> or <code class=\"codespan\">&#39;vertical&#39;</code>.</p>\n<p><br>\n<strong>Compatibility with ECharts2: </strong></p>\n<p>Naming of <code class=\"codespan\">x/x2/y/y2</code> in ECharts2 is still compatible, as well as the newly added <code class=\"codespan\">left/right/top/bottom</code>. But <code class=\"codespan\">left/right/top/bottom</code> is recommended.</p>\n<p>To be compatible with ECharts2, there may be settings that seems to be odd, e.g.: <code class=\"codespan\">left: &#39;right&#39;</code>, <code class=\"codespan\">left: &#39;left&#39;</code>, <code class=\"codespan\">top: &#39;bottom&#39;</code>, <code class=\"codespan\">top: &#39;top&#39;</code>, which are equal to: <code class=\"codespan\">right: 0</code>, <code class=\"codespan\">left: 0</code>, <code class=\"codespan\">bottom: 0</code>, <code class=\"codespan\">top: 0</code>, in a more normal expression.</p>\n<h2 id=\"media-query\">Media Query</h2>\n<p><a href=\"https://www.w3.org/TR/css3-mediaqueries/#media1\" target=\"_blank\">Media Query</a> provides the ability to be responsive with container size.</p>\n<p>As shown in the following example, you may drag <strong>the circle in bottom-right corner</strong> to see the legend and series change layout position and method with container size.</p>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=doc-example/pie-media&edit=1&reset=1\" width=\"750\" height=\"600\" ></iframe>\n\n\n<p>The following format should be followed if you need to set Media Query in option:</p>\n<pre><code class=\"lang-javascript\">option = {\n    // here defines baseOption\n    title: {...},\n    legend: {...},\n    series: [{...}, {...}, ...],\n    ...,\n    media: [ // each rule of media query is defined here\n        {\n            query: {...},   // write rule here\n            option: {       // write options accordingly\n                legend: {...},\n                ...\n            }\n        },\n        {\n            query: {...},   // the second rule\n            option: {       // the second option\n                legend: {...},\n                ...\n            }\n        },\n        {                   // default with no rules,\n            option: {       // when all rules fail, use this option\n                legend: {...},\n                ...\n            }\n        }\n    ]\n};\n</code></pre>\n<p>In the above example, <code class=\"codespan\">baseOption</code> and every option in <code class=\"codespan\">media</code> are all <em>simple options</em>, which are regular options containing components and series. <code class=\"codespan\">baseOption</code> is always be used, while options of every will be merged with <code class=\"codespan\">chart.mergeOption()</code> when given <code class=\"codespan\">query</code> condition is satisfied with.</p>\n<p><strong>query: </strong></p>\n<p>A <code class=\"codespan\">query</code> is in the following format:</p>\n<pre><code class=\"lang-javascript\">{\n    minWidth: 200,\n    maxHeight: 300,\n    minAspectRatio: 1.3\n}\n</code></pre>\n<p>Currently there are three supported attributes:<code class=\"codespan\">width</code>, <code class=\"codespan\">height</code>, <code class=\"codespan\">aspectRatio</code> (height / width), each of which can add <code class=\"codespan\">min</code> or <code class=\"codespan\">max</code> as prefix. E.g., <code class=\"codespan\">minWidth: 200</code> stands for when width is greater than or equal to 200px. When two attributes are written together, it means <em>and</em> in Bool logic. For example, <code class=\"codespan\">{minWidth: 200, maxHeight: 300}</code> stands for when width is greater than or equal to 200px and height is smaller than or equal to 300px.</p>\n<p><strong>option: </strong></p>\n<p>Since option in <code class=\"codespan\">media</code> is <em>simple option</em>, technically speaking, you can write every option configuration item. But usually we only write those related to layout. Take part of the above query option as example:</p>\n<pre><code class=\"lang-javascript\">media: [\n    ...,\n    {\n        query: {\n            maxAspectRatio: 1           // when length-to-width ratio is less than 1\n        },\n        option: {\n            legend: {                   // legend is placed in middle-bottom\n                right: &#39;center&#39;,\n                bottom: 0,\n                orient: &#39;horizontal&#39;    // horizontal layout of legend\n            },\n            series: [                   // left and right layout of two pie charts\n                {\n                    radius: [20, &#39;50%&#39;],\n                    center: [&#39;50%&#39;, &#39;30%&#39;]\n                },\n                {\n                    radius: [30, &#39;50%&#39;],\n                    center: [&#39;50%&#39;, &#39;70%&#39;]\n                }\n            ]\n        }\n    },\n    {\n        query: {\n            maxWidth: 500               // when container width is smaller than 500\n        },\n        option: {\n            legend: {\n                right: 10,              // legend is placed in middle-right\n                top: &#39;15%&#39;,\n                orient: &#39;vertical&#39;      // vertical layout\n            },\n            series: [                   // top and bottom layout of two pie charts\n                {\n                    radius: [20, &#39;50%&#39;],\n                    center: [&#39;50%&#39;, &#39;30%&#39;]\n                },\n                {\n                    radius: [30, &#39;50%&#39;],\n                    center: [&#39;50%&#39;, &#39;75%&#39;]\n                }\n            ]\n        }\n    },\n    ...\n]\n</code></pre>\n<p><strong>Priority when multiple queries are satisfied: </strong></p>\n<p>Attention: When multiple <code class=\"codespan\">query</code> are satisfied at the same time, all of them will be merged with <code class=\"codespan\">mergeOption</code> and those are defined later will be merged later, thus provides them with higher priority.</p>\n<p><strong>Query by default: </strong></p>\n<p>If an item in <code class=\"codespan\">media</code> has no not <code class=\"codespan\">query</code>, then it means <em>default value</em>, which will be used when all other rules fail.</p>\n<p><strong>Pay attention when container size changes:</strong></p>\n<p>In many cases, container DOM node doesn&#39;t need to change size with user dragging. Instead, it may set to several sizes on varied ends.</p>\n<p>But if the container DOM node needs to change size with dragging, you need to pay attention to this: if certain configuration item appears in one <code class=\"codespan\">query option</code>, then it should also appeared in other <code class=\"codespan\">query option</code>, or it will not be able to return to the original state. (<code class=\"codespan\">left/right/top/bottom/width/height</code> are not restricted to this rule.)</p>\n<p><strong><code class=\"codespan\">media</code> in <em>composite option</em> does not support merge</strong></p>\n<p>When <code class=\"codespan\">chart.setOption(rawOption)</code> for the second, third, fourth, fifth, and etc. times, if <code class=\"codespan\">rawOption</code> is <code class=\"codespan\">composite option</code> (which means it contains <code class=\"codespan\">media</code> list), then, the new <code class=\"codespan\">rawOption.media</code> list will not merge with the old <code class=\"codespan\">media</code>. instead, it will simply replace the option. Of course, <code class=\"codespan\">baseOption</code> will still merge with the old option normally.</p>\n<p><br>\nFinally, let&#39;s see an example combining with timeline:</p>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=doc-example/bar-media-timeline&edit=1&reset=1\" width=\"750\" height=\"700\" ></iframe>\n\n\n\n\n\n"},"Visual Map of Data":{"type":["*"],"description":"<p>Data visualization is a procedure of mapping data into visual elements. This procedure can also be called visual coding, and visual elements can also be called visual tunnels.</p>\n<p>Every type of charts in Apache ECharts<sup>TM</sup> has this built-in mapping procedure. For example, line charts map data into <em>lines</em>, bar charts map data into <em>length</em>. Some more complicated charts, like <code class=\"codespan\">graph</code>, <code class=\"codespan\">themeRiver</code>, and <code class=\"codespan\">treemap</code> have their own built-in mapping.</p>\n<p>Besides, ECharts provides <a href=\"option.html#visualMap\" target=\"_blank\">visualMap component</a> for general visual mapping. Visual elements allowed in <code class=\"codespan\">visualMap</code> component are:<br>\n<code class=\"codespan\">symbol</code>, <code class=\"codespan\">symbolSize</code><br>\n<code class=\"codespan\">color</code>, <code class=\"codespan\">opacity</code>, <code class=\"codespan\">colorAlpha</code>, <br>\n<code class=\"codespan\">colorLightness</code>, <code class=\"codespan\">colorSaturation</code>, <code class=\"codespan\">colorHue</code></p>\n<p>Next, we are going to introduce how to use <code class=\"codespan\">visualMap</code> component.</p>\n<h2 id=\"data-and-dimension\">Data and Dimension</h2>\n<p>Data are usually stored in <a href=\"option.html#series.data\" target=\"_blank\">series.data</a> in ECharts. Depending on chart types, like list, tree, graph, and so on, the form of data may vary somehow. But they have one common feature, that they are a collection of <code class=\"codespan\">dataItem</code>s. Every data item contains data value, and other information if needed. Every data value can be a single value (one dimension) or an array (multiple dimensions).</p>\n<p>For example, <a href=\"option.html#series.data\" target=\"_blank\">series.data</a> is the most common form, which is a <code class=\"codespan\">list</code>, a common array:</p>\n<pre><code class=\"lang-javascript\">series: {\n    data: [\n        {       // every item here is a dataItem\n            value: 2323, // this is data value\n            itemStyle: {...}\n        },\n        1212,   // it can also be a value of dataItem, which is a more common case\n        2323,   // every data value here is one dimension\n        4343,\n        3434\n    ]\n}\n</code></pre>\n<pre><code class=\"lang-javascript\">series: {\n    data: [\n        {                        // every item here is a dataItem\n            value: [3434, 129,  &#39;San Marino&#39;], // this is data value\n            itemStyle: {...}\n        },\n        [1212, 5454, &#39;Vatican&#39;],   // it can also be a value of dataItem, which is a more common case\n        [2323, 3223, &#39;Nauru&#39;],     // every data value here is three dimension\n        [4343, 23,   &#39;Tuvalu&#39;]    // If is scatter chart, usually map the first dimension to x axis,\n                                 // the second dimension to y axis,\n                                 // and the third dimension to symbolSize\n    ]\n}\n</code></pre>\n<p>Usually the first one or two dimensions are used for mapping. For example, map the first dimension to x axis, and the second dimension to y axis. If you want to represent more dimensions, <code class=\"codespan\">visualMap</code> is what you need. Most likely, <a href=\"option.html#series-scatter\" target=\"_blank\">scatter charts</a> use radius to represent the third dimension.</p>\n<h2 id=\"visualmap-component\">visualMap Component</h2>\n<p>visualMap component defines the mapping from <em>which dimension of data</em> to <em>what visual elements</em>.</p>\n<p>The following two types of visualMap components are supported, identified with <a href=\"option.html#visualMap.type\" target=\"_blank\">visualMap.type</a>.</p>\n<p>Its structure is defined as:</p>\n<pre><code class=\"lang-javascript\">option = {\n    visualMap: [ // can define multiple visualMap components at the same time\n        { // the first visualMap component\n            type: &#39;continuous&#39;, // defined as continuous visualMap\n            ...\n        },\n        { // the second visualMap component\n            type: &#39;piecewise&#39;, // defined as discrete visualMap\n            ...\n        }\n    ],\n    ...\n};\n</code></pre>\n<p><a href=\"option.html#visualMap-continuous\" target=\"_blank\">visualMapContinuous</a>：</p>\n<p><a href=\"option.html#visualMap-piecewise\" target=\"_blank\">visualMapPiecewise</a>：</p>\n<p>Piecewise visual map component（visualMapPiecewise）has three types:</p>\n<ul>\n<li>Equal division of continuous data: divide equally based on <a href=\"option.html#visualMap-piecewise.splitNumber\" target=\"_blank\">visualMap-piecewise.splitNumber</a>;</li>\n<li>User-defined division of continuous data: divide with range in <a href=\"option.html#visualMap-piecewise.pieces\" target=\"_blank\">visualMap-piecewise.pieces</a>;</li>\n<li>Discrete data (data in category type): divide with <a href=\"option.html#visualMap-piecewise.categories\" target=\"_blank\">visualMap-piecewise.categories</a>.</li>\n</ul>\n<p><br>\n<strong>Configuration of visualMap mapping method</strong></p>\n<p>As we have introduced above, <code class=\"codespan\">visualMap</code> maps a certain dimension to a certain visual element, we can configure which dimension of the data (see in <a href=\"#visualMap.dimension\">visualMap.dimension</a>) to be mapped to which visual elements (see in <a href=\"option.html#visualMap.inRange\" target=\"_blank\">visualMap.inRange</a> and <a href=\"option.html#visualMap.outOfRange\" target=\"_blank\">visualMap.outOfRange</a>).</p>\n<p>Example A:</p>\n<pre><code class=\"lang-javascript\">option = {\n    visualMap: [\n        {\n            type: &#39;piecewise&#39;,\n            min: 0,\n            max: 5000,\n            dimension: 3,       // the fourth dimension of series.data, or value[3], is mapped\n            seriesIndex: 4,     // map with the fourth series\n            inRange: {          // visual configuration items in selected range\n                color: [&#39;blue&#39;, &#39;#121122&#39;, &#39;red&#39;], // defines color list of mapping\n                                                   // The largest value will be mapped to &#39;red&#39;,\n                                                   // and others will be interpolated\n                symbolSize: [30, 100]              // the smallest value will be mapped to size of 30,\n                                                   // the largest to 100,\n                                                   // and others will be interpolated\n            },\n            outOfRange: {       // visual configuration items out of selected range\n                symbolSize: [30, 100]\n            }\n        },\n        ...\n    ]\n};\n</code></pre>\n<p>Example B:</p>\n<pre><code class=\"lang-javascript\">option = {\n    visualMap: [\n        {\n            ...,\n            inRange: {          // visual configuration items in selected range\n                colorLightness: [0.2, 1], // map to lightness, which will process lightness based on original color\n                                          // original color may be selected from global color palette,\n                                          // which is not concerned by visualMap component\n                symbolSize: [30, 100]\n            },\n            ...\n        },\n        ...\n    ]\n};\n</code></pre>\n<p>For more information, please refer to <a href=\"option.html#visualMap.inRange\" target=\"_blank\">visualMap.inRange</a> and <a href=\"option.html#visualMap.outOfRange\" target=\"_blank\">visualMap.outOfRange</a>.</p>\n"},"Events and Actions in ECharts":{"type":["*"],"description":"<p>User interactions trigger corresponding events in Apache ECharts<sup>TM</sup>. Developers can listen to these events and handle accordingly through callback functions, e.g., redirecting to an address, popping out a dialog box, or drilling down data and so on.</p>\n<p>Binding events in ECharts 3 is though <a href=\"api.html#EChartsInstance.on\" target=\"_blank\">on</a> method, same as in ECharts 2. But event names are much simpler than it is in 2. Event names in ECharts 3 are the same as DOM event names, in lowercases. Below is an example of binding clicking operation.</p>\n<pre><code class=\"lang-js\">myChart.on(&#39;click&#39;, function (params) {\n    // printing data name in console\n    console.log(params.name);\n});\n</code></pre>\n<p>Event in ECharts can be divided in two kinds. One is mouse event, which is triggered when mouse clicks on certain component, the other is triggered with interaction components, such as triggering <a href=\"api.html#events.legendselectchanged\" target=\"_blank\">&#39;legendselectchanged&#39;</a> event when toggling legend (Notice here, that <code class=\"codespan\">&#39;legendselected&#39;</code> event will not be triggered when toggling legend), triggering <a href=\"api.html#events.legendselectchanged\" target=\"_blank\">&#39;datazoom&#39;</a> event when data zooming in some area.</p>\n<h2 id=\"mouse-events-handling\">Mouse Events Handling</h2>\n<p>ECharts support regular mouse events, which includes <code class=\"codespan\">&#39;click&#39;</code>, <code class=\"codespan\">&#39;dblclick&#39;</code>, <code class=\"codespan\">&#39;mousedown&#39;</code>, <code class=\"codespan\">&#39;mousemove&#39;</code>, <code class=\"codespan\">&#39;mouseup&#39;</code>, <code class=\"codespan\">&#39;mouseover&#39;</code>, <code class=\"codespan\">&#39;mouseout&#39;</code>, <code class=\"codespan\">&#39;globalout&#39;</code>, <code class=\"codespan\">&#39;contextmenu&#39;</code>. Next let&#39;s see an example of opening Baidu search page when clicks a bar chart.</p>\n<pre><code class=\"lang-js\">// initialize ECharts instance based on prepared dom\nvar myChart = echarts.init(document.getElementById(&#39;main&#39;));\n\n// data and configuration item of specific chart\nvar option = {\n    xAxis: {\n        data: [&quot;shirt&quot;,&quot;cardign&quot;,&quot;chiffon shirt&quot;,&quot;pants&quot;,&quot;heels&quot;,&quot;socks&quot;]\n    },\n    yAxis: {},\n    series: [{\n        name: &#39;sales&#39;,\n        type: &#39;bar&#39;,\n        data: [5, 20, 36, 10, 10, 20]\n    }]\n};\n// use specified configuration item and data to show chart\nmyChart.setOption(option);\n// handle click event and redirect to corresponding Baidu search page\nmyChart.on(&#39;click&#39;, function (params) {\n    window.open(&#39;https://www.baidu.com/s?wd=&#39; + encodeURIComponent(params.name));\n});\n</code></pre>\n<p>All types of mouse events have a common parameter called <code class=\"codespan\">params</code>, which is an object that contains data information of the clicked chart, whose format is as followed:</p>\n<pre><code class=\"lang-js\">{\n    // component name of clicked component\n    // e.g., &#39;series&#39;, &#39;markLine&#39;, &#39;markPoint&#39;, &#39;timeLine&#39;\n    componentType: string,\n    // series type (useful when componentType is &#39;series&#39;)\n    // e.g., &#39;line&#39;, &#39;bar&#39;, &#39;pie&#39;\n    seriesType: string,\n    // series index in option.series (useful when componentType is &#39;series&#39;)\n    seriesIndex: number,\n    // series name (useful when componentType is &#39;series&#39;)\n    seriesName: string,\n    // data name, or category name\n    name: string,\n    // data index in input data array\n    dataIndex: number,\n    // raw input data item\n    data: Object,\n    // Some series, such as sankey or graph, maintains both nodeData and edgeData,\n    // in which case, dataType is set to be &#39;node&#39; or &#39;edge&#39; to identify.\n    // On the other hand, most other series have only one type of data,\n    // where dataType is not needed.\n    dataType: string,\n    // input data value\n    value: number|Array\n    // color of component (useful when componentType is &#39;series&#39;)\n    color: string\n}\n</code></pre>\n<p>How to know where the mouse clicked:</p>\n<pre><code class=\"lang-js\">myChart.on(&#39;click&#39;, function (params) {\n    if (params.componentType === &#39;markPoint&#39;) {\n        // clicked on markPoint\n        if (params.seriesIndex === 5) {\n            // clicked on a markPoint which belongs to a series indexed with 5\n        }\n    }\n    else if (params.componentType === &#39;series&#39;) {\n        if (params.seriesType === &#39;graph&#39;) {\n            if (params.dataType === &#39;edge&#39;) {\n                // clicked on an edge of the graph\n            }\n            else {\n                // clicked on a node of the graph\n            }\n        }\n    }\n});\n</code></pre>\n<p>Use <code class=\"codespan\">query</code> to call handler only on the graphic elements of the specified components:</p>\n<pre><code class=\"lang-js\">chart.on(eventName, query, handler);\n</code></pre>\n<p><code class=\"codespan\">query</code> can be <code class=\"codespan\">string</code> or <code class=\"codespan\">Object</code>.</p>\n<p>If <code class=\"codespan\">string</code>, the formatter can be &#39;mainType&#39; or &#39;mainType.subType&#39;. For example:</p>\n<pre><code class=\"lang-js\">chart.on(&#39;click&#39;, &#39;series&#39;, function () {...});\nchart.on(&#39;click&#39;, &#39;series.line&#39;, function () {...});\nchart.on(&#39;click&#39;, &#39;dataZoom&#39;, function () {...});\nchart.on(&#39;click&#39;, &#39;xAxis.category&#39;, function () {...});\n</code></pre>\n<p>If <code class=\"codespan\">Object</code>, one or more properties below can be included, and any of them is optional.</p>\n<pre><code class=\"lang-js\">{\n    &lt;mainType&gt;Index: number // component index\n    &lt;mainType&gt;Name: string // component name\n    &lt;mainType&gt;Id: string // component id\n    dataIndex: number // data item index\n    name: string // data item name\n    dataType: string // data item type, e.g.,\n                     // &#39;node&#39; and &#39;edge&#39; in graph.\n    element: string // element name in custom series\n}\n</code></pre>\n<p>For example:</p>\n<pre><code class=\"lang-js\">chart.setOption({\n    // ...\n    series: [{\n        name: &#39;uuu&#39;\n        // ...\n    }]\n});\nchart.on(&#39;mouseover&#39;, {seriesName: &#39;uuu&#39;}, function () {\n    // When the graphic elements in the series with name &#39;uuu&#39; mouse overed, this method called.\n});\n</code></pre>\n<p>For example:</p>\n<pre><code class=\"lang-js\">chart.setOption({\n    // ...\n    series: [{\n        // ...\n    }, {\n        // ...\n        data: [\n            {name: &#39;xx&#39;, value: 121},\n            {name: &#39;yy&#39;, value: 33}\n        ]\n    }]\n});\nchart.on(&#39;mouseover&#39;, {seriesIndex: 1, name: &#39;xx&#39;}, function () {\n    // When the graphic elements of the data item with name &#39;xx&#39; in the series with index 1 mouse overed, this method called.\n});\n</code></pre>\n<p>For example:</p>\n<pre><code class=\"lang-js\">chart.setOption({\n    // ...\n    series: [{\n        type: &#39;graph&#39;,\n        nodes: [{name: &#39;a&#39;, value: 10}, {name: &#39;b&#39;, value: 20}],\n        edges: [{source: 0, target: 1}]\n    }]\n});\nchart.on(&#39;click&#39;, {dataType: &#39;node&#39;}, function () {\n    // When the nodes of the graph clicked, this method is called.\n});\nchart.on(&#39;click&#39;, {dataType: &#39;edge&#39;}, function () {\n    // When the edges of the graph clicked, this method is called.\n});\n</code></pre>\n<p>For example:</p>\n<pre><code class=\"lang-js\">chart.setOption({\n    // ...\n    series: {\n        // ...\n        type: &#39;custom&#39;,\n        renderItem: function (params, api) {\n            return {\n                type: &#39;group&#39;,\n                children: [{\n                    type: &#39;circle&#39;,\n                    name: &#39;my_el&#39;,\n                    // ...\n                }, {\n                    // ...\n                }]\n            }\n        },\n        data: [[12, 33]]\n    }\n})\nchart.on(&#39;click&#39;, {element: &#39;my_el&#39;}, function () {\n    // When the element with name &#39;my_el&#39; clicked, this method called.\n});\n</code></pre>\n<p>You may update chart or show customized layer with information got from your own data warehouse, indexed from data name or series name of an object received from a callback function. Sample code is shown as followed:</p>\n<pre><code class=\"lang-js\">myChart.on(&#39;click&#39;, function (parmas) {\n    $.get(&#39;detail?q=&#39; + params.name, function (detail) {\n        myChart.setOption({\n            series: [{\n                name: &#39;pie&#39;,\n                // present data distribution  of a single bar through pie chart\n                data: [detail.data]\n            }]\n        });\n    });\n});\n</code></pre>\n<h2 id=\"interaction-events-with-components\">Interaction Events with Components</h2>\n<p>Basically all component interactions in ECharts trigger corresponding events. Frequently used events and corresponding parameters are listed in <a href=\"api.html#events\" target=\"_blank\">events</a>.</p>\n<p>Below is example that listens to a legend toggling:</p>\n<pre><code class=\"lang-js\">// legend toggling triggers legendselectchanged event only\nmyChart.on(&#39;legendselectchanged&#39;, function (params) {\n    // obtain selecting status of clicked legend\n    var isSelected = params.selected[params.name];\n    // print in console\n    console.log((isSelected ? &#39;select&#39; : &#39;unselect&#39;) + &#39;legend&#39; + params.name);\n    // print all legend status\n    console.log(params.selected);\n});\n</code></pre>\n<h2 id=\"triggering-component-actions-through-code-in-echarts\">Triggering Component Actions through Code in ECharts</h2>\n<p>Actions like <code class=\"codespan\">&#39;legendselectchanged&#39;</code> mentioned above will be triggered by component interaction. Besides that, sometimes we need to trigger certain actions in our program, such as showing tooltip, or selecting legend.</p>\n<p>ECharts 2.x triggers actions through <code class=\"codespan\">myChart.component.tooltip.showTip</code>, whose entrance is deep and involves organization of inner components. On the other hand, ECharts 3 triggers actions through <code class=\"codespan\">myChart.dispatchAction({ type: &#39;&#39; })</code>, which manages all actions in a uniformed way, and may record user&#39;s event path when need.</p>\n<p>Frequently used actions and the parameters are listed in <a href=\"api.html#action\" target=\"_blank\">action</a>.</p>\n<p>Below displays how to highlight each sector of pie chart in turn through <code class=\"codespan\">dispatchAction</code>.</p>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=doc-example/pie-highlight&edit=1&reset=1\" width=\"600\" height=\"400\" ></iframe>\n\n\n\n<h2 id=\"listen-to-events-from-the-blank\">Listen to events from the blank</h2>\n<p>Sometimes developers need to listen to the events that are triggered from the blank of the canvas. For example, need to reset the chart when users click on the blank.</p>\n<p>Before we talk about this feature, we need to clarify two kinds of events: <code class=\"codespan\">zrender events</code> and <code class=\"codespan\">echarts events</code>.</p>\n<pre><code class=\"lang-js\">myChart.getZr().on(&#39;click&#39;, function (event) {\n    // This listener is listening to a `zrender event`.\n});\nmyChart.on(&#39;click&#39;, function (event) {\n    // This listener is listening to a `echarts event`.\n});\n</code></pre>\n<p><code class=\"codespan\">zrender events</code> are different from <code class=\"codespan\">echarts events</code>. The former one are triggered when mouse/pointer is at everywhere, while the latter one can only be triggered when mouse/pointer is at the graphic elements. In fact, <code class=\"codespan\">echarts events</code> are implemented based on <code class=\"codespan\">zrender events</code>, that is, when a <code class=\"codespan\">zrender events</code> is triggered at a graphic element, <code class=\"codespan\">echarts</code> will trigger a <code class=\"codespan\">echarts event</code>.</p>\n<p>Having <code class=\"codespan\">zrender events</code>, we can implement &quot;listen to events from the blank&quot; as follows:</p>\n<pre><code class=\"lang-js\">myChart.getZr().on(&#39;click&#39;, function (event) {\n    // No &quot;target&quot; means that mouse/pointer is not on\n    // any of the graphic elements, which is &quot;blank&quot;.\n    if (!event.target) {\n        // Click on blank. Do something.\n    }\n});\n</code></pre>\n"},"Bar Race":{"type":["*"],"description":"<p>Bar race is a chart that shows changes in the ranking of data over time and it is supported by default sinde ECharts 5.</p>\n<blockquote>\n<p>Bar race charts usually use horizontal bars. If you want to use vertical bars, just take the X axis and Y axis in this tutorial to the opposite.</p>\n</blockquote>\n<ol>\n<li>Set <code class=\"codespan\">yAxis.realtimeSort</code> to be <code class=\"codespan\">true</code> to enable bar race</li>\n<li>Set <code class=\"codespan\">yAxis.inverse</code> to be <code class=\"codespan\">true</code> to display longer bars at top</li>\n<li><code class=\"codespan\">yAxis.animationDuration</code> is suggested to be set to be <code class=\"codespan\">300</code> for bar reordering animation for the first time</li>\n<li><code class=\"codespan\">yAxis.animationDurationUpdate</code> is suggested to be set to be <code class=\"codespan\">300</code> for bar reordering animation for later times</li>\n<li>Set <code class=\"codespan\">yAxis.max</code> to be <em>n - 1</em> where <em>n</em> is the number of bars to be displayed; otherwise, all bars are displayed</li>\n<li><code class=\"codespan\">xAxis.max</code> is suggested to be set to be <code class=\"codespan\">&#39;dataMax&#39;</code> so that the maximum of data is used as X maximum.</li>\n<li>If realtime label changing is required, set <code class=\"codespan\">series.label.valueAnimation</code> to be <code class=\"codespan\">true</code></li>\n<li>Set <code class=\"codespan\">animationDuration</code> to be <code class=\"codespan\">0</code> so that the first animation doesn&#39;t start from 0; if you wish otherwise, set it to be the same value as <code class=\"codespan\">animationDurationUpdate</code></li>\n<li><code class=\"codespan\">animationDurationUpdate</code> is suggested to be set to be <code class=\"codespan\">3000</code> for animation update duration, which should be the same as the frequency of calling <code class=\"codespan\">setOption</code></li>\n<li>Call <code class=\"codespan\">setOption</code> to update data to be of next time with <code class=\"codespan\">setInterval</code> at the frequency of <code class=\"codespan\">animationDurationUpdate</code></li>\n</ol>\n<p>A full example is:</p>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=bar-race&edit=1&reset=1\" width=\"700\" height=\"300\" ></iframe>\n\n\n<p>As you see, there are many options to be set to enable bar race effect. We are going to provide a tool that doesn&#39;t require any coding to help you make bar race charts more easily.</p>\n"},"An Example: Implement Dragging":{"type":["*"],"description":"<p>This is a tiny example, introducing how to implement dragging of graphic elements in Apache ECharts<sup>TM</sup>. From this example, we will see how to make an application with rich intractivity based on echarts API.</p>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=line-draggable&edit=1&reset=1\" width=\"600\" height=\"400\" ></iframe>\n\n\n<p>This example mainly implements that dragging points of a curve and by which the curve is modified. Although it is simple example, but we can do more based on that, like edit charts viually. So let&#39;s get started from this simple example.</p>\n<h2 id=\"-part-1-implement-basic-dragging\">[ Part 1 ] Implement basic dragging</h2>\n<p>First of all, we create a basic <a href=\"option.html#series-line\" target=\"_blank\">line chart (line series)</a>:</p>\n<pre><code class=\"lang-js\">var symbolSize = 20;\nvar data = [[15, 0], [-50, 10], [-56.5, 20], [-46.5, 30], [-22.1, 40]];\n\nmyChart.setOption({\n    xAxis: {\n        min: -100,\n        max: 80,\n        type: &#39;value&#39;,\n        axisLine: {onZero: false}\n    },\n    yAxis: {\n        min: -30,\n        max: 60,\n        type: &#39;value&#39;,\n        axisLine: {onZero: false}\n    },\n    series: [\n        {\n            id: &#39;a&#39;,\n            type: &#39;line&#39;,\n            smooth: true,\n            // Set a big symbolSize for dragging convenience.\n            symbolSize: symbolSize,\n            data: data\n        }\n    ]\n});\n</code></pre>\n<p>Since the symbols in line is not draggable, we make them draggable by using <a href=\"option.html#graphic\" target=\"_blank\">graphic component</a> to add draggable circular elements to symbols respectively.</p>\n<pre><code class=\"lang-js\">myChart.setOption({\n    // Declare a graphic component, which contains some graphic elements\n    // with the type of &#39;circle&#39;.\n    // Here we have used the method `echarts.util.map`, which has the same\n    // behavior as Array.prototype.map, and is compatible with ES5-.\n    graphic: echarts.util.map(data, function (dataItem, dataIndex) {\n        return {\n            // &#39;circle&#39; means this graphic element is a shape of circle.\n            type: &#39;circle&#39;,\n\n            shape: {\n                // The radius of the circle.\n                r: symbolSize / 2\n            },\n            // Transform is used to located the circle. position:\n            // [x, y] means translate the circle to the position [x, y].\n            // The API `convertToPixel` is used to get the position of\n            // the circle, which will introduced later.\n            position: myChart.convertToPixel(&#39;grid&#39;, dataItem),\n\n            // Make the circle invisible (but mouse event works as normal).\n            invisible: true,\n            // Make the circle draggable.\n            draggable: true,\n            // Give a big z value, which makes the circle cover the symbol\n            // in line series.\n            z: 100,\n            // This is the event handler of dragging, which will be triggered\n            // repeatly while dragging. See more details below.\n            // A util method `echarts.util.curry` is used here to generate a\n            // new function the same as `onPointDragging`, except that the\n            // first parameter is fixed to be the `dataIndex` here.\n            ondrag: echarts.util.curry(onPointDragging, dataIndex)\n        };\n    })\n});\n</code></pre>\n<p>In the code above, API <a href=\"api.html#echartsInstance.convertToPixel\" target=\"_blank\">convertToPixel</a> is used to convert data to its &quot;pixel coodinate&quot;, based on which each graphic elements can be rendered on canvas. The term &quot;pixel coodinate&quot; means the coordinate is in canvas pixel, whose origin is the top-left of the canvas. In the sentence <code class=\"codespan\">myChart.convertToPixel(&#39;grid&#39;, dataItem)</code>, the first parameter <code class=\"codespan\">&#39;grid&#39;</code> indicates that <code class=\"codespan\">dataItem</code> should be converted in the first <a href=\"option.html#grid\" target=\"_blank\">grid component (cartesian)</a>.</p>\n<p><strong>Notice:</strong> <code class=\"codespan\">convertToPixel</code> should not be called before the first time that <code class=\"codespan\">setOption</code> called. Namely, it can only be used after coordinate systems (grid/polar/...) initialized.</p>\n<p>Now points have been made draggable. Then we will bind event listeners on dragging to those points.</p>\n<pre><code class=\"lang-js\">// This function will be called repeatly while dragging.\n// The mission of this function is to update `series.data` based on\n// the new points updated by dragging, and to re-render the line\n// series based on the new data, by which the graphic elements of the\n// line series can be synchronized with dragging.\nfunction onPointDragging(dataIndex) {\n    // Here the `data` is declared in the code block in the beginning\n    // of this article. The `this` refers to the dragged circle.\n    // `this.position` is the current position of the circle.\n    data[dataIndex] = myChart.convertFromPixel(&#39;grid&#39;, this.position);\n    // Re-render the chart based on the updated `data`.\n    myChart.setOption({\n        series: [{\n            id: &#39;a&#39;,\n            data: data\n        }]\n    });\n}\n</code></pre>\n<p>In the code above, API <a href=\"api.html#echartsInstance.convertFromPixel\" target=\"_blank\">convertFromPixel</a> is used, which is the reversed process of <a href=\"api.html#echartsInstance.convertToPixel\" target=\"_blank\">convertToPixel</a>. <code class=\"codespan\">myChart.convertFromPixel(&#39;grid&#39;, this.position)</code> converts a pixel coordinate to data item in <a href=\"option.html#grid\" target=\"_blank\">grid (cartesian)</a>.</p>\n<p>Finally, add those code to make graphic elements responsive to change of canvas size.</p>\n<pre><code class=\"lang-js\">window.addEventListener(&#39;resize&#39;, function () {\n    // Re-calculate the position of each circle and update chart using `setOption`.\n    myChart.setOption({\n        graphic: echarts.util.map(data, function (item, dataIndex) {\n            return {\n                position: myChart.convertToPixel(&#39;grid&#39;, item)\n            };\n        })\n    });\n});\n\n</code></pre>\n<h2 id=\"-part-2-add-tooltip-component\">[ Part 2 ] Add tooltip component</h2>\n<p>Now basic functionality have been implemented by parte 1. If we need the data can be displayed realtime when dragging, we can use <a href=\"option.html#tooltip\" target=\"_blank\">tooltip component</a> to do that. Nevertheless, tooltip component has its default &quot;show/hide rule&quot;, which is not applicable in this case. So we need to customize the &quot;show/hide rule&quot; for our case.</p>\n<p>Add these snippets to the code block above:</p>\n<pre><code class=\"lang-js\">myChart.setOption({\n    ...,\n    tooltip: {\n        // Means disable default &quot;show/hide rule&quot;.\n        triggerOn: &#39;none&#39;,\n        formatter: function (params) {\n            return &#39;X: &#39; + params.data[0].toFixed(2) + &#39;&lt;br&gt;Y: &#39; + params.data[1].toFixed(2);\n        }\n    }\n});\n</code></pre>\n<pre><code class=\"lang-js\">myChart.setOption({\n    graphic: echarts.util.map(data, function (item, dataIndex) {\n        return {\n            type: &#39;circle&#39;,\n            ...,\n            // Customize &quot;show/hide rule&quot;, show when mouse over, hide when mouse out.\n            onmousemove: echarts.util.curry(showTooltip, dataIndex),\n            onmouseout: echarts.util.curry(hideTooltip, dataIndex),\n        };\n    })\n});\n\nfunction showTooltip(dataIndex) {\n    myChart.dispatchAction({\n        type: &#39;showTip&#39;,\n        seriesIndex: 0,\n        dataIndex: dataIndex\n    });\n}\n\nfunction hideTooltip(dataIndex) {\n    myChart.dispatchAction({\n        type: &#39;hideTip&#39;\n    });\n}\n</code></pre>\n<p>The API <a href=\"api.html#echartsInstance.dispatchAction\" target=\"_blank\">dispatchAction</a> is used to show/hide tooltip content, where actions <a href=\"api.html#action.tooltip.showTip\" target=\"_blank\">showTip</a> and <a href=\"api.html#action.tooltip.hideTip\" target=\"_blank\">hideTip</a> is dispatched.</p>\n<h2 id=\"-part-3-full-code\">[ Part 3 ] Full code</h2>\n<p>Full code is shown as follow:</p>\n<pre><code>&lt;!DOCTYPE html&gt;\n&lt;html&gt;\n&lt;head&gt;\n    &lt;meta charset=&quot;utf-8&quot;&gt;\n    &lt;script src=&quot;dist/echarts.min.js&quot;&gt;&lt;/script&gt;\n&lt;/head&gt;\n&lt;body&gt;\n    &lt;div id=&quot;main&quot; style=&quot;width: 600px;height:400px;&quot;&gt;&lt;/div&gt;\n    &lt;script type=&quot;text/javascript&quot;&gt;\n\n    var symbolSize = 20;\n    var data = [[15, 0], [-50, 10], [-56.5, 20], [-46.5, 30], [-22.1, 40]];\n\n    var myChart = echarts.init(document.getElementById(&#39;main&#39;));\n\n    myChart.setOption({\n        tooltip: {\n            triggerOn: &#39;none&#39;,\n            formatter: function (params) {\n                return &#39;X: &#39; + params.data[0].toFixed(2) + &#39;&lt;br&gt;Y: &#39; + params.data[1].toFixed(2);\n            }\n        },\n        xAxis: {\n            min: -100,\n            max: 80,\n            type: &#39;value&#39;,\n            axisLine: {onZero: false}\n        },\n        yAxis: {\n            min: -30,\n            max: 60,\n            type: &#39;value&#39;,\n            axisLine: {onZero: false}\n        },\n        series: [\n            {\n                id: &#39;a&#39;,\n                type: &#39;line&#39;,\n                smooth: true,\n                symbolSize: symbolSize,\n                data: data\n            }\n        ],\n    });\n\n    myChart.setOption({\n        graphic: echarts.util.map(data, function (item, dataIndex) {\n            return {\n                type: &#39;circle&#39;,\n                position: myChart.convertToPixel(&#39;grid&#39;, item),\n                shape: {\n                    r: symbolSize / 2\n                },\n                invisible: true,\n                draggable: true,\n                ondrag: echarts.util.curry(onPointDragging, dataIndex),\n                onmousemove: echarts.util.curry(showTooltip, dataIndex),\n                onmouseout: echarts.util.curry(hideTooltip, dataIndex),\n                z: 100\n            };\n        })\n    });\n\n    window.addEventListener(&#39;resize&#39;, function () {\n        myChart.setOption({\n            graphic: echarts.util.map(data, function (item, dataIndex) {\n                return {\n                    position: myChart.convertToPixel(&#39;grid&#39;, item)\n                };\n            })\n        });\n    });\n\n    function showTooltip(dataIndex) {\n        myChart.dispatchAction({\n            type: &#39;showTip&#39;,\n            seriesIndex: 0,\n            dataIndex: dataIndex\n        });\n    }\n\n    function hideTooltip(dataIndex) {\n        myChart.dispatchAction({\n            type: &#39;hideTip&#39;\n        });\n    }\n\n    function onPointDragging(dataIndex, dx, dy) {\n        data[dataIndex] = myChart.convertFromPixel(&#39;grid&#39;, this.position);\n        myChart.setOption({\n            series: [{\n                id: &#39;a&#39;,\n                data: data\n            }]\n        });\n    }\n\n&lt;/script&gt;\n&lt;/body&gt;\n&lt;/html&gt;\n</code></pre><p><br></p>\n<p>With knowledge introduced above, more feature can be implemented. For example, <a href=\"option.html#dataZoom\" target=\"_blank\">dataZoom component</a> can be added to cooperate with the cartesian, or we can make a plotting board on coordinate systems. Use your imagination ~</p>\n"},"Custom Series":{"type":["*"],"description":"<p><a href=\"option.html#series-custom\" target=\"_blank\">custom series</a> is a type of series, which enable develpers to customize graphic elements rendering and generate new types of chart.</p>\n<p>Why does Apache ECharts<sup>TM</sup> supports <code class=\"codespan\">custom series</code>?</p>\n<p>There are endless chart types in the world of data visualization, which are not enumerable. Thus only most common used chart types are built-in supported in echarts. For other chart types, it is necessary to provide an approach to make new types of chart for developers. This approach should be as simple as possible, which had better not to bothered developers with some details of implementation, such as creating and deleting graphic elements, transition animation, tooltip supporting, working with <a href=\"option.html#dataZoom\" target=\"_blank\">dataZoom</a> or <a href=\"option.html#visualMap\" target=\"_blank\">visualMap</a>. Having considered the factors above, a solution <a href=\"option.html#series-custom\" target=\"_blank\">custom series</a> is published.</p>\n<p><strong>For example, a &quot;x-range&quot; chart is made by custom sereis:</strong></p>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=custom-profile&reset=1&edit=1\" width=\"800\" height=\"500\" ></iframe>\n\n\n<p><strong><a href=\"https://echarts.apache.org/examples/en/index.html#chart-type-custom\" target=\"_blank\">More samples of custom series</a></strong></p>\n<p>Let&#39;s begin the tutorial.</p>\n<h2 id=\"-i-the-method-renderitem\">(I) The method <code class=\"codespan\">renderItem</code></h2>\n<p>The snippet of graphic elements rendering should be written in <code class=\"codespan\">renderItem</code> method my developers. For example:</p>\n<pre><code class=\"lang-js\">var option = {\n    ...,\n    series: [{\n        type: &#39;custom&#39;,\n        renderItem: function (params, api) {\n            // ...\n        },\n        data: data\n    }]\n}\n</code></pre>\n<p>In the rendering phase of echarts workflow, <a href=\"option.html#series-custom.renderItem\" target=\"_blank\">renderItem</a> is called respectively for each <code class=\"codespan\">dataItem</code> in <a href=\"option.html#series-custom.data\" target=\"_blank\">series.data</a>. <code class=\"codespan\">renderItem</code> is responsible for build a group of definitions of graphic elements, including graphic type, size, location, style, etc. echarts will then build graphic elements according to those definitions. For example:</p>\n<pre><code class=\"lang-js\">var option = {\n    ...,\n    series: [{\n        type: &#39;custom&#39;,\n        renderItem: function (params, api) {\n            // This method will be called for each dataItem repectively.\n            // Notice: it does not ensure that called according to the order\n            // of `dataItem`.\n\n            // Some processes, such as coordinate conversion.\n            // `api.value(0)` is used to retrieve the value on the first\n            // dimension in the current `dataItem`.\n            var categoryIndex = api.value(0);\n            // `api.coord(...)` is used to convert data values to pixel values,\n            // will are necessary for graphic elements rendering.\n            var startPoint = api.coord([api.value(1), categoryIndex]);\n            var endPoint = api.coord([api.value(2), categoryIndex]);\n            // `api.size(...)` is used to calculate the pixel size corresponding to\n            // the a value range that the length is 1 on Y axis.\n            var height = api.size([0, 1])[1] * 0.6;\n\n            // The property `shape` incicates the location and size of thsi\n            // element.\n            // `echarts.graphic.clipRectByRect` is used for clipping the\n            // rectangular when it overflow the bounding box of the current\n            // coordinate system (cartesian).\n            // If the rect is totally clipped, returns undefined.\n            var rectShape = echarts.graphic.clipRectByRect({\n                // position and location of the rectangular.\n                x: startPoint[0],\n                y: startPoint[1] - height / 2,\n                width: endPoint[0] - startPoint[0],\n                height: height\n            }, {\n                // Bounding box of the current cooridinate system (cartesian).\n                x: params.coordSys.x,\n                y: params.coordSys.y,\n                width: params.coordSys.width,\n                height: params.coordSys.height\n            })\n\n            // Returns definitions for the current `dataItem`.\n            return rectShape &amp;&amp; {\n                // &#39;rect&#39; indicates that the graphic element is rectangular.\n                // Can also be &#39;circle&#39;, &#39;sector&#39;, &#39;polygon&#39;, ...\n                type: &#39;rect&#39;,\n                shape: rectShape,\n                // `api.style(...)` is used to obtain style settings, which\n                // includes itemStyle settings in optino and the result of\n                // visual mapping.\n                style: api.style()\n            };\n        },\n        data: [\n            [12, 44, 55, 60], // The first dataItem.\n            [53, 31, 21, 56], // The second dataItem.\n            [71, 33, 10, 20], // The third dataItem.\n            ...\n        ]\n    }]\n}\n</code></pre>\n<p><a href=\"option.html#series-custom.renderItem\" target=\"_blank\">renderItem</a> provides two parameters:</p>\n<ul>\n<li><a href=\"option.html#series-custom.renderItem.arguments.params\" target=\"_blank\">params</a>：provides info about the current series (such as <code class=\"codespan\">seriesIndex</code>、<code class=\"codespan\">dataIndex</code>, etc.) and data (such as <code class=\"codespan\">dataIndex</code>, <code class=\"codespan\">dataIndexInside</code>, etc.) and coordinate system (such as location and size of bounding box of the current coordinate system)</li>\n<li><a href=\"option.html#series-custom.renderItem.arguments.api\" target=\"_blank\">api</a> provides some methods to developers (such as <code class=\"codespan\">api.value()</code>, <code class=\"codespan\">api.coord()</code>).</li>\n</ul>\n<p><a href=\"option.html#series-custom.renderItem\" target=\"_blank\">renderItem</a> method should return definitions of graphic elements for the current <code class=\"codespan\">dataItem</code>. See <a href=\"option.html#series-custom.renderItem.return\" target=\"_blank\">renderItem.return</a>.</p>\n<p>Generally, the main process of <a href=\"option.html#series-custom.renderItem\" target=\"_blank\">renderItem</a> is that retrieve value from data and convert them to graphic elements on the current coordinate system. Two methods in <a href=\"option.html#series-custom.renderItem.arguments.api\" target=\"_blank\">renderItem.arguments.api</a> are always used in this procedure:</p>\n<ul>\n<li><a href=\"option.html#series-custom.renderItem.arguments.api.value\" target=\"_blank\">api.value(...)</a> is used to retrieve value from data. For example, <code class=\"codespan\">api.value(0)</code> retrieve the value of the first dimension in the current data item.</li>\n<li><a href=\"option.html#series-custom.renderItem.arguments.api.coord\" target=\"_blank\">api.coord(...)</a> is used to convert data to coordinate. For example, <code class=\"codespan\">var point = api.coord([api.value(0), api.value(1)])</code> converet the data to the point on the current coordinate system.</li>\n</ul>\n<p>Sometimes <a href=\"option.html#series-custom.renderItem.arguments.api.size\" target=\"_blank\">api.size(...)</a> method is needed, which calculates the size on the coordinate system by a given data range.</p>\n<p>Moreover, <a href=\"option.html#series-custom.renderItem.arguments.api.style\" target=\"_blank\">api.style(...)</a> method can be used to set style. It provides not only the style settings specified in <a href=\"option.html#series-custom.itemStyle\" target=\"_blank\">series.itemStyle</a>, but also the result of visual mapping. This method can also be called like <code class=\"codespan\">api.style({fill: &#39;green&#39;, stroke: &#39;yellow&#39;})</code> to override those style settings.</p>\n<p>Having <code class=\"codespan\">renderItem</code> provided, 90% of the work of creating custom series has been accomplished. The rest of this work is to refine and polish them.</p>\n<h2 id=\"-ii-make-the-extent-of-axes-fit-the-data\">(II) Make the extent of axes fit the data</h2>\n<p>There is axes in some coordinate systems, such as <a href=\"option.html#grid\" target=\"_blank\">cartesian2d (grid)</a>and <a href=\"option.html#polar\" target=\"_blank\">polar</a>. The extent of an axis should fit the data automatically, otherwise the graphic elements would be overflow the bounding box of the coordinate system. So, for example, in <a href=\"option.html#grid\" target=\"_blank\">cartesian2d (grid)</a>, developers should specify that which dimensions correspond to <code class=\"codespan\">x</code> axis and which to <code class=\"codespan\">y</code> axis use the property <a href=\"option.html#series-custom.encode\" target=\"_blank\">encode</a>:</p>\n<pre><code class=\"lang-js\">option = {\n    series: [{\n        type: &#39;custom&#39;,\n        renderItem: function () {\n            ...\n        },\n        encode: {\n            // `dim1` and `dim2` correspond to `x` axis.\n            x: [1, 2],\n            // `dim0` corresponds to `y` axis.\n            y: 0\n        },\n        data: [\n            // dim0  dim1  dim2  dim3\n            [   12,   44,   55,   60   ], // The first dataItem.\n            [   53,   31,   21,   56   ], // The second dataItem.\n            [   71,   33,   10,   20   ], // The third dataItem.\n            ...\n        ]\n    }]\n};\n</code></pre>\n<h2 id=\"-iii-set-tooltip-content\">(III) Set tooltip content</h2>\n<p>Of course <a href=\"option.html#tooltip.formatter\" target=\"_blank\">tooltip.formatter</a> can be used to define the content in tooltip. But it is easier to do that by setting <a href=\"option.html#series-custom.encode\" target=\"_blank\">encode</a> and <a href=\"option.html#series-custom.dimensions\" target=\"_blank\">dimensions</a>:</p>\n<pre><code class=\"lang-js\">option = {\n    series: [{\n        type: &#39;custom&#39;,\n        renderItem: function () {\n            ...\n        },\n        encode: {\n            x: [1, 2],\n            y: 0,\n            // `dim2` and `dim3` will displayed in tooltip.\n            tooltip: [2, 3]\n        },\n        // `dim2` is named as &quot;Age&quot; and `dim3` is named as &quot;Satisfaction&quot;.\n        dimensions: [null, null, &#39;Age&#39;, &#39;Satisfaction&#39;],\n        data: [\n            // dim0  dim1  dim2  dim3\n            [   12,   44,   55,   60   ],\n            [   53,   31,   21,   56   ],\n            [   71,   33,   10,   20   ],\n            ...\n        ]\n    }]\n};\n</code></pre>\n<p><br>\n<br>\n<br></p>\n<hr>\n<p>Several other issues about <code class=\"codespan\">custom series</code> are introduced below.</p>\n<h2 id=\"-iv-shape-clipping-when-overflow-the-coordinates-area\">(IV) Shape clipping when overflow the coordinates area</h2>\n<p>When use <code class=\"codespan\">custom series</code> with <a href=\"option.html#dataZoom\" target=\"_blank\">dataZoom</a>, <a href=\"option.html#dataZoom.filterMode\" target=\"_blank\">dataZoom.filterMode</a> usually be set as <code class=\"codespan\">&#39;weakFilter&#39;</code>, which prevent <code class=\"codespan\">dataItem</code> from being filtered when only part of its dimensions are out of the current data window. For example:</p>\n<pre><code class=\"lang-js\">option = {\n    dataZoom: {\n        xAxisIndex: 0,\n        filterMode: &#39;weakFilter&#39;\n    },\n    series: [{\n        type: &#39;custom&#39;,\n        renderItem: function () {\n            ...\n        },\n        encode: {\n            x: [1, 2],\n            y: 0\n        },\n        data: [\n            // dim0  dim1  dim2  dim3\n            [   12,   44,   55,   60   ], // The first dataItem.\n            [   53,   31,   21,   56   ], // The second dataItem.\n            [   71,   33,   10,   20   ], // The third dataItem.\n            ...\n        ]\n    }]\n};\n</code></pre>\n<p>In the example above, <code class=\"codespan\">dim</code> and <code class=\"codespan\">dim2</code> corresponds to <code class=\"codespan\">x</code> axis, and the <code class=\"codespan\">dataZoom</code> component constrols the data window of <code class=\"codespan\">x</code> axis. If part of a <code class=\"codespan\">dataItem</code> is overflow the extent of <code class=\"codespan\">x</code> axis (the value on <code class=\"codespan\">dim1</code> is overflow and the value on <code class=\"codespan\">dim2</code> is not) while zooming, the <code class=\"codespan\">dataItem</code> will not be filtered if <code class=\"codespan\">dataZoom.filterMode = &#39;weakFilter&#39;</code> set. Thus the <code class=\"codespan\">dataItem</code> can be still rendered (usually be partially rendered by using <code class=\"codespan\">echarts.graphic.clipRectByRect</code> to clip the exceeding part).\nSee the example mentioned above <a href=\"https://echarts.apache.org/examples/en/editor.html?c=custom-profile\" target=\"_blank\">Profile</a>.</p>\n<h2 id=\"-v-about-dataindex\">(V) About dataIndex</h2>\n<p>Developers had better notice that in <a href=\"option.html#series-custom.renderItem.arguments.params\" target=\"_blank\">renderItem.arguments.params</a> <code class=\"codespan\">dataIndexInside</code> and <code class=\"codespan\">dataIndex</code> is different:</p>\n<ul>\n<li><code class=\"codespan\">dataIndex</code> is the index of a <code class=\"codespan\">dataItem</code> in the original data.</li>\n<li><code class=\"codespan\">dataIndexInside</code> is the index of a <code class=\"codespan\">dataItem</code> in the current data window (see <a href=\"option.html#dataZoom\" target=\"_blank\">dataZoom</a>.</li>\n</ul>\n<p><a href=\"option.html#series-custom.renderItem.arguments.api\" target=\"_blank\">renderItem.arguments.api</a> uses <code class=\"codespan\">dataIndexInside</code> as the input parameter but not <code class=\"codespan\">dataIndex</code>, because conversion from <code class=\"codespan\">dataIndex</code> to <code class=\"codespan\">dataIndexInside</code> is time-consuming.</p>\n<h2 id=\"-vi-event-listener\">(VI) Event listener</h2>\n<pre><code class=\"lang-js\">chart.setOption({\n    // ...\n    series: {\n        type: &#39;custom&#39;,\n        renderItem: function () {\n            // ...\n            return {\n                type: &#39;group&#39;,\n                children: [{\n                    type: &#39;circle&#39;\n                    // ...\n                }, {\n                    type: &#39;circle&#39;,\n                    name: &#39;aaa&#39;,\n                    // User specified info, available\n                    // in event handler.\n                    info: 12345,\n                    // ...\n                }]\n            };\n        }\n    }\n});\nchart.on(&#39;click&#39;, {element: &#39;aaa&#39;}, function (params) {\n    // When the element with name &#39;aaa&#39; clicked,\n    // this method called.\n    console.log(params.info);\n});\n</code></pre>\n<h2 id=\"-vii-custom-vector-shapes\">(VII) Custom vector shapes</h2>\n<p><a href=\"http://www.w3.org/TR/SVG/paths.html#PathData\" target=\"_blank\">SVG PathData</a> is supported, which enables to use shapes that are created in vector tool. See <a href=\"option.html#series-custom.renderItem.return_path\" target=\"_blank\">path</a>, and examples: <a href=\"https://echarts.apache.org/examples/en/editor.html?c=custom-calendar-icon\" target=\"_blank\">icons</a>, <a href=\"https://echarts.apache.org/examples/en/editor.html?c=custom-gantt-flight\" target=\"_blank\">shapes</a>.</p>\n<p><br></p>\n<p><strong><a href=\"https://echarts.apache.org/examples/en/index.html#chart-type-custom\" target=\"_blank\">More examples about custom series</a></strong></p>\n"},"Rich Text":{"type":["*"],"description":"<p>Rich text can be used in Apache ECharts<sup>TM</sup> labels of series, axis or other components. For example:</p>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=pie-rich-text&edit=1&reset=1\" width=\"800\" height=\"400\" ></iframe>\n\n\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=treemap-obama&edit=1&reset=1\" width=\"800\" height=\"550\" ></iframe>\n\n\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=bar-rich-text&edit=1&reset=1\" width=\"800\" height=\"400\" ></iframe>\n\n\n<p><br></p>\n<p>More examples:\n<a href=\"https://echarts.apache.org/examples/en/editor.html?c=map-labels&amp;edit=1&amp;reset=1\" target=\"_blank\">Map Labels</a>,\n<a href=\"https://echarts.apache.org/examples/en/editor.html?c=pie-nest&amp;edit=1&amp;reset=1\" target=\"_blank\">Pie Labels</a>,\n<a href=\"https://echarts.apache.org/examples/en/editor.html?c=gauge-car&amp;edit=1&amp;reset=1\" target=\"_blank\">Gauge</a>.</p>\n<p><br></p>\n<p>Before v3.7, the style options was only able to applied to the whole label text block, and only color and font can be configured, which restricted the expressability of text descriptions.</p>\n<p>Since v3.7, rich text has been supported:</p>\n<ul>\n<li>Box styles (background, border, shadow, etc.), rotation, position of a text block can be specified.</li>\n<li>Styles (color, font, width/height, background, shadow, etc.) and alignment can be customzied on fragments of text.</li>\n<li>Image can be used in text as icon or background.</li>\n<li>Combine these configurations, some special effects can be made, such as simple table, horizontal rule (hr).</li>\n</ul>\n<p>At the beginning, the meanings of two terms that will be used below should be clarified:</p>\n<ul>\n<li>Text Block: The whole block of label text.</li>\n<li>Text fragment: Some piece of text in a text block.</li>\n</ul>\n<p>For example:</p>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=doc-example/text-block-fragment&edit=1&reset=1\" width=\"340\" height=\"240\" ></iframe>\n\n\n\n<h2 id=\"options-about-text\">Options about Text</h2>\n<p>echarts provides plenty of text options, including:</p>\n<ul>\n<li>Basic font style: <code class=\"codespan\">fontStyle</code>, <code class=\"codespan\">fontWeight</code>, <code class=\"codespan\">fontSize</code>, <code class=\"codespan\">fontFamily</code>.</li>\n<li>Fill of text: <code class=\"codespan\">color</code>.</li>\n<li>Stroke of text: <code class=\"codespan\">textBorderColor</code>, <code class=\"codespan\">textBorderWidth</code>.</li>\n<li>Shadow of text: <code class=\"codespan\">textShadowColor</code>, <code class=\"codespan\">textShadowBlur</code>, <code class=\"codespan\">textShadowOffsetX</code>, <code class=\"codespan\">textShadowOffsetY</code>.</li>\n<li>Box size of text block or text fragment: <code class=\"codespan\">lineHeight</code>, <code class=\"codespan\">width</code>, <code class=\"codespan\">height</code>, <code class=\"codespan\">padding</code>.</li>\n<li>Alignment of text block or text fragment: <code class=\"codespan\">align</code>, <code class=\"codespan\">verticalAlign</code>.</li>\n<li>Border, background (color or image) of text block or text fragment: <code class=\"codespan\">backgroundColor</code>, <code class=\"codespan\">borderColor</code>, <code class=\"codespan\">borderWidth</code>, <code class=\"codespan\">borderRadius</code>.</li>\n<li>Shadow of text block or text fragment: <code class=\"codespan\">shadowColor</code>, <code class=\"codespan\">shadowBlur</code>, <code class=\"codespan\">shadowOffsetX</code>, <code class=\"codespan\">shadowOffsetY</code>.</li>\n<li>Position and rotation of text block: <code class=\"codespan\">position</code>, <code class=\"codespan\">distance</code>, <code class=\"codespan\">rotate</code>.</li>\n</ul>\n<p>User can defined styles for text fragment in <code class=\"codespan\">rich</code> property. For example, <a href=\"option.html#series-bar.label.rich\" target=\"_blank\">series-bar.label.rich</a></p>\n<p>For example:</p>\n<pre><code class=\"lang-js\">label: {\n    // Styles defined in &#39;rich&#39; can be applied to some fragments\n    // of text by adding some markers to those fragment, like\n    // `{styleName|text content text content}`.\n    // `&#39;\\n&#39;` is the newline character.\n    formatter: [\n        &#39;{a|Style &quot;a&quot; is applied to this fragment}&#39;\n        &#39;{b|Style &quot;b&quot; is applied to this fragment}This fragment use default style{x|use style &quot;x&quot;}&#39;\n    ].join(&#39;\\n&#39;),\n\n    // Styles for the whole text block are defined here:\n    color: &#39;#333&#39;,\n    fontSize: 5,\n    fontFamily: &#39;Arial&#39;,\n    borderWidth: 3,\n    backgroundColor: &#39;#984455&#39;,\n    padding: [3, 10, 10, 5],\n    lineHeight: 20,\n\n    // Styles for text fragments are defined here:\n    rich: {\n        a: {\n            color: &#39;red&#39;,\n            lineHeight: 10\n        },\n        b: {\n            backgroundColor: {\n                image: &#39;xxx/xxx.jpg&#39;\n            },\n            height: 40\n        },\n        x: {\n            fontSize: 18,\n            fontFamily: &#39;Microsoft YaHei&#39;,\n            borderColor: &#39;#449933&#39;,\n            borderRadius: 4\n        },\n        ...\n    }\n}\n</code></pre>\n<blockquote>\n<p>Notice: <code class=\"codespan\">width</code> 和 <code class=\"codespan\">height</code> only work when <code class=\"codespan\">rich</code> specified.</p>\n</blockquote>\n<h2 id=\"basic-styles-of-text-text-block-and-text-fragment\">Basic Styles of Text, Text Block and Text Fragment</h2>\n<p>Basic font style can be set to text: <code class=\"codespan\">fontStyle</code>, <code class=\"codespan\">fontWeight</code>, <code class=\"codespan\">fontSize</code>, <code class=\"codespan\">fontFamily</code>.</p>\n<p>Fill color and stroke color can be set to text: <code class=\"codespan\">color</code>, <code class=\"codespan\">textBorderColor</code>, <code class=\"codespan\">textBorderWidth</code>.</p>\n<p>Border style and background style can be set to text block: <code class=\"codespan\">borderColor</code>, <code class=\"codespan\">borderWidth</code>, <code class=\"codespan\">backgroundColor</code>, <code class=\"codespan\">padding</code>.</p>\n<p>Border style and background style can be set to text fragment too: <code class=\"codespan\">borderColor</code>, <code class=\"codespan\">borderWidth</code>, <code class=\"codespan\">backgroundColor</code>, <code class=\"codespan\">padding</code>.</p>\n<p>For example:</p>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=doc-example/text-options&edit=1&reset=1\" width=\"700\" height=\"300\" ></iframe>\n\n\n\n<h2 id=\"label-position\">Label Position</h2>\n<p><code class=\"codespan\">label</code> option can be use in charts like <code class=\"codespan\">bar</code>, <code class=\"codespan\">line</code>, <code class=\"codespan\">scatter</code>, etc. The position of a label, can be specified by <a href=\"option.html#series-scatter.label.position\" target=\"_blank\">label.position</a>、<a href=\"option.html#series-scatter.label.distance\" target=\"_blank\">label.distance</a>.</p>\n<p>For example:</p>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=doc-example/label-position&edit=1&reset=1\" width=\"800\" height=\"400\" ></iframe>\n\n\n<blockquote>\n<p>Notice, there are different optional values of <code class=\"codespan\">position</code> by different chart types. And <code class=\"codespan\">distance</code> is not supported in every chart. More detailed info can be checked in <a href=\"option.html\" target=\"_blank\">option doc</a>.</p>\n</blockquote>\n<h2 id=\"label-rotation\">Label Rotation</h2>\n<p>Sometimes label is needed to be rotated. For example:</p>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=bar-label-rotation&edit=1&reset=1\" width=\"900\" height=\"500\" ></iframe>\n\n\n<p><a href=\"option.html#series-bar.label.align\" target=\"_blank\">align</a> and<a href=\"option.html#series-bar.label.verticalAlign\" target=\"_blank\">verticalAlign</a> can be used to adjust location of label in this scenario.</p>\n<p>Notice, <code class=\"codespan\">align</code> and <code class=\"codespan\">verticalAlign</code> are applied firstly, then rotate.</p>\n<h2 id=\"layout-and-alignment-of-text-fragment\">Layout and Alignment of Text fragment</h2>\n<p>To understand the layout rule, every text fragment can be imagined as a <code class=\"codespan\">inline-block</code> dom element in CSS.</p>\n<p><code class=\"codespan\">content box size</code> of a text fragment is determined by its font size by default. It can also be specified directly by <code class=\"codespan\">width</code> and <code class=\"codespan\">height</code>, although they are rarely set. <code class=\"codespan\">border box size</code> of a text fragment is calculated by adding the <code class=\"codespan\">border box size</code> and <code class=\"codespan\">padding</code>.</p>\n<p>Only <code class=\"codespan\">&#39;\\n&#39;</code> is the newline character, which breaks a line.</p>\n<p>Multiple text fragment exist in a single line. The height of a line is determined by the biggest <code class=\"codespan\">lineHeight</code> of text fragments. <code class=\"codespan\">lineHeight</code> of a text fragment can be specified in <code class=\"codespan\">rich</code>, or in the parent level of <code class=\"codespan\">rich</code>, otherwise using <code class=\"codespan\">box size</code> of the text fragment.</p>\n<p>Having <code class=\"codespan\">lineHeight</code> determined, the vertical position of text fragments can be determined by <code class=\"codespan\">verticalAlign</code> (there is a little different from the rule in CSS):</p>\n<ul>\n<li><code class=\"codespan\">&#39;bottom&#39;</code>: The bottom edge of the text fragment sticks to the bottom edge of the line.</li>\n<li><code class=\"codespan\">&#39;top&#39;</code>: The top edge of the text fragment sticks to the top edge of the line.</li>\n<li><code class=\"codespan\">&#39;middle&#39;</code>: In the middle of the line.</li>\n</ul>\n<p>The width of a text block can be specified by <code class=\"codespan\">width</code>, otherwise, by the longest line. Having the width determined, text fragment can be placed in each line, where the horizontal position of text fragments can be determined by its <code class=\"codespan\">align</code>.</p>\n<ul>\n<li>Firstly, place text fragments whose <code class=\"codespan\">align</code> is <code class=\"codespan\">&#39;left&#39;</code> from left to right continuously.</li>\n<li>Secondly, place text fragments whose <code class=\"codespan\">align</code> is <code class=\"codespan\">&#39;right&#39;</code> from right to left continuously.</li>\n<li>Finally, the text fragments remained will be sticked and placed in the center of the rest of space.</li>\n</ul>\n<p>The position of text in a text fragment:</p>\n<ul>\n<li>If <code class=\"codespan\">align</code> is <code class=\"codespan\">&#39;center&#39;</code>, text aligns at the center of the text fragment box.</li>\n<li>If <code class=\"codespan\">align</code> is <code class=\"codespan\">&#39;left&#39;</code>, text aligns at the left of the text fragment box.</li>\n<li>If <code class=\"codespan\">align</code> is <code class=\"codespan\">&#39;right&#39;</code>, text aligns at the right of the text fragment box.</li>\n</ul>\n<p>For example:</p>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=doc-example/text-fragment-align&edit=1&reset=1\" width=\"800\" height=\"220\" ></iframe>\n\n\n\n\n<h2 id=\"effects-icon-horizontal-rule-title-block-simple-table\">Effects: Icon, Horizontal Rule, Title Block, Simple Table</h2>\n<p>See example:</p>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=doc-example/title-block&edit=1&reset=1\" width=\"600\" height=\"400\" ></iframe>\n\n\n<p>Icon is implemented by using image in <code class=\"codespan\">backgroundColor</code>.</p>\n<pre><code class=\"lang-js\">rich: {\n    Sunny: {\n        backgroundColor: {\n            image: &#39;./data/asset/img/weather/sunny_128.png&#39;\n        },\n        // Can only height specified, but leave width auto obtained\n        // from the image, where the aspect ratio kept.\n        height: 30\n    }\n}\n</code></pre>\n<p>Horizontal rule (like HTML &lt;hr&gt; tag) can be implemented by border:</p>\n<pre><code class=\"lang-js\">rich: {\n    hr: {\n        borderColor: &#39;#777&#39;,\n        // width is set as &#39;100%&#39; to fullfill the text block.\n        // Notice, the percentage is based on the content box, without\n        // padding. Although it is a little different from CSS rule,\n        // it is convinent in most cases.\n        width: &#39;100%&#39;,\n        borderWidth: 0.5,\n        height: 0\n    }\n}\n</code></pre>\n<p>Title block can be implemented by <code class=\"codespan\">backgroundColor</code>:</p>\n<pre><code class=\"lang-js\">// Title is at left.\nformatter: &#39;{titleBg|Left Title}&#39;,\nrich: {\n    titleBg: {\n        backgroundColor: &#39;#000&#39;,\n        height: 30,\n        borderRadius: [5, 5, 0, 0],\n        padding: [0, 10, 0, 10],\n        width: &#39;100%&#39;,\n        color: &#39;#eee&#39;\n    }\n}\n\n// Title is in the center of the line.\n// This implementation is a little tricky, but is works\n// without more complicated layout mechanism involved.\nformatter: &#39;{tc|Center Title}{titleBg|}&#39;,\nrich: {\n    titleBg: {\n        align: &#39;right&#39;,\n        backgroundColor: &#39;#000&#39;,\n        height: 30,\n        borderRadius: [5, 5, 0, 0],\n        padding: [0, 10, 0, 10],\n        width: &#39;100%&#39;,\n        color: &#39;#eee&#39;\n    }\n}\n</code></pre>\n<p>Simple table can be implemented by specify the same width to text fragments that are in the same column of different lines. See the <a href=\"https://echarts.apache.org/examples/en/view.html?c=pie-rich-text&amp;edit=1&amp;reset=1\" target=\"_blank\">example</a> at the mentioned above.</p>\n"},"Server-side Rendering":{"type":["*"],"description":"<p>Apache ECharts<sup>TM</sup> can be rendered at server-side. For example, the thumbnails in the <a href=\"https://echarts.apache.org/examples/en/index.html\" target=\"_blank\">official examples page</a> are generated at a server.</p>\n<p>Commonly used headless tool is required, for example, <a href=\"https://github.com/GoogleChrome/puppeteer\" target=\"_blank\">puppeteer</a>, <a href=\"https://chromium.googlesource.com/chromium/src/+/lkgr/headless/README.md\" target=\"_blank\">headless chrome</a>, <a href=\"https://github.com/Automattic/node-canvas\" target=\"_blank\">node-canvas</a>, <a href=\"https://github.com/jsdom/jsdom\" target=\"_blank\">jsdom</a>, <a href=\"http://phantomjs.org/\" target=\"_blank\">PhantomJS</a>, etc.</p>\n<p>Some solutions contributed by the community are list as follows:</p>\n<ul>\n<li><a href=\"https://github.com/hellosean1025/node-echarts\" target=\"_blank\">https://github.com/hellosean1025/node-echarts</a></li>\n<li><a href=\"https://github.com/chfw/echarts-scrappeteer\" target=\"_blank\">https://github.com/chfw/echarts-scrappeteer</a></li>\n<li><a href=\"https://github.com/chfw/pyecharts-snapshot/blob/master/pyecharts_snapshot/phantomjs/snapshot.js\" target=\"_blank\">https://github.com/chfw/pyecharts-snapshot/blob/master/pyecharts_snapshot/phantomjs/snapshot.js</a></li>\n<li><a href=\"https://gist.github.com/pissang/4c32ee30e35c91336af72b129a1a4a73\" target=\"_blank\">https://gist.github.com/pissang/4c32ee30e35c91336af72b129a1a4a73</a></li>\n</ul>\n"},"Render by Canvas or SVG":{"type":["*"],"description":"<p>Most of browser-side charting libraries use SVG or Canvas as their underlying renderer. In the scope of Apache ECharts<sup>TM</sup>, they are usually alternative, without critical differences. But in some environment and scenarios, they show notable differences in performance or functionality.</p>\n<p>ECharts has been using Canvas as its renderer (use VML for IE8-) from the beginning. As of <a href=\"https://github.com/apache/echarts/releases\" target=\"_blank\">ECharts v3.8</a> we provide an SVG renderer (beta version) as another option. Either of them can be used by specifing parameter <a href=\"api.html#echarts.init\" target=\"_blank\">renderer</a> as <code class=\"codespan\">&#39;canvas&#39;</code> or <code class=\"codespan\">&#39;svg&#39;</code> when initailizing a chart instance.</p>\n<blockquote>\n<p>Both SVG and Canvas, which are very different rendering implementations, are supported in ECharts by leveraging the Canvas and SVG renderers offered by the <a href=\"https://github.com/ecomfe/zrender\" target=\"_blank\">zrender</a> library.</p>\n</blockquote>\n<h2 id=\"how-to-make-a-choice-\">How to make a choice?</h2>\n<p>Generally speaking, Canvas is suitable for cases where there is a large amount of graphical elements (usually due to a large amount of data points), like heatmap and lines or scatter plot with large data in geo or parallel coordinates. In addition, it supports some <a href=\"https://echarts.apache.org/examples/en/editor.html?c=lines-bmap-effect\" target=\"_blank\">special visual effect</a> not supported by SVG. However, in some other scenarios SVG has some critical advantages: it consumes less memory than Canvas (especially in mobile devices), and gives better performance in rendering. Moreover, it never blurs when zooming the viewport of the browser whereas Canvas may blur.</p>\n<p>How to make a choice? These factors, hardware and software environment, data amount and functional requirements, should be considered.</p>\n<ul>\n<li>When not constrained by hardware/software, and the data amount is not large, both should provide equally satisfactory results.</li>\n<li>When encountering performance issues, we can attempt to get better result by choose appropriate renderer.<ul>\n<li>If lots of ECharts instances have to be created, and it causes the browser crash (probably caused by that the large memory consumption) we can try the SVG renderer. Or, generally, when running on some old Android devices, or if we are using some kind of charts like <a href=\"https://ecomfe.github.io/echarts-liquidfill/example/\" target=\"_blank\">liquidfill</a>, the SVG renderer probably gives a better performance.</li>\n<li>If visualizing a large amount of data, or complicated human interactions with data is required, the Canvas renderer works better currently.</li>\n</ul>\n</li>\n</ul>\n<p>Therefore <a href=\"https://github.com/apache/echarts/issues/new\" target=\"_blank\">feedback</a> of experiences and usage scenarios are strongly welcomed, which will help improve the these renderers.</p>\n<h2 id=\"how-to-use-specify-a-renderer-\">How to use specify a renderer?</h2>\n<p>ECharts uses Canvas by default. If a user intends to use the SVG renderer, the module of the SVG renderer should be included in ECharts bundle.</p>\n<ul>\n<li>In the <a href=\"https://www.jsdelivr.com/package/npm/echarts\" target=\"_blank\">pre-build</a> of ECharts, the SVG renderer has been included in <a href=\"https://cdn.jsdelivr.net/npm/echarts/dist/echarts.common.min.js\" target=\"_blank\">common version</a> and <a href=\"https://cdn.jsdelivr.net/npm/echarts/dist/echarts.min.js\" target=\"_blank\">complete version</a>. But not in <a href=\"https://cdn.jsdelivr.net/npm/echarts/dist/echarts.simple.min.js\" target=\"_blank\">simple version</a>.</li>\n<li>When <a href=\"https://echarts.apache.org/en/builder.html\" target=\"_blank\">building ECharts online</a>, the checkbox &quot;SVG Renderer&quot; should be checked.</li>\n<li>When <a href=\"tutorial.html#Use%20ECharts%20with%20bundler%20and%20NPM\" target=\"_blank\">building ECharts offline</a>, the SVG renderer module should be imported:</li>\n</ul>\n<pre><code class=\"lang-js\">import &#39;zrender/lib/svg/svg&#39;;\n</code></pre>\n<p>Then we can specify renderer by <a href=\"api.html#echarts.init\" target=\"_blank\">parameter</a>:</p>\n<pre><code class=\"lang-js\">// Use the Canvas renderer (default).\nvar chart = echarts.init(containerDom, null, {renderer: &#39;canvas&#39;});\n// which is equal to:\nvar chart = echarts.init(containerDom, null, {renderer: &#39;canvas&#39;});\n\n// Use the SVG renderer.\nvar chart = echarts.init(containerDom, null, {renderer: &#39;svg&#39;});\n</code></pre>\n"},"SVG Base Map in Geo Coords and Map Series":{"type":["*"],"description":"<p>Since <code class=\"codespan\">v5.1.0</code>, ECharts support to use SVG as the base map in <a href=\"option.html#geo\" target=\"_blank\">geo coordinate system</a> and <a href=\"option.html#series-map\" target=\"_blank\">map series</a>, where previously only <a href=\"http://geojson.org/\" target=\"_blank\">GeoJSON</a> is supported.</p>\n<p>This feature enables ECharts to display SVG in either of the render modes (<code class=\"codespan\">canvas</code> render mode and <code class=\"codespan\">svg</code> render mode), and enables features like <a href=\"option.html#geo.roam\" target=\"_blank\">zoom</a>, <a href=\"option.html#geo.roam\" target=\"_blank\">pan</a>, <a href=\"option.html#geo.select\" target=\"_blank\">select</a>, <a href=\"option.html#geo.emphasis\" target=\"_blank\">emphasis</a>, <a href=\"option.html#geo.emphasis.focus\" target=\"_blank\">focus-blur</a>, <a href=\"option.html#geo.label\" target=\"_blank\">label</a>, <a href=\"option.html#series-map.labelLayout\" target=\"_blank\">labelLayout</a>, <a href=\"option.html#geo.tooltip\" target=\"_blank\">tooltip</a> on SVG with only simple some ECharts options. Series like <a href=\"option.html#series-scatter\" target=\"_blank\">scatter</a>, <a href=\"option.html#series-effectScatter\" target=\"_blank\">effectScatter</a>, <a href=\"option.html#series-lines\" target=\"_blank\">lines</a>, <a href=\"option.html#series-custom\" target=\"_blank\">custom</a> that are available on <a href=\"option.html#geo\" target=\"_blank\">geo coordinate system</a> can also be positioned and displayed based on SVG base map.</p>\n<p>There are several examples where SVG base map is used:</p>\n<p><a href=\"https://echarts.apache.org/examples/en/editor.html?c=geo-beef-cuts\" target=\"_blank\">Beef Cuts</a> |\n<a href=\"https://echarts.apache.org/examples/en/editor.html?c=geo-organ\" target=\"_blank\">Organ Visualization</a> |\n<a href=\"https://echarts.apache.org/examples/en/editor.html?c=geo-seatmap-flight\" target=\"_blank\">Flight Seatmap</a> |\n<a href=\"https://echarts.apache.org/examples/en/editor.html?c=geo-svg-map\" target=\"_blank\">SVG Map</a> |\n<a href=\"https://echarts.apache.org/examples/en/editor.html?c=geo-svg-scatter-simple\" target=\"_blank\">SVG Scatter</a> |\n<a href=\"https://echarts.apache.org/examples/en/editor.html?c=geo-svg-lines\" target=\"_blank\">SVG Lines</a> |\n<a href=\"https://echarts.apache.org/examples/en/editor.html?c=geo-svg-traffic\" target=\"_blank\">SVG Traffic</a></p>\n<h2 id=\"basic-usage\">Basic Usage</h2>\n<p>The usage of SVG base map is the same as the usage of <a href=\"http://geojson.org/\" target=\"_blank\">GeoJSON</a>.</p>\n<p>If used in <a href=\"option.html#geo\" target=\"_blank\">geo coordinate system</a>:</p>\n<pre><code class=\"lang-js\">$.get(&#39;map/organ.svg&#39;, function (svg) {\n    // Firstly we need to register SVG raw string or parsed SVG DOM\n    // to echarts with a name:\n    echarts.registerMap(&#39;organ_diagram&#39;, {svg: svg});\n\n    var chart = echarts.init(document.getElementById(&#39;main&#39;));\n    chart.setOption({\n        geo: {\n            // Reference it in echarts option.\n            map: &#39;organ_diagram&#39;,\n            ...\n        }\n    });\n});\n</code></pre>\n<p>If used in <a href=\"option.html#series-map\" target=\"_blank\">map series</a>:</p>\n<pre><code class=\"lang-js\">$.get(&#39;map/beef_cuts.svg&#39;, function (svg) {\n    // Firstly we need to register SVG raw string or parsed SVG DOM\n    // to echarts with a name:\n    echarts.registerMap(&#39;beef_cuts_diagram&#39;, {svg: svg});\n\n    var chart = echarts.init(document.getElementById(&#39;main&#39;));\n    chart.setOption({\n        series: {\n            type: &#39;map&#39;,\n            // Reference it in echarts option.\n            map: &#39;beef_cuts_diagram&#39;,\n            ...\n        }\n    });\n});\n</code></pre>\n<h2 id=\"zoom-and-pan\">Zoom and Pan</h2>\n<p>For <a href=\"option.html#geo\" target=\"_blank\">Geo coordinate system</a></p>\n<pre><code class=\"lang-js\">option = {\n    geo: {\n        // Enable zoom and pan.\n        roam: true,\n        ...\n    }\n};\n</code></pre>\n<p>For <a href=\"option.html#series-map\" target=\"_blank\">map series</a></p>\n<pre><code class=\"lang-js\">option = {\n    series: {\n        type: &#39;map&#39;,\n        // Enable zoom and pan.\n        roam: true,\n        ...\n    }\n};\n</code></pre>\n<p>See <a href=\"option.html#geo.roam\" target=\"_blank\">roam</a>.\nAlso see example <a href=\"https://echarts.apache.org/examples/en/editor.html?c=geo-svg-map\" target=\"_blank\">SVG Map</a>.</p>\n<h2 id=\"named-element\">Named Element</h2>\n<p>If intending to interact with some elements of SVG, we need to mark those elements in SVG firstly. That can be done simply by adding names to the target elements. The interaction related feature like <a href=\"option.html#geo.select\" target=\"_blank\">select</a>, <a href=\"option.html#geo.emphasis\" target=\"_blank\">emphasis</a>, <a href=\"option.html#geo.emphasis.focus\" target=\"_blank\">focus-blur</a>, <a href=\"option.html#geo.label\" target=\"_blank\">label</a>, <a href=\"option.html#series-map.labelLayout\" target=\"_blank\">labelLayout</a>, <a href=\"option.html#geo.tooltip\" target=\"_blank\">tooltip</a> depend on those named elements.</p>\n<p>For example, we add name attribute <code class=\"codespan\">name=&quot;named_rect&quot;</code> only to the left SVG <code class=\"codespan\">path</code>.</p>\n<pre><code class=\"lang-xml\">&lt;?xml version=&quot;1.0&quot; encoding=&quot;utf-8&quot;?&gt;\n&lt;svg xmlns=&quot;http://www.w3.org/2000/svg&quot; version=&quot;1.2&quot; fill-rule=&quot;evenodd&quot; xml:space=&quot;preserve&quot;&gt;\n    &lt;path name=&quot;named_rect&quot; d=&quot;M 0,0 L 0,100 100,100 100,0 Z&quot; fill=&quot;#765&quot; /&gt;\n    &lt;path d=&quot;M 150,0 L 150,100 250,100 250,0 Z&quot; fill=&quot;#567&quot; /&gt;\n&lt;/svg&gt;\n</code></pre>\n<p>Then hover on the left rect, it can be highlighted, whereas the right one can not.</p>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=doc-example/geo-svg-named-basic&edit=1&reset=1\" width=\"500\" height=\"200\" ></iframe>\n\n\n<p>Option for some certain named elements can be specified in <a href=\"option.html#geo.regions\" target=\"_blank\">geo.regions</a>, like:</p>\n<pre><code class=\"lang-js\">option = {\n    geo: {\n        map: &#39;some_svg&#39;,\n        regions: [{\n            name: &#39;element_name_1&#39;,\n            itemStyle: { ... }\n        }, {\n            name: &#39;element_name_2&#39;,\n            itemStyle: { ... }\n        }]\n    }\n};\n</code></pre>\n<p>Note:</p>\n<ul>\n<li>These SVG elements can be named and recognized by ECharts:\n<code class=\"codespan\">rect</code>, <code class=\"codespan\">circle</code>, <code class=\"codespan\">line</code>, <code class=\"codespan\">ellipse</code>, <code class=\"codespan\">polygon</code>, <code class=\"codespan\">polyline</code>, <code class=\"codespan\">path</code>, <code class=\"codespan\">text</code>, <code class=\"codespan\">tspan</code>, <code class=\"codespan\">g</code>.</li>\n<li>It is supported that multiple elements are named with the same name, will they will be highlighted/selected together.</li>\n</ul>\n<h2 id=\"style-customization\">Style Customization</h2>\n<p>Although the style (such as color, font, lineWidth, ...) of SVG Elements can be defined directly in SVG file, style of named elements can also be customized in ECharts option, which will be handy in some scenario.</p>\n<p>Styles can be specified in <a href=\"option.html#geo.itemStyle\" target=\"_blank\">geo.itemStyle</a> and <a href=\"option.html#series-map.itemStyle\" target=\"_blank\">series-map.itemStyle</a> (also includes <code class=\"codespan\">emphasis.itemStyle</code>, <code class=\"codespan\">select.itemStyle</code>, <code class=\"codespan\">blur.itemStyle</code>, <code class=\"codespan\">regions[i].itemStyle</code>, <code class=\"codespan\">regions[i].emphasis.itemStyle</code>, <code class=\"codespan\">regions[i].select.itemStyle</code>, <code class=\"codespan\">regions[i].blur.itemStyle</code>). Some default style of the named elements can also be removed here (e.g., set <code class=\"codespan\">emphasis.itemStyle.color: null</code> to prevent the fill color from changing when mouse hovering.)</p>\n<p>Moreover, named elements can also be styled by <a href=\"option.html#visualMap\" target=\"_blank\">visualMap component</a> if using <a href=\"option.html#series-map\" target=\"_blank\">series-map</a>. See <a href=\"https://echarts.apache.org/examples/en/editor.html?c=geo-beef-cuts\" target=\"_blank\">Beef Cuts</a>.</p>\n<p>Note:\nOnly these named elements can be styled in <code class=\"codespan\">itemStyle</code>:\n<code class=\"codespan\">rect</code>, <code class=\"codespan\">circle</code>, <code class=\"codespan\">line</code>, <code class=\"codespan\">ellipse</code>, <code class=\"codespan\">polygon</code>, <code class=\"codespan\">polyline</code>, <code class=\"codespan\">path</code>.</p>\n<h2 id=\"select\">Select</h2>\n<p>Named elements can adopt &quot;select&quot; feature by setting <a href=\"option.html#geo.selectedMode\" target=\"_blank\">geo.selectedMode</a> or <a href=\"option.html#series-map.selectedMode\" target=\"_blank\">series-map.selectedMode</a> as <code class=\"codespan\">&#39;single&#39;</code> or <code class=\"codespan\">&#39;multiple&#39;</code>. The style of element when selected can be specified in <a href=\"option.html#geo.select\" target=\"_blank\">geo.select</a> or <a href=\"option.html#series-map.select\" target=\"_blank\">series-map.select</a>.</p>\n<p>The selected names can be obtained by <a href=\"api.html#event.geoselectchanged\" target=\"_blank\">geoselectchanged</a> event, like:</p>\n<pre><code class=\"lang-js\">myChart.on(&#39;geoselectchanged&#39;, function (params) {\n    var selectedNames = params.allSelected[0].name;\n    console.log(&#39;selected&#39;, selectedNames);\n});\n</code></pre>\n<p>See <a href=\"https://echarts.apache.org/examples/en/editor.html?c=geo-seatmap-flight\" target=\"_blank\">Flight Seatmap</a> for more details.</p>\n<h2 id=\"emphasis-and-focus-blur\">Emphasis and Focus-Blur</h2>\n<p><code class=\"codespan\">emphasis</code> state (highlight when hovering) can be auto adopted to named elements.</p>\n<p>Especially, <a href=\"option.html#geo.emphasis.focus\" target=\"_blank\">geo.emphasis.focus</a> and be set as <code class=\"codespan\">&#39;self&#39;</code> to enable &quot;focus-blur&quot; feature, where all all of the other elements will be blurred when hovering on an named element.</p>\n<p>See <a href=\"https://echarts.apache.org/examples/en/editor.html?c=geo-organ\" target=\"_blank\">Organ Visualization</a> for more details.</p>\n<h2 id=\"tooltip\">Tooltip</h2>\n<p>Tooltip can be enabled or disabled on named elements.</p>\n<pre><code class=\"lang-js\">option = {\n    // Need to declare the root tooltip to\n    // enable tooltip feature on ECharts.\n    tooltip: {},\n    geo: {\n        map: &#39;some_svg&#39;,\n        tooltip: {\n            // Use `show` to enable/disable tooltip\n            // on geo coordinate system.\n            show: true\n        },\n        regions: [{\n            name: &#39;some_name1&#39;,\n            // Set named element specified tooltip option if needed.\n            tooltip: {\n                formatter: &#39;some special tooltip 1&#39;\n            }\n        }, {\n            name: &#39;some_name2&#39;,\n            tooltip: {\n                formatter: &#39;some special tooltip 2&#39;\n            }\n        }]\n    }\n};\n</code></pre>\n<p>If intending to disable the geo tooltip when hovering a on named elements, just:</p>\n<pre><code class=\"lang-js\">option = {\n    tooltip: {},\n    geo: {\n        map: &#39;some_svg&#39;,\n        tooltip: {\n            show: false\n        }\n    }\n};\n</code></pre>\n<p>See <a href=\"https://echarts.apache.org/examples/en/editor.html?c=geo-svg-map\" target=\"_blank\">SVG Map</a> for more details.</p>\n<h2 id=\"label\">Label</h2>\n<p>Although text label can be declared in SVG file directly via <code class=\"codespan\">&lt;text&gt;</code>/<code class=\"codespan\">&lt;tspan&gt;</code>, we can also use ECharts built-in label feature on named elements by specifying <a href=\"option.html#geo.label\" target=\"_blank\">geo.label</a> or <a href=\"option.html#series-map.label\" target=\"_blank\">series-map.label</a>.</p>\n<p>By default the label feature is enabled when hovering on a named element. If intending to disable it, just:</p>\n<pre><code class=\"lang-js\">option = {\n    geo: {\n        map: &#39;some_svg&#39;,\n        emphasis: {\n            label: {\n                show: false\n            }\n        }\n    }\n};\n</code></pre>\n<p>When multiple elements need to share one label text, we have two choices:</p>\n<ul>\n<li>Wrap those elements in a named <code class=\"codespan\">&lt;g&gt;</code> (e.g., <code class=\"codespan\">&lt;g name=&quot;name_a&quot;&gt;</code>), where a single label will be displayed and located based on the bounding rect of the <code class=\"codespan\">&lt;g&gt;</code>.</li>\n<li>Name those elements with the same name (e.g., <code class=\"codespan\">&lt;path name=&quot;name_b&quot;/&gt;&lt;path name=&quot;name_b&quot;/&gt;</code>), where multiple labels will be displayed and located based on each elements self.</li>\n</ul>\n<p>For example (hover to show the labels):</p>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=doc-example/geo-svg-label-basic&edit=1&reset=1\" width=\"500\" height=\"300\" ></iframe>\n\n\n<p>Note: Only these named elements can be labeled via <code class=\"codespan\">label</code> option:\n<code class=\"codespan\">rect</code>, <code class=\"codespan\">circle</code>, <code class=\"codespan\">line</code>, <code class=\"codespan\">ellipse</code>, <code class=\"codespan\">polygon</code>, <code class=\"codespan\">polyline</code>, <code class=\"codespan\">path</code>, <code class=\"codespan\">g</code>.</p>\n<p>Also see <a href=\"https://echarts.apache.org/examples/en/editor.html?c=geo-organ\" target=\"_blank\">Organ Visualization</a> for the usage of label.</p>\n<h2 id=\"events\">Events</h2>\n<p>Mouse events or touch events of named elements can be listened simply by:</p>\n<pre><code class=\"lang-js\">// &#39;name1&#39; is a name of a SVG element.\nmyChart.on(&#39;click&#39;, { geoIndex: 0, name: &#39;name1&#39; }, function (params) {\n    console.log(params);\n});\n</code></pre>\n<h2 id=\"layout-of-svg-base-map\">Layout of SVG Base Map</h2>\n<p>By default ECharts will position the SVG base map in the center of the canvas. If need some adjust, we usually only adjust <a href=\"option.html#geo.layoutCenter\" target=\"_blank\">layoutCenter</a>/<a href=\"option.html#geo.layoutSize\" target=\"_blank\">layoutSize</a>, and occasionally <code class=\"codespan\">&lt;svg viewBox=&quot;...&quot;&gt;</code>/<a href=\"option.html#geo.boundingCoords\" target=\"_blank\">geo.boundingCoords</a> (difference: clip or not). In most cases they are enough.</p>\n<p>If need some advanced precise control of the position and zoom, several concepts below can be noticed.</p>\n<p>The layout rule and options of <a href=\"option.html#geo\" target=\"_blank\">geo coordinate system</a> and <a href=\"option.html#series-map\" target=\"_blank\">map series</a> are the same. So we only demonstrate <a href=\"option.html#geo\" target=\"_blank\">geo coordinate system</a> below.</p>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=doc-example/geo-svg-layout-basic&edit=1&reset=1\" width=\"700\" height=\"550\" ></iframe>\n\n\n<p>The demo above shows six <a href=\"option.html#geo\" target=\"_blank\">geo coordinate system</a> with three SVG files in a single ECharts canvas. Each two <a href=\"option.html#geo\" target=\"_blank\">geo</a> that are in the same column use the same SVG file.</p>\n<p>Firstly, what shapes looks like is determined by SVG file itself. That is, in the demo above, determined by the <code class=\"codespan\">&lt;circle&gt;</code> and <code class=\"codespan\">viewBox</code> attribute (<code class=\"codespan\">viewBox</code> cut (clips) the circle). We can noticed that the final shape outlines in each column are the same (despite the difference in position, size and scratch), since they use the same SVG file.</p>\n<p>Secondly, users can use either of the two option groups below to determine the location and the size of the <code class=\"codespan\">geo view port</code> of <a href=\"option.html#geo\" target=\"_blank\">geo coordinate system</a> according to the entire chart canvas (all of these options are measured in echarts canvas pixel, or percentage value):</p>\n<ul>\n<li><a href=\"option.html#geo.layoutCenter\" target=\"_blank\">layoutCenter</a>, <a href=\"option.html#geo.layoutSize\" target=\"_blank\">layoutSize</a> (recommended).</li>\n<li><a href=\"option.html#geo.top\" target=\"_blank\">top</a>, <a href=\"option.html#geo.right\" target=\"_blank\">right</a>, <a href=\"option.html#geo.bottom\" target=\"_blank\">bottom</a>, <a href=\"option.html#geo.left\" target=\"_blank\">left</a> (which is used in the demo above).</li>\n</ul>\n<p>In the demo above, the six geo <code class=\"codespan\">geo view ports</code> are displayed as six black squares.</p>\n<p>Thirdly, a <code class=\"codespan\">bounding rect</code> of the SVG is determined, which is determined by methods below (all of them are measured in SVG local unit):</p>\n<ol>\n<li>If <a href=\"option.html#geo.boundingCoords\" target=\"_blank\">geo.boundingCoords</a> is specified, use it as <code class=\"codespan\">bounding rect</code>.</li>\n<li>Else if <code class=\"codespan\">&lt;svg width=&quot;...&quot; height=&quot;...&quot;&gt;</code> is specified, use <code class=\"codespan\">[0, 0, width, height]</code> as <code class=\"codespan\">bounding rect</code>. (If only <code class=\"codespan\">width</code> or only <code class=\"codespan\">height</code> is specified, only use <code class=\"codespan\">[0, width]</code> or <code class=\"codespan\">[0, height]</code>).</li>\n<li>Else if <code class=\"codespan\">svg viewBox=&quot;...&quot;&gt;</code> is specified, use <code class=\"codespan\">viewBox</code> as <code class=\"codespan\">bounding rect</code>.</li>\n<li>Else use the union bounding rect of all of the SVG elements as the <code class=\"codespan\">bounding rect</code>.</li>\n<li>If <a href=\"option.html#geo.center\" target=\"_blank\">geo.center</a> or <a href=\"option.html#geo.zoom\" target=\"_blank\">geo.zoom</a> is specified, transform the <code class=\"codespan\">bounding rect</code> determined by <code class=\"codespan\">1~4</code> above.</li>\n</ol>\n<p>Having <code class=\"codespan\">bounding rect</code> determined, it will be placed into its corresponding <code class=\"codespan\">geo view port</code>:</p>\n<ul>\n<li>If <a href=\"option.html#geo.layoutCenter\" target=\"_blank\">layoutCenter</a>, <a href=\"option.html#geo.layoutSize\" target=\"_blank\">layoutSize</a> is used, the <code class=\"codespan\">bounding rect</code> will be placed at the center and as big as possible into the <code class=\"codespan\">geo view port</code> (keep aspect ratio).</li>\n<li>If <a href=\"option.html#geo.top\" target=\"_blank\">top</a>, <a href=\"option.html#geo.right\" target=\"_blank\">right</a>, <a href=\"option.html#geo.bottom\" target=\"_blank\">bottom</a>, <a href=\"option.html#geo.left\" target=\"_blank\">left</a> is used, the view rect will be stretched to fill the <code class=\"codespan\">geo view port</code> entirely.</li>\n</ul>\n<h2 id=\"place-series-on-svg-base-map\">Place Series on SVG Base Map</h2>\n<p>Series like <a href=\"option.html#series-scatter\" target=\"_blank\">scatter</a>, <a href=\"option.html#series-effectScatter\" target=\"_blank\">effectScatter</a>, <a href=\"option.html#series-lines\" target=\"_blank\">lines</a>, <a href=\"option.html#series-custom\" target=\"_blank\">custom</a> that are available on <a href=\"option.html#geo\" target=\"_blank\">geo coordinate system</a> can also be positioned and displayed on SVG base map.</p>\n<p>Note that in this kind of usage the unit of series data value is the SVG file local coords. For example:</p>\n<pre><code class=\"lang-js\">option = {\n    geo: {\n        map: &#39;some_svg&#39;\n    },\n    series: {\n        type: &#39;effectScatter&#39;,\n        coordinateSystem: &#39;geo&#39;,\n        geoIndex: 0,\n        data: [\n            // SVG local coords.\n            [488.2358421078053, 459.70913833075736],\n            [770.3415644319939, 757.9672194986475],\n            [1180.0329284196291, 743.6141808346214],\n        ]\n    }\n};\n</code></pre>\n<p>By the way, there is a simple approach to get SVG local coord:</p>\n<pre><code class=\"lang-js\">myChart.setOption({\n    geo: {\n        map: &#39;some_svg&#39;\n    }\n});\nmyChart.getZr().on(&#39;click&#39;, function (params) {\n    var pixelPoint = [params.offsetX, params.offsetY];\n    var dataPoint = myChart.convertFromPixel({ geoIndex: 0 }, pixelPoint);\n    // When click, the data in SVG local coords will be printed,\n    // which can be used in `series.data`.\n    console.log(dataPoint);\n});\n</code></pre>\n<p>See also <a href=\"https://echarts.apache.org/examples/en/editor.html?c=geo-svg-scatter-simple\" target=\"_blank\">SVG Scatter</a>, <a href=\"https://echarts.apache.org/examples/en/editor.html?c=geo-svg-lines\" target=\"_blank\">SVG Lines</a>, <a href=\"https://echarts.apache.org/examples/en/editor.html?c=geo-traffic\" target=\"_blank\">SVG Traffic</a>.</p>\n<h2 id=\"unsupported-svg-features\">Unsupported SVG features</h2>\n<p>Unfortunately it is difficult to implement a complete SVG parser. While the common SVG features are supported, at least these features listed below are not supported yet:</p>\n<ul>\n<li>Flip and skew (will be supported <code class=\"codespan\">v5.1.2</code>):<ul>\n<li>Not support <code class=\"codespan\">transform: skew(...)</code> (including <code class=\"codespan\">transform: matrix(...)</code> that includes skew).</li>\n<li>Not support <code class=\"codespan\">transform: scale(x, y)</code> that <code class=\"codespan\">x</code>, <code class=\"codespan\">y</code> has different sign while has <code class=\"codespan\">rotate</code> (e.g., <code class=\"codespan\">scale: (1, -1), rotate(90)</code>).</li>\n</ul>\n</li>\n<li>Standalone <code class=\"codespan\">&lt;style&gt;</code> tag is not supported.<ul>\n<li>But inline style is supported (e.g., <code class=\"codespan\">&lt;path style=&quot;color:red&quot; /&gt;</code>).</li>\n</ul>\n</li>\n<li>Unit:<ul>\n<li>Only <code class=\"codespan\">px</code> is supported. Other unit like <code class=\"codespan\">width=&quot;231.65mm&quot;</code> is not supported.</li>\n<li>Percentage value like <code class=\"codespan\">&lt;svg width=&quot;30%&quot; height=&quot;40%&quot;&gt;</code> is not supported.</li>\n</ul>\n</li>\n<li><code class=\"codespan\">&lt;defs&gt;</code> tag:<ul>\n<li>Only <code class=\"codespan\">&lt;linearGradient&gt;</code>, <code class=\"codespan\">&lt;radialGradient&gt;</code> are supported.</li>\n<li>other elements (e.g., <code class=\"codespan\">&lt;pattern&gt;</code>, <code class=\"codespan\">&lt;path&gt;</code>, ...) defined in <code class=\"codespan\">&lt;defs&gt;</code> are not supported yet.</li>\n</ul>\n</li>\n<li><code class=\"codespan\">&lt;linearGradient&gt;</code>, <code class=\"codespan\">&lt;radialGradient&gt;</code>:<ul>\n<li><code class=\"codespan\">fx</code>, <code class=\"codespan\">fy</code> is not supported.</li>\n<li><code class=\"codespan\">gradientTransform</code> attribute is not supported.</li>\n</ul>\n</li>\n<li><code class=\"codespan\">fill:url(...)</code>, <code class=\"codespan\">stroke:utl(...)</code>:<ul>\n<li>Only <code class=\"codespan\">url(#someId)</code> is supported.</li>\n<li>Other URL patterns are not supported. e.g.,<ul>\n<li><code class=\"codespan\">url(https://example.com/images/myImg.jpg)</code>;</li>\n<li><code class=\"codespan\">url(data:image/png;base64,iRxVB0…)</code>;</li>\n<li><code class=\"codespan\">url(myFont.woff)</code>;</li>\n</ul>\n</li>\n</ul>\n</li>\n<li><code class=\"codespan\">&lt;switch&gt;</code> tag:<ul>\n<li>All the content inside <code class=\"codespan\">&lt;switch&gt;</code> tag will be displayed. The &quot;switch&quot; feature is not supported.</li>\n</ul>\n</li>\n<li><code class=\"codespan\">&lt;text&gt;</code>:<ul>\n<li><code class=\"codespan\">textPath</code> is not supported.</li>\n<li><a href=\"https://www.w3.org/TR/SVG/text.html#TermAddressableCharacter\" target=\"_blank\">Addressable character</a> is not supported. That is,<pre><code class=\"lang-xml\">&lt;!-- Not supported: --&gt;\n&lt;tspan x=&quot;0 4.94 9.89&quot;&gt;abc&lt;/tspan&gt;\n&lt;!-- Supported: --&gt;\n&lt;tspan x=&quot;0&quot;&gt;a&lt;/tspan&gt;\n&lt;tspan x=&quot;4.94&quot;&gt;b&lt;/tspan&gt;\n&lt;tspan x=&quot;9.89&quot;&gt;c&lt;/tspan&gt;\n</code></pre>\n</li>\n</ul>\n</li>\n</ul>\n"},"Supporting ARIA in Charts":{"type":["*"],"description":"<p>The W3C has developed the <a href=\"https://www.w3.org/WAI/intro/aria\" target=\"_blank\">WAI-ARIA</a>, the Accessible Rich Internet Applications Suite, which is dedicated to making web content and web applications accessible. Apache ECharts<sup>TM</sup> 4 complies with this specification by supporting the automatic generation of intelligent descriptions based on chart configuration items, allowing blind people to understand the chart content with the help of a reading device, making the chart accessible to a wider audience.</p>\n<p>By default, ARIA is disabled. To enable it, you should set <a href=\"#aria.enabled\">aria.enabled</a> to be <code class=\"codespan\">true</code>. After enabling, it will generate descriptions based on charts, series, data, and so on. Users may change the generated description.</p>\n<p><strong>For example:</strong></p>\n<p>For config:</p>\n<pre><code class=\"lang-js\">option = {\n    aria: {\n        show: true\n    },\n    title: {\n        text: &#39;Source of user access to a site&#39;,\n        x: &#39;center&#39;\n    },\n    series: [\n        {\n             Name: &#39;access source&#39;,\n            type: &#39;pie&#39;,\n            data: [\n                { value: 335, name: &#39;direct access&#39; },\n                { value: 310, name: &#39;mail marketing&#39; },\n                { value: 234, name: &#39;union ad&#39; },\n                { value: 135, name: &#39;video ad&#39; },\n                { value: 1548, name: &#39;search engine&#39; }\n            ]\n        }\n    ]\n};\n</code></pre>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=doc-example/aria-pie&edit=1&reset=1\" width=\"700\" height=\"300\" ></iframe>\n\n\n<p>There should be an <code class=\"codespan\">aria-label</code> attribute on the chart DOM, which can help the disabled understand the content of charts with the help of certain devices. The value of the label is:</p>\n<pre><code>This is a chart of &quot;Source of user access to a site.&quot; The chart type is a pie chart that indicates the source of the visit. The data is - direct access data is 335, mail marketing data is 310, union ad data is 234, video ad data is 135, search engine data is 1548.\n</code></pre><p>The default language is in defined by the language package (Chinese by default), but you can configure it with templates.</p>\n<p>In addition, Apache ECharts 5 now supports applique textures as a secondary expression of color to further differentiate data. If <code class=\"codespan\">aria.enabled</code> is set to <code class=\"codespan\">true</code>, <code class=\"codespan\">aria.decal.show</code> is set to <code class=\"codespan\">true</code> to adopt the default applique style.</p>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=doc-example/aria-decal-simple&edit=1&reset=1\" width=\"700\" height=\"300\" ></iframe>\n\n\n\n<p>Next, let&#39;s describe more specifically how these two accessible designs can be configured.</p>\n<h2 id=\"chart-labels\">Chart Labels</h2>\n<h3 id=\"apply-overall-modification-description\">Apply Overall Modification Description</h3>\n<p>For some charts, the default generated descriptions of the data points are not sufficient to represent the overall information. For example, in the scatter plot below, the default description can include the coordinates of the data points, but knowing the coordinates of hundreds or thousands of points does not help us to effectively understand the information presented in the chart.</p>\n<p><img width=\"600\" height=\"auto\" src=\"documents/asset/img/aria-example.png\"></p>\n<p>At this point, the user can specify the overall description of the chart via the <a href=\"option.html#aria.label.description\" target=\"_blank\">aria.label.description</a> configuration item.</p>\n<h3 id=\"customizing-the-template-description\">Customizing the Template Description</h3>\n<p>In addition to modifying descriptions holistically, we also provide templates for generating descriptions that can be easily modified at a fine-grained level.</p>\n<p>The basic flow for generating descriptions is that if <a href=\"option.html#aria.label.show\" target=\"_blank\">aria.label.description</a> is set to <code class=\"codespan\">true</code>, then the accessibility description is generated, otherwise it is not. If <a href=\"option.html#aria.label.description\" target=\"_blank\">aria.label.description</a> is defined, it is used as the full description of the chart, otherwise the description is generated according to the template stitching. We provide a default algorithm for generating descriptions, and only if the generated descriptions are not quite right, we need to modify these templates, or even override them completely with <code class=\"codespan\">aria.description</code>.</p>\n<p>When using the template, whether <a href=\"#title.text\">title.text</a> is used along with <a href=\"option.html#aria.label.general.withTitle\" target=\"_blank\">aria.label.general.withTitle</a> while <a href=\"option.html#aria.label.general.withoutTitle\" target=\"_blank\">aria.label.general.withoutTitle</a> is used if there is no title text. <code class=\"codespan\">aria.general.withTitle</code> supports a template <code class=\"codespan\">&#39;{title}&#39;</code>, which will be replaced with chart title. This means, if <code class=\"codespan\">aria.general.withTitle</code> is set to be <code class=\"codespan\">&#39;The chart title is {title}.&#39;</code> and the chart title is <code class=\"codespan\">Price Distribution</code>, it will be interpreted into <code class=\"codespan\">&#39;The chart title is Price Distribution.&#39;</code></p>\n<p>After generating the title, the description of the series (<a href=\"option.html#aria.label.series\" target=\"_blank\">aria.label.series</a>) and the description of the data for each series (<a href=\"option.html#aria.label.data\" target=\"_blank\">aria.label.data</a>) are generated in turn. The following is an example of a template. Likewise, each template may include template variables to replace actual values.</p>\n<h2 id=\"decal-pattern\">Decal Pattern</h2>\n<p>The way to use the default applique pattern was described above. If you need to customize the decal pattern, you can use <a href=\"option.html#aria.decal.decals\" target=\"_blank\">aria.decal.decals</a> to configure a flexible decal pattern.</p>\n<iframe data-src=\"https://echarts.apache.org/examples/en/view.html?c=doc-example/aria-decal&edit=1&reset=1\" width=\"700\" height=\"300\" ></iframe>\n\n\n<p>Please refer to <a href=\"option.html#aria\" target=\"_blank\">ARIA option</a> for more detail.</p>\n"}}}}