In our previous tutorial (Part 63), we explored how to freely duplicate presentation pages using Slide.duplicate(). We learned the technique of copying a template slide to automatically generate department-specific pages, such as for “Engineering” and “Sales.”
Once your slides are set up, the next natural step is to automatically build out the slide contents and visual design elements! Especially in monthly performance reports, placing rectangular card shapes (topic cards) to spotlight “Monthly Highlights” or “Key Takeaways” is a standard design best practice for business presentations.
Manually inserting shapes and tweaking their sizes and positions with a mouse takes time, and repeating the exact same layout tasks every month can get exhausting.
That is why in this 64th lesson, we will do a deep dive into an essential Google Apps Script method: Slide.insertShape(), which lets you draw any shape (like rectangles and rounded rectangles) onto a designated slide completely through code!
Using our Phase 7 project—the “Sapporo Office Monthly Performance Report”—we will cover practical tips for positioning and sizing shapes with pinpoint accuracy, demystify coordinate calculations in points (pt), and examine common pitfalls so you can master automated slide layouts with confidence!
1. What Is Slide.insertShape() in Google Apps Script?
Slide.insertShape() is a method that automatically creates and places a new shape (a Shape object) onto a designated slide (a Slide object).
Revisiting the “House, Room, Furniture” Analogy
Let’s organize the hierarchy of Google Slides operations using our familiar “House, Room, and Furniture” analogy from this series:
- [House] = The entire presentation (Retrieved via
SlidesApp.openById()) - [Room] = An individual slide page (Retrieved via
Presentation.getSlides()[0], etc.) - [Furniture] = Shapes, text boxes, images, etc. on the slide (★ Our star today!)
Just as we compared “cells” to furniture in the Google Sheets chapters [Part 4] and [Part 10], shapes and text containers placed on a slide act as furniture in Google Slides.
Calling Slide.insertShape() is essentially like delivering and installing a new rectangular shelf or card (shape) into your “room (slide)” with millimeter-level precision.
Basic Code Syntax
When using Slide.insertShape(), you specify five arguments: which shape to draw, where to place it (X and Y coordinates), and how large it should be (width and height).
// Basic syntax for inserting a shape on a slide
var shape = slide.insertShape(shapeType, left, top, width, height);
2. Mastering the 5 Arguments of insertShape()
Let’s examine each of the five arguments passed to insertShape() in detail.
| Order | Argument | Description | Example Value |
|---|---|---|---|
| 1st | shapeType | Shape type (Specified using an enum) | SlidesApp.ShapeType.RECTANGLE |
| 2nd | left | Distance from left edge of the slide (X-coordinate) | 50 (in pt) |
| 3rd | top | Distance from top edge of the slide (Y-coordinate) | 100 (in pt) |
| 4th | width | Width of the shape | 250 (in pt) |
| 5th | height | Height of the shape | 150 (in pt) |
① 1st Argument: Shape Type (ShapeType)
You specify the type of shape to draw using predefined enums under SlidesApp.ShapeType. Here are some of the most common ones:
SlidesApp.ShapeType.RECTANGLE: Standard rectangleSlidesApp.ShapeType.ROUNDED_RECTANGLE: Rounded rectangle (ideal for topic cards!)SlidesApp.ShapeType.ELLIPSE: Circle or ellipseSlidesApp.ShapeType.TEXT_BOX: Text box (*specialized container for text)
For topic cards in business decks, ROUNDED_RECTANGLE (which gives a softer, modern look) and standard RECTANGLE are the most frequently used choices.
② 2nd to 5th Arguments: Positioning and Sizing with “Points (pt)”
Position (left, top) and dimensions (width, height) are all expressed as numeric values in “points (pt)”.
- 1 pt ≈ 0.35 mm (72 pt = 1 inch)
- Standard 16:9 widescreen slide dimensions:
- Width: 960 pt
- Height: 540 pt
The origin point (X=0, Y=0) is located at the top-left corner of the slide canvas.
left: 50➡ 50 pt to the right from the left edge of the slidetop: 100➡ 100 pt down from the top edge of the slide
Once you get a feel for these numbers, positioning shapes exactly where you want them becomes second nature!
3. STEP 1: Preparation – Set Up the “Sapporo Office Monthly Performance Report” Slide
Let’s create a Google Slides presentation to practice drawing shapes with GAS.
Setup Steps
- Open Google Drive and create a new Google Slides presentation.
- Rename the file to “Sapporo Office Monthly Performance Report”.
- Change the layout of the first slide to “Blank,” or select and delete all default title text boxes to leave a completely blank canvas.
- Copy the presentation ID from your browser’s address bar (URL) and keep it handy.
URL Example:
https://docs.google.com/presentation/d/1a2b3c4d5e6f7g8h9i0j_EXAMPLE_ID/edit
* The alphanumeric string between/d/and/editis your presentation ID. This is the same workflow we covered in [Part 61]!
4. STEP 2: Hands-On – Draw a Topic Card Shape on Your Slide
Now that your presentation is ready, open the Apps Script editor and start writing your script. In this exercise, we will create a rounded rectangle card to showcase Sapporo Office highlights (such as “Soup Curry Collaboration Success” or “New Chitose Airport Branch Opening”).
1. Enter the Code
Open the script editor (either a container-bound script or a standalone script as covered in [Part 1]) and paste the code below. (Make sure to replace YOUR_SLIDE_ID_HERE with your actual presentation ID.)
function createTopicsCard() {
// 1. Open the "House" (presentation) by ID
var slideId = "YOUR_SLIDE_ID_HERE";
var presentation = SlidesApp.openById(slideId);
// 2. Get the "Room" (first slide)
var slide = presentation.getSlides()[0];
// 3. Define card position and dimensions (unit: pt)
var left = 50; // 50 pt from the left edge
var top = 100; // 100 pt from the top edge
var width = 260; // 260 pt wide
var height = 320; // 320 pt high
// 4. Draw a rounded rectangle shape (topic card) on the slide!
var cardShape = slide.insertShape(
SlidesApp.ShapeType.ROUNDED_RECTANGLE,
left,
top,
width,
height
);
// 5. Output completion log
Logger.log("Successfully drew the topic card shape for the Sapporo Office report!");
}
2. Line-by-Line Code Breakdown
var presentation = SlidesApp.openById(slideId);
The foundational command we learned in [Part 61]. It opens and returns the presentation object using its ID.var slide = presentation.getSlides()[0];
Retrieves the very first slide (room) in the presentation array.slide.insertShape(SlidesApp.ShapeType.ROUNDED_RECTANGLE, left, top, width, height);
Today’s featured method! Inserts a rounded rectangle on the first slide at(X=50, Y=100)with dimensions of260 pt wide × 320 pt high.
3. Save and Run
- Click the Save icon (floppy disk) in the Apps Script editor toolbar.
- Verify that the active function is set to
createTopicsCard, then click Run. - If this is your first execution, complete the Google authorization prompt to allow script access.
- Switch over to your Google Slides tab and view the result!
[Execution Verification] If a clean, grey (or default colored) rounded rectangle card shape appears neatly positioned on the left side of the slide, your script executed with total success!
5. STEP 3: Advanced Layout – Arrange 3 Topic Cards Horizontally with a Calculation Formula
Now that you can insert a single card, let’s tackle a practical business layout: arranging three topic cards side by side with consistent spacing across the slide.
Doing this manually can be tedious due to margin calculations and alignment adjustments. With a simple GAS for loop and basic arithmetic, however, you can generate a perfectly aligned row of three cards in seconds!
Script to Automatically Place a 3-Card Row
function createTripleTopicsCards() {
var slideId = "YOUR_SLIDE_ID_HERE";
var presentation = SlidesApp.openById(slideId);
var slide = presentation.getSlides()[0];
// Layout calculation parameters
var startLeft = 50; // Left position of the first card
var top = 120; // Y-coordinate shared by all cards
var cardWidth = 260; // Width of each card
var cardHeight = 300; // Height of each card
var gap = 40; // Spacing (margin) between cards
// Use a for loop to draw 3 cards sequentially!
for (var i = 0; i < 3; i++) {
// Calculate the X-coordinate for card index i (★ Key formula!)
// Card 1 (i=0): 50 + 0 = 50
// Card 2 (i=1): 50 + (260 + 40) * 1 = 350
// Card 3 (i=2): 50 + (260 + 40) * 2 = 650
var currentLeft = startLeft + (cardWidth + gap) * i;
// Draw the shape
var card = slide.insertShape(
SlidesApp.ShapeType.ROUNDED_RECTANGLE,
currentLeft,
top,
cardWidth,
cardHeight
);
Logger.log("Inserted topic card #" + (i + 1) + " (X-coordinate: " + currentLeft + " pt)");
}
}
Execution Results
Run the function and check your slide. You should see three cards, each 260 pt wide, aligned across the slide with a crisp 40 pt margin between them!
By leveraging the simple formula currentLeft = startLeft + (cardWidth + gap) * i, you can build responsive, pixel-perfect layouts effortlessly without manual alignment tools.
6. 4 Common Traps for Beginners and How to Fix Them
Here are four frequent errors and surprises beginners encounter when working with Slide.insertShape(), along with proactive solutions to keep your automation smooth.
Trap 1: Confusing Argument Order, Leading to Distorted or Off-Screen Shapes
This is the #1 mistake when starting out. Because insertShape takes five arguments, it is easy to swap their positions accidentally.
// ✕ Incorrect: left/top and width/height are swapped
slide.insertShape(SlidesApp.ShapeType.ROUNDED_RECTANGLE, top, left, height, width);
// ◯ Correct: Type ➡ Left ➡ Top ➡ Width ➡ Height
slide.insertShape(SlidesApp.ShapeType.ROUNDED_RECTANGLE, left, top, width, height);
[Helpful Rule of Thumb] Memorize the order as “Type, Left, Top, Width, Height” (Coordinates first, then dimensions!).
Trap 2: Typos in ShapeType Causing Runtime Errors
Constants like SlidesApp.ShapeType.ROUNDED_RECTANGLE require strict casing and underscores (_).
- ✕
SlidesApp.shapetype.rectangle(Incorrect lowercase) - ✕
SlidesApp.ShapeType.ROUND_RECTANGLE(Missing theED)
[Solution] Rather than typing the full constant by hand, type up to SlidesApp.ShapeType. and select the desired shape from the Apps Script autocomplete drop-down.
Trap 3: Coordinates (left / top) Are Too Large, Pushing Shapes Off-Canvas
If you lose track of the slide’s dimensions (960 pt wide × 540 pt high) and pass values like left = 1200 or top = 800, your shape will be generated outside the visible canvas boundary, making it look as though nothing happened.
[Solution]
- Keep horizontal positions (
left) roughly within 0 to 700 pt - Keep vertical positions (
top) roughly within 0 to 400 pt
Plan your coordinates so that left + width <= 960 and top + height <= 540.
Trap 4: “I Want to Put Text Inside the Shape, but How?”
When you draw a shape using insertShape(), it starts as a blank, unpopulated visual container.
You likely want to populate these cards with text like “Sapporo Office Monthly Target: 120% Achieved!”. To add and format text within a shape, you combine it with methods we will explore in upcoming lessons, such as Shape.getText() and TextRange.setText().
By saving the created shape into a variable like cardShape, you hold the reference needed to populate text and apply rich formatting dynamically in the next step!
7. Summary and What’s Next
In this tutorial, we learned how to programmatically draw and arrange shapes on Google Slides using Slide.insertShape().
Key Takeaways from Today
Slide.insertShape()automatically places new shape elements (furniture) onto a slide- Pass five arguments in order: Shape Type, Left, Top, Width, and Height
- Specify shapes using enums such as
SlidesApp.ShapeType.ROUNDED_RECTANGLE - Coordinates and sizes are measured in points (pt) (960 pt × 540 pt for standard 16:9 slides)
- Pairing a
forloop with a coordinate formula lets you align multi-card layouts instantly
You can now generate the structural layout and wireframe cards of your business presentations completely via code!
Right now, shapes inserted by default often appear in plain grey or light blue. In real-world reports, you often want conditional styling—such as bright green cards for achieved targets and soft red cards for items needing attention.
In our next tutorial (Part 65), we will explore how to customize shape colors and borders using Shape.getFill() and Shape.getBorder(). Stay tuned to learn how to turn basic shapes into professional, dynamic data visualizations!
