HTML Widget Sizing

Overview

In the spirit of HTML widgets working just like plots in R, it’s important that HTML widgets intelligently size themselves to their container, whether it be the RStudio Viewer, a figure in knitr, or a UI panel within a Shiny application. The htmlwidgets framework provides a rich mechanism for specifying the sizing behavior of widgets.

This sizing mechanism is designed to address the following constraints that affect the natural size of a widget:

• The kind of widget it is. Some widgets may only be designed to look good at small, fixed sizes (like sparklines) while other widgets may want every pixel that can be spared (like network graphs).

• The context into which the widget is rendered. While a given widget might look great at 960px by 480px in an R Markdown document, the same widget would look silly at that size in the RStudio Viewer pane, which is typically much smaller.

Widget sizing is handled in two steps:

1. First, a sizing policy is specified for the widget. This is done via the sizingPolicy argument to the createWidget function. Most widgets can accept the default sizing policy (or override only one or two aspects of it) and get satisfactory sizing behavior (see details below).

2. The sizing policy is used by the framework to compute the correct width and height for a widget given where it is being rendered. This size information is then passed to the initialize and resize methods of the widgets JavaScript binding. It’s up to the widget to then forward this size information to the underlying JavaScript library.

Specifying a sizing policy

The default HTML widget sizing policy treats the widget with the same sizing semantics as an R plot. When printed at the R console the widget is displayed within the RStudio Viewer and sized to fill the Viewer pane (modulo any padding). When rendered inside an R Markdown document the widget is sized based on the default size of figures in the document.

Note that for most widgets the default sizing behavior is fine and you won’t need to create a custom sizing policy. If you need a slightly different behavior than the default you can also selectively override the default behavior by calling the sizingPolicy function and passing the result to createWidget. For example:

htmlwidgets::createWidget(
  "sigma", 
  x, 
  width = width, 
  height = height,
  sizingPolicy = htmlwidgets::sizingPolicy(
    viewer.padding = 0,
    viewer.paneHeight = 500,
    browser.fill = TRUE
  )
)

sizingPolicy(padding = 0, browser.fill = TRUE)

sizingPolicy(viewer.suppress = TRUE,
             knitr.figure = FALSE,
             browser.fill = TRUE,
             browser.padding = 75,
             knitr.defaultWidth = 800,
             knitr.defaultHeight = 500)

JavaScript resize method

Specifying a sizing policy allows htmlwidgets to calculate the width and height of your widget based on where it’s being displayed. However, you still need to forward this sizing information on to the underlying JavaScript library you are creating a widget for.

Every JavaScript library handles dynamic sizing a bit differently. Some do it automatically, some have a resize() call to force a layout, and some require that size be set only along with data and other options. Whatever the case, the htmlwidgets framework will pass the computed sizes to both your factory function and resize function. Here’s an empty JavaScript binding that illustrates:

HTMLWidgets.widget({

  name: "demo",
  
  type: "output",
  
  factory: function(el, width, height) {
  
    return {
      renderValue: function(x) {
      
      },
      
      resize: function(width, height) {
        
      }
    };
  }
});

What you do with the passed width and height is up to you and depends on the re-sizing semantics of the underlying JavaScript library you are creating a widget for. A couple of illustrative examples are included in the next section.

resize: function(width, height) {
  if (dygraph)
    dygraph.resize();
}

factory: function(el, width, height) {

  // instance data
  var el = el;
  var force = d3.layout.force();

  d3.select(el).append("svg")
    .attr("width", width)
    .attr("height", height);
      
  return {
    renderValue: function(x) {
      // implementation excluded
    },
      
    resize: function(width, height) {
         
      d3.select(el).select("svg")
        .attr("width", width)
        .attr("height", height);

      force.size([width, height]).resume();
    }
  };
}