{
"cells": [
{
"cell_type": "markdown",
"id": "3f12d7c2",
"metadata": {},
"source": [
"# Margins\n",
"\n",
" \n",
"The margins around the plot and text elements are controlled by the `plotMargin` parameter in `theme()` and the `margin` parameter in `elementText()` respectively.\n",
"\n",
"Now the parameters `plotMargin` and `margin` accept a number or a list of numbers.\n",
"\n",
"- A number or list of one number is specified: the same margin is applied to **all four sides**.\n",
"- A list of two numbers: the first margin applies to the **top and bottom**, the second - to the **left and right**.\n",
"- A list of three numbers: the first margin applies to the **top**, the second - to the **right and left**, the third - to the **bottom**.\n",
"- A list of four numbers: the margins are applied to the **top, right, bottom and left** in that order.\n",
"\n",
"It is acceptable to use `null` for any side; in this case, the default side value for this element will be used."
]
},
{
"cell_type": "code",
"execution_count": 1,
"id": "9304d8d0",
"metadata": {
"execution": {
"iopub.execute_input": "2025-12-03T16:07:09.646613Z",
"iopub.status.busy": "2025-12-03T16:07:09.643826Z",
"iopub.status.idle": "2025-12-03T16:07:11.620035Z",
"shell.execute_reply": "2025-12-03T16:07:11.619527Z"
}
},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
]
},
"metadata": {},
"output_type": "display_data"
},
{
"data": {
"text/html": [
" \n",
" "
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"%useLatestDescriptors\n",
"%use lets-plot"
]
},
{
"cell_type": "code",
"execution_count": 2,
"id": "1318eeef",
"metadata": {
"execution": {
"iopub.execute_input": "2025-12-03T16:07:11.622273Z",
"iopub.status.busy": "2025-12-03T16:07:11.621727Z",
"iopub.status.idle": "2025-12-03T16:07:11.657313Z",
"shell.execute_reply": "2025-12-03T16:07:11.657444Z"
}
},
"outputs": [
{
"data": {
"text/plain": [
"Lets-Plot Kotlin API v.4.12.0. Frontend: Notebook with dynamically loaded JS. Lets-Plot JS v.4.8.1.\n",
"Outputs: Web (HTML+JS), Kotlin Notebook (Swing), Static SVG (hidden)"
]
},
"execution_count": 2,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"LetsPlot.getInfo()"
]
},
{
"cell_type": "code",
"execution_count": 3,
"id": "6fb71ad3",
"metadata": {
"execution": {
"iopub.execute_input": "2025-12-03T16:07:11.658918Z",
"iopub.status.busy": "2025-12-03T16:07:11.658666Z",
"iopub.status.idle": "2025-12-03T16:07:11.875547Z",
"shell.execute_reply": "2025-12-03T16:07:11.875273Z"
}
},
"outputs": [],
"source": [
"import kotlin.random.Random\n",
"\n",
"val rand = Random(37)\n",
"val barData = mapOf(\n",
" \"x\" to List(100) { rand.nextInt(10)}\n",
")\n",
"\n",
"val p = letsPlot(barData) {x = \"x\"} + \n",
" geomBar() + \n",
" ggtitle(\"Barchart\") +\n",
" themeLight() + \n",
" theme(plotBackground = elementRect(size = 4))"
]
},
{
"cell_type": "markdown",
"id": "939abcc4",
"metadata": {},
"source": [
"#### Plot without Margins"
]
},