Create a widget sizing policy

Define the policy by which HTML widgets will be sized in various containers (e.g. Browser, RStudio Viewer, R Markdown, Shiny). Note that typically widgets can accept the default sizing policy (or override only one or two aspects of it) and get satisfactory sizing behavior via the automatic sizing logic built into the htmlwidgets framework (see the notes below for the most typical exceptions to this).

sizingPolicy(
  defaultWidth = NULL,
  defaultHeight = NULL,
  padding = NULL,
  viewer.defaultWidth = NULL,
  viewer.defaultHeight = NULL,
  viewer.padding = NULL,
  viewer.fill = TRUE,
  viewer.suppress = FALSE,
  viewer.paneHeight = NULL,
  browser.defaultWidth = NULL,
  browser.defaultHeight = NULL,
  browser.padding = NULL,
  browser.fill = FALSE,
  browser.external = FALSE,
  knitr.defaultWidth = NULL,
  knitr.defaultHeight = NULL,
  knitr.figure = TRUE
)

Arguments

defaultWidth	The default width used to display the widget. This parameter specifies the default width for viewing in all contexts (browser, viewer, and knitr) unless it is specifically overridden with e.g. browser.defaultWidth.
defaultHeight	The default height used to display the widget. This parameter specifies the default height for viewing in all contexts (browser, viewer, and knitr) unless it is specifically overridden with e.g. browser.defaultHeight.
padding	Padding around the widget (in pixels). This parameter specifies the padding for viewing in all contexts (browser and viewer) unless it is specifically overriden by e.g. browser.padding.
viewer.defaultWidth	The default width used to display the widget within the RStudio Viewer.
viewer.defaultHeight	The default height used to display the widget within the RStudio Viewer.
viewer.padding	Padding around the widget when displayed in the RStudio Viewer (defaults to 15 pixels).
viewer.fill	When displayed in the RStudio Viewer, automatically size the widget to the viewer dimensions (note that viewer.padding is still applied). Default to TRUE.
viewer.suppress	Never display the widget within the RStudio Viewer (useful for widgets that require a large amount of space for rendering). Defaults to FALSE.
viewer.paneHeight	Request that the RStudio Viewer be forced to a specific height when displaying this widget.
browser.defaultWidth	The default width used to display the widget within a standalone web browser.
browser.defaultHeight	The default height used to display the widget within a standalone web browser.
browser.padding	Padding around the widget when displayed in a standalone browser (defaults to 40 pixels).
browser.fill	When displayed in a standalone web browser, automatically size the widget to the browser dimensions (note that browser.padding is still applied). Defaults to FALSE.
browser.external	When displaying in a browser, always use an external browser (via browseURL()). Defaults to FALSE, which will result in the use of an internal browser within RStudio v1.1 and higher.
knitr.defaultWidth	The default width used to display the widget within documents generated by knitr (e.g. R Markdown).
knitr.defaultHeight	The default height used to display the widget within documents generated by knitr (e.g. R Markdown).
knitr.figure	Apply the default knitr fig.width and fig.height to the widget when it's rendered within R Markdown documents. Defaults to TRUE.

Value

A widget sizing policy

Details

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.

You might need to change the default behavior if your widget is extremely large. In this case you might specify viewer.suppress = TRUE and knitr.figure = FALSE as well provide for a larger default width and height for knitr.

You also might need to change the default behavior if you widget already incorporates padding. In this case you might specify viewer.padding = 0.

For additional details on widget sizing:

vignette("develop_sizing", package = "htmlwidgets")