diff --git a/docs/developers/updates.md b/docs/developers/updates.md
index 06550ce0c..b65757f85 100644
--- a/docs/developers/updates.md
+++ b/docs/developers/updates.md
@@ -1,6 +1,6 @@
# Updating Charts
-It's pretty common to want to update charts after they've been created. When the chart data is changed, Chart.js will animate to the new data values.
+It's pretty common to want to update charts after they've been created. When the chart data or options are changed, Chart.js will animate to the new data values and options.
## Adding or Removing Data
@@ -14,9 +14,7 @@ function addData(chart, label, data) {
});
chart.update();
}
-```
-```javascript
function removeData(chart) {
chart.data.labels.pop();
chart.data.datasets.forEach((dataset) => {
@@ -26,6 +24,78 @@ function removeData(chart) {
}
```
+## Updating Options
+
+To update the options, mutating the options property in place or passing in a new options object are supported.
+
+- If the options are mutated in place, other option properties would be preserved, including those calculated by Chart.js.
+- If created as a new object, it would be like creating a new chart with the options - old options would be discarded.
+
+```javascript
+function updateConfigByMutating(chart) {
+ chart.options.title.text = 'new title';
+ chart.update();
+}
+
+function updateConfigAsNewObject(chart) {
+ chart.options = {
+ responsive: true,
+ title:{
+ display:true,
+ text: 'Chart.js'
+ },
+ scales: {
+ xAxes: [{
+ display: true
+ }],
+ yAxes: [{
+ display: true
+ }]
+ }
+ }
+ chart.update();
+}
+```
+
+Scales can be updated separately without changing other options.
+To update the scales, pass in an object containing all the customization including those unchanged ones.
+
+Variables referencing any one from `chart.scales` would be lost after updating scales with a new `id` or the changed `type`.
+
+```javascript
+function updateScales(chart) {
+ var xScale = chart.scales['x-axis-0'];
+ var yScale = chart.scales['y-axis-0'];
+ chart.options.scales = {
+ xAxes: [{
+ id: 'newId',
+ display: true
+ }],
+ yAxes: [{
+ display: true,
+ type: 'logarithmic'
+ }]
+ }
+ chart.update();
+ // need to update the reference
+ xScale = chart.scales['newId'];
+ yScale = chart.scales['y-axis-0'];
+}
+```
+
+You can also update a specific scale either by specifying its index or id.
+
+```javascript
+function updateScale(chart) {
+ chart.options.scales.yAxes[0] = {
+ type: 'logarithmic'
+ }
+ chart.update();
+}
+```
+
+Code sample for updating options can be found in [toggle-scale-type.html](../../samples/scales/toggle-scale-type.html).
+
## Preventing Animations
Sometimes when a chart updates, you may not want an animation. To achieve this you can call `update` with a duration of `0`. This will render the chart synchronously and without an animation.
\ No newline at end of file
diff --git a/samples/samples.js b/samples/samples.js
index 2d11e9d48..b818827c6 100644
--- a/samples/samples.js
+++ b/samples/samples.js
@@ -136,6 +136,9 @@
}, {
title: 'Non numeric Y Axis',
path: 'scales/non-numeric-y.html'
+ }, {
+ title: 'Toggle Scale Type',
+ path: 'scales/toggle-scale-type.html'
}]
}, {
title: 'Legend',
diff --git a/samples/scales/toggle-scale-type.html b/samples/scales/toggle-scale-type.html
new file mode 100644
index 000000000..b46687e82
--- /dev/null
+++ b/samples/scales/toggle-scale-type.html
@@ -0,0 +1,99 @@
+
+
+
+