
{
"cell_type": "code",
"execution_count": 4,
"id": "c3a57af3",
"metadata": {
"execution": {
"iopub.execute_input": "2025-12-03T16:07:11.877020Z",
"iopub.status.busy": "2025-12-03T16:07:11.876721Z",
"iopub.status.idle": "2025-12-03T16:07:12.091805Z",
"shell.execute_reply": "2025-12-03T16:07:12.091926Z"
}
},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
]
},
"metadata": {},
"output_type": "display_data"
},
{
"data": {
"application/plot+json": {
"apply_color_scheme": true,
"output": {
"data": {
"x": [
8.0,
4.0,
9.0,
7.0,
3.0,
3.0,
2.0,
9.0,
8.0,
3.0,
4.0,
2.0,
4.0,
6.0,
7.0,
4.0,
5.0,
2.0,
5.0,
7.0,
1.0,
3.0,
6.0,
7.0,
9.0,
9.0,
1.0,
4.0,
0.0,
8.0,
2.0,
3.0,
9.0,
7.0,
8.0,
6.0,
8.0,
8.0,
8.0,
8.0,
8.0,
3.0,
2.0,
4.0,
5.0,
2.0,
1.0,
9.0,
8.0,
2.0,
0.0,
5.0,
4.0,
7.0,
9.0,
0.0,
4.0,
6.0,
4.0,
6.0,
0.0,
7.0,
4.0,
8.0,
5.0,
1.0,
1.0,
7.0,
8.0,
6.0,
1.0,
1.0,
4.0,
8.0,
7.0,
1.0,
8.0,
6.0,
5.0,
5.0,
9.0,
2.0,
0.0,
6.0,
1.0,
7.0,
4.0,
0.0,
2.0,
4.0,
5.0,
8.0,
4.0,
0.0,
1.0,
4.0,
5.0,
6.0,
0.0,
7.0
]
},
"data_meta": {
"series_annotations": [
{
"column": "x",
"type": "int"
}
]
},
"ggtitle": {
"text": "Barchart"
},
"kind": "plot",
"layers": [
{
"geom": "bar",
"mapping": {},
"position": "stack",
"stat": "count"
}
],
"mapping": {
"x": "x"
},
"scales": [],
"theme": {
"name": "light",
"plot_background": {
"blank": false,
"size": 4.0
}
}
},
"output_type": "lets_plot_spec",
"swing_enabled": true
},
"text/html": [
" \n",
" \n",
" "
]
},
"execution_count": 4,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"p"
]
},
{
"cell_type": "markdown",
"id": "12422bb7",
"metadata": {},
"source": [
"#### Margins Around the Plot"
]
},
{
"cell_type": "code",
"execution_count": 5,
"id": "7dda150c",
"metadata": {
"execution": {
"iopub.execute_input": "2025-12-03T16:07:12.093431Z",
"iopub.status.busy": "2025-12-03T16:07:12.093244Z",
"iopub.status.idle": "2025-12-03T16:07:12.225249Z",
"shell.execute_reply": "2025-12-03T16:07:12.225371Z"
}
},
"outputs": [
{
"data": {
"application/plot+json": {
"apply_color_scheme": true,
"output": {
"figures": [
{
"data": {
"x": [
8.0,
4.0,
9.0,
7.0,
3.0,
3.0,
2.0,
9.0,
8.0,
3.0,
4.0,
2.0,
4.0,
6.0,
7.0,
4.0,
5.0,
2.0,
5.0,
7.0,
1.0,
3.0,
6.0,
7.0,
9.0,
9.0,
1.0,
4.0,
0.0,
8.0,
2.0,
3.0,
9.0,
7.0,
8.0,
6.0,
8.0,
8.0,
8.0,
8.0,
8.0,
3.0,
2.0,
4.0,
5.0,
2.0,
1.0,
9.0,
8.0,
2.0,
0.0,
5.0,
4.0,
7.0,
9.0,
0.0,
4.0,
6.0,
4.0,
6.0,
0.0,
7.0,
4.0,
8.0,
5.0,
1.0,
1.0,
7.0,
8.0,
6.0,
1.0,
1.0,
4.0,
8.0,
7.0,
1.0,
8.0,
6.0,
5.0,
5.0,
9.0,
2.0,
0.0,
6.0,
1.0,
7.0,
4.0,
0.0,
2.0,
4.0,
5.0,
8.0,
4.0,
0.0,
1.0,
4.0,
5.0,
6.0,
0.0,
7.0
]
},
"data_meta": {
"series_annotations": [
{
"column": "x",
"type": "int"
}
]
},
"ggtitle": {
"text": "plotMargin=40 (all sides)"
},
"kind": "plot",
"layers": [
{
"geom": "bar",
"mapping": {},
"position": "stack",
"stat": "count"
}
],
"mapping": {
"x": "x"
},
"scales": [],
"theme": {
"name": "light",
"plot_background": {
"blank": false,
"size": 4.0
},
"plot_margin": 40.0
}
},
{
"data": {
"x": [
8.0,
4.0,
9.0,
7.0,
3.0,
3.0,
2.0,
9.0,
8.0,
3.0,
4.0,
2.0,
4.0,
6.0,
7.0,
4.0,
5.0,
2.0,
5.0,
7.0,
1.0,
3.0,
6.0,
7.0,
9.0,
9.0,
1.0,
4.0,
0.0,
8.0,
2.0,
3.0,
9.0,
7.0,
8.0,
6.0,
8.0,
8.0,
8.0,
8.0,
8.0,
3.0,
2.0,
4.0,
5.0,
2.0,
1.0,
9.0,
8.0,
2.0,
0.0,
5.0,
4.0,
7.0,
9.0,
0.0,
4.0,
6.0,
4.0,
6.0,
0.0,
7.0,
4.0,
8.0,
5.0,
1.0,
1.0,
7.0,
8.0,
6.0,
1.0,
1.0,
4.0,
8.0,
7.0,
1.0,
8.0,
6.0,
5.0,
5.0,
9.0,
2.0,
0.0,
6.0,
1.0,
7.0,
4.0,
0.0,
2.0,
4.0,
5.0,
8.0,
4.0,
0.0,
1.0,
4.0,
5.0,
6.0,
0.0,
7.0
]
},
"data_meta": {
"series_annotations": [
{
"column": "x",
"type": "int"
}
]
},
"ggtitle": {
"text": "plotMargin=[40,20]\n(top/bottom, left/right)"
},
"kind": "plot",
"layers": [
{
"geom": "bar",
"mapping": {},
"position": "stack",
"stat": "count"
}
],
"mapping": {
"x": "x"
},
"scales": [],
"theme": {
"name": "light",
"plot_background": {
"blank": false,
"size": 4.0
},
"plot_margin": [
40.0,
20.0
]
}
},
{
"data": {
"x": [
8.0,
4.0,
9.0,
7.0,
3.0,
3.0,
2.0,
9.0,
8.0,
3.0,
4.0,
2.0,
4.0,
6.0,
7.0,
4.0,
5.0,
2.0,
5.0,
7.0,
1.0,
3.0,
6.0,
7.0,
9.0,
9.0,
1.0,
4.0,
0.0,
8.0,
2.0,
3.0,
9.0,
7.0,
8.0,
6.0,
8.0,
8.0,
8.0,
8.0,
8.0,
3.0,
2.0,
4.0,
5.0,
2.0,
1.0,
9.0,
8.0,
2.0,
0.0,
5.0,
4.0,
7.0,
9.0,
0.0,
4.0,
6.0,
4.0,
6.0,
0.0,
7.0,
4.0,
8.0,
5.0,
1.0,
1.0,
7.0,
8.0,
6.0,
1.0,
1.0,
4.0,
8.0,
7.0,
1.0,
8.0,
6.0,
5.0,
5.0,
9.0,
2.0,
0.0,
6.0,
1.0,
7.0,
4.0,
0.0,
2.0,
4.0,
5.0,
8.0,
4.0,
0.0,
1.0,
4.0,
5.0,
6.0,
0.0,
7.0
]
},
"data_meta": {
"series_annotations": [
{
"column": "x",
"type": "int"
}
]
},
"ggtitle": {
"text": "plotMargin=[40,20,10]\n(top, left/right, bottom)"
},
"kind": "plot",
"layers": [
{
"geom": "bar",
"mapping": {},
"position": "stack",
"stat": "count"
}
],
"mapping": {
"x": "x"
},
"scales": [],
"theme": {
"name": "light",
"plot_background": {
"blank": false,
"size": 4.0
},
"plot_margin": [
40.0,
20.0,
10.0
]
}
},
{
"data": {
"x": [
8.0,
4.0,
9.0,
7.0,
3.0,
3.0,
2.0,
9.0,
8.0,
3.0,
4.0,
2.0,
4.0,
6.0,
7.0,
4.0,
5.0,
2.0,
5.0,
7.0,
1.0,
3.0,
6.0,
7.0,
9.0,
9.0,
1.0,
4.0,
0.0,
8.0,
2.0,
3.0,
9.0,
7.0,
8.0,
6.0,
8.0,
8.0,
8.0,
8.0,
8.0,
3.0,
2.0,
4.0,
5.0,
2.0,
1.0,
9.0,
8.0,
2.0,
0.0,
5.0,
4.0,
7.0,
9.0,
0.0,
4.0,
6.0,
4.0,
6.0,
0.0,
7.0,
4.0,
8.0,
5.0,
1.0,
1.0,
7.0,
8.0,
6.0,
1.0,
1.0,
4.0,
8.0,
7.0,
1.0,
8.0,
6.0,
5.0,
5.0,
9.0,
2.0,
0.0,
6.0,
1.0,
7.0,
4.0,
0.0,
2.0,
4.0,
5.0,
8.0,
4.0,
0.0,
1.0,
4.0,
5.0,
6.0,
0.0,
7.0
]
},
"data_meta": {
"series_annotations": [
{
"column": "x",
"type": "int"
}
]
},
"ggtitle": {
"text": "plotMargin=[40,10,10,20]\n(top, right, bottom, left)"
},
"kind": "plot",
"layers": [
{
"geom": "bar",
"mapping": {},
"position": "stack",
"stat": "count"
}
],
"mapping": {
"x": "x"
},
"scales": [],
"theme": {
"name": "light",
"plot_background": {
"blank": false,
"size": 4.0
},
"plot_margin": [
40.0,
10.0,
10.0,
20.0
]
}
}
],
"kind": "subplots",
"layout": {
"align": false,
"fit": true,
"name": "grid",
"ncol": 2,
"nrow": 2
}
},
"output_type": "lets_plot_spec",
"swing_enabled": true
},
"text/html": [
" \n",
" \n",
" "
]
},
"execution_count": 5,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"gggrid(\n",
" listOf(\n",
" p + theme(plotMargin = 40) + ggtitle(\"plotMargin=40 (all sides)\"),\n",
" p + theme(plotMargin = listOf(40, 20)) + \n",
" ggtitle(\"plotMargin=[40,20]\\n(top/bottom, left/right)\"),\n",
" p + theme(plotMargin = listOf(40, 20, 10)) + \n",
" ggtitle(\"plotMargin=[40,20,10]\\n(top, left/right, bottom)\"),\n",
" p + theme(plotMargin = listOf(40, 10, 10, 20)) + \n",
" ggtitle(\"plotMargin=[40,10,10,20]\\n(top, right, bottom, left)\")\n",
" ),\n",
" ncol=2\n",
")"
]
},