Enhance the responsive documentation

Make sure to explain responsiveness limitations with CANVAS elements and how to correctly setup a responsive chart using a dedicated and relatively positioned div wrapper.

diff --git a/docs/general/responsive.md b/docs/general/responsive.md
index 894dccee0bc99d4dd267871e6c47e3ae5aad2fd3..3d7bb027e19b0e3b0e18d70fe717cf2effc3744f 100644 (file)
--- a/docs/general/responsive.md
+++ b/docs/general/responsive.md
@@ -1,10 +1,35 @@
 # Responsive Charts
 
-Chart.js provides a few options for controlling resizing behaviour of charts.
+When it comes to change the chart size based on the window size, a major limitation is that the canvas *render* size (`canvas.width` and `.height`) can **not** be expressed with relative values, contrary to the *display* size (`canvas.style.width` and `.height`). Furthermore, these sizes are independent from each other and thus the canvas *render* size does not adjust automatically based on the *display* size, making the rendering inaccurate.
+
+The following examples **do not work**:
+
+- `<canvas height="40vh" width="80vw">`: **invalid** values, the canvas doesn't resize ([example](https://codepen.io/chartjs/pen/oWLZaR))
+- `<canvas style="height:40vh; width:80vw">`: **invalid** behavior, the canvas is resized but becomes blurry ([example](https://codepen.io/chartjs/pen/WjxpmO))
+
+Chart.js provides a [few options](#configuration-options) to enable responsiveness and control the resize behavior of charts by detecting when the canvas *display* size changes and update the *render* size accordingly.
+
+## Configuration Options
 
 | Name | Type | Default | Description
 | ---- | ---- | ------- | -----------
-| `responsive` | `Boolean` | `true` | Resizes the chart canvas when its container does.
+| `responsive` | `Boolean` | `true` | Resizes the chart canvas when its container does ([important note...](#important-note)).
 | `responsiveAnimationDuration` | `Number` | `0` | Duration in milliseconds it takes to animate to new size after a resize event.
 | `maintainAspectRatio` | `Boolean` | `true` | Maintain the original canvas aspect ratio `(width / height)` when resizing.
-| `onResize` | `Function` | `null` | Called when a resize occurs. Gets passed two arguments: the chart instance and the new size.
\ No newline at end of file
+| `onResize` | `Function` | `null` | Called when a resize occurs. Gets passed two arguments: the chart instance and the new size.
+
+## Important Note
+
+Detecting when the canvas size changes can not be done directly from the `CANVAS` element. Chart.js uses its parent container to update the canvas *render* and *display* sizes. However, this method requires the container to be **relatively positioned**. It's also strongly recommended to **dedicate this container to the chart canvas only**. Responsiveness can then be achieved by setting relative values for the container size ([example](https://codepen.io/chartjs/pen/YVWZbz)):
+
+```html
+<div class="chart-container" style="position: relative; height:40vh; width:80vw">
+    <canvas id="chart"></canvas>
+</div>
+```
+
+The chart can also be programmatically resized by modifying the container size:
+
+```javascript
+chart.canvas.parentNode.style.height = '128px';
+```