
{
"cell_type": "markdown",
"id": "789ff5c5",
"metadata": {},
"source": [
"#### Margins Around the Text Element"
]
},
{
"cell_type": "code",
"execution_count": 6,
"id": "1350c45f",
"metadata": {
"execution": {
"iopub.execute_input": "2025-12-03T16:07:12.227243Z",
"iopub.status.busy": "2025-12-03T16:07:12.227023Z",
"iopub.status.idle": "2025-12-03T16:07:12.282798Z",
"shell.execute_reply": "2025-12-03T16:07:12.282925Z"
}
},
"outputs": [
{
"data": {
"application/plot+json": {
"apply_color_scheme": true,
"output": {
"data": {
"x": [
8.0,
4.0,
9.0,
7.0,
3.0,
3.0,
2.0,
9.0,
8.0,
3.0,
4.0,
2.0,
4.0,
6.0,
7.0,
4.0,
5.0,
2.0,
5.0,
7.0,
1.0,
3.0,
6.0,
7.0,
9.0,
9.0,
1.0,
4.0,
0.0,
8.0,
2.0,
3.0,
9.0,
7.0,
8.0,
6.0,
8.0,
8.0,
8.0,
8.0,
8.0,
3.0,
2.0,
4.0,
5.0,
2.0,
1.0,
9.0,
8.0,
2.0,
0.0,
5.0,
4.0,
7.0,
9.0,
0.0,
4.0,
6.0,
4.0,
6.0,
0.0,
7.0,
4.0,
8.0,
5.0,
1.0,
1.0,
7.0,
8.0,
6.0,
1.0,
1.0,
4.0,
8.0,
7.0,
1.0,
8.0,
6.0,
5.0,
5.0,
9.0,
2.0,
0.0,
6.0,
1.0,
7.0,
4.0,
0.0,
2.0,
4.0,
5.0,
8.0,
4.0,
0.0,
1.0,
4.0,
5.0,
6.0,
0.0,
7.0
]
},
"data_meta": {
"series_annotations": [
{
"column": "x",
"type": "int"
}
]
},
"ggtitle": {
"text": "plotTitle=40 -> top/bottom=40,\naxisTitle=[20,20] -> top/right=20"
},
"kind": "plot",
"layers": [
{
"geom": "bar",
"mapping": {},
"position": "stack",
"stat": "count"
}
],
"mapping": {
"x": "x"
},
"scales": [],
"theme": {
"axis_title": {
"blank": false,
"margin": [
20.0,
20.0
]
},
"name": "light",
"plot_background": {
"blank": false,
"size": 4.0
},
"plot_title": {
"blank": false,
"margin": 40.0
}
}
},
"output_type": "lets_plot_spec",
"swing_enabled": true
},
"text/html": [
" \n",
" \n",
" "
]
},
"execution_count": 6,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"p + theme(plotTitle = elementText(margin=40),\n",
" axisTitle = elementText(margin=listOf(20, 20))) +\n",
" ggtitle(\"plotTitle=40 -> top/bottom=40,\\n\" +\n",
" \"axisTitle=[20,20] -> top/right=20\")"
]
}
],
"metadata": {
"kernelspec": {
"display_name": "Kotlin",
"language": "kotlin",
"name": "kotlin"
},
"language_info": {
"codemirror_mode": "text/x-kotlin",
"file_extension": ".kt",
"mimetype": "text/x-kotlin",
"name": "kotlin",
"nbconvert_exporter": "",
"pygments_lexer": "kotlin",
"version": "2.2.20-Beta2"
}
},
"nbformat": 4,
"nbformat_minor": 5
}