# How to Create PowerPoint Shapes with Geometry Presets, Gradients, and Pattern Fills Using OfficeCLI

> Learn to create PowerPoint shapes with geometry presets, gradients, and pattern fills using OfficeCLI. Effortlessly style slides with JSON batch commands for stunning visuals.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: how-to-guide
- Published: 2026-08-09

---

**OfficeCLI creates and styles PowerPoint shapes by sending JSON batch commands through the `Document.batch` method, allowing you to set geometry presets, gradient fills, and pattern fills via a unified property-based protocol.**

OfficeCLI is an open-source command-line interface and Node SDK for automating Microsoft Office documents. When working with PowerPoint presentations, you can programmatically define shape appearance—including geometric outlines, color gradients, and pattern overlays—by constructing batch items that target specific shape paths within the presentation structure.

## Understanding the OfficeCLI Command Protocol

OfficeCLI communicates with a resident Office process using a JSON-based batch protocol. Every shape styling operation is encapsulated as a batch item containing three core fields.

### The Batch Item Structure

Each batch item follows this schema:

- **command** – The operation verb, typically `"set"` for modifying properties
- **path** – A URI-like reference to the target object (e.g., `/Slide1/Shapes/Shape1`)
- **props** – A map of property names and values to apply

The Node SDK forwards these batches through the `Document.batch` method, implemented around lines 496-506 in [`sdk/node/index.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js). This method builds a `batchJson` payload and transmits it to the resident process, which maps the path to the actual PowerPoint object model.

## Setting Geometry Presets for PowerPoint Shapes

PowerPoint shapes support **geometry presets** that define the base outline of the shape. You set these using the `geometryPreset` property within the batch item's `props` object.

The preset names correspond to PowerPoint's internal enumeration. Common values include `RoundedRectangle`, `Ellipse`, `RightArrow`, and `Star5`.

```json
{
  "command": "set",
  "path": "/Slide1/Shapes/MyShape",
  "props": {
    "geometryPreset": "RoundedRectangle"
  }
}

```

When the resident process receives this command, it applies the specified geometry to the shape located at the given path, transforming the shape's outline to match the preset definition.

## Applying Gradient Fills to Shapes

**Gradient fills** create smooth color transitions across a shape's surface. In OfficeCLI, you define gradients through a nested `fill` object where `type` is set to `"gradient"` and the `gradient` field contains direction and color stop definitions.

```json
{
  "command": "set",
  "path": "/Slide1/Shapes/MyShape",
  "props": {
    "fill": {
      "type": "gradient",
      "gradient": {
        "direction": "horizontal",
        "stops": [
          { "offset": 0, "color": "#FF5733" },
          { "offset": 0.5, "color": "#33C1FF" },
          { "offset": 1, "color": "#3357FF" }
        ]
      }
    }
  }
}

```

Supported directions include `vertical`, `horizontal`, and `diagonal`. Each stop requires an `offset` value between 0 and 1, and a hex `color` string. The resident process translates these values into Office Open XML gradient definitions.

## Configuring Pattern Fills

**Pattern fills** overlay geometric textures onto shapes using foreground and background colors. Set `fill.type` to `"pattern"` and provide a `pattern` object containing the pattern name and color specifications.

```json
{
  "command": "set",
  "path": "/Slide1/Shapes/MyShape",
  "props": {
    "fill": {
      "type": "pattern",
      "pattern": {
        "name": "DiagonalCross",
        "foregroundColor": "#FFFFFF",
        "backgroundColor": "#000000"
      }
    }
  }
}

```

Available pattern names include `DiagonalCross`, `Cross`, and other PowerPoint standard patterns. The `foregroundColor` defines the pattern line color, while `backgroundColor` fills the spaces between pattern elements.

## Complete Implementation Examples

You can combine geometry presets, gradients, and patterns in a single batch operation. Below are implementations using both the Node SDK and the pure CLI interface.

### Node SDK Approach

The Node SDK provides a typed interface through the `open` function and `Document.batch` method. This example creates a star shape with a diagonal gradient:

```javascript
import { open } from '@iOfficeAI/officecli';

(async () => {
  const doc = await open('presentation.pptx');
  
  await doc.batch([
    {
      command: 'set',
      path: '/Slide2/Shapes/StarShape',
      props: {
        geometryPreset: 'Star5',
        fill: {
          type: 'gradient',
          gradient: {
            direction: 'diagonal',
            stops: [
              { offset: 0, color: '#FFD700' },
              { offset: 1, color: '#8B0000' }
            ]
          }
        }
      }
    }
  ]);
  
  await doc.close();
})();

```

The `batch` method queues the operation and transmits it to the Office resident process, applying all specified properties atomically.

### Pure CLI Approach

For shell scripts or one-off operations, use the `officecli batch` command with inline JSON:

```bash
officecli batch presentation.pptx \
  --json '[
    {
      "command": "set",
      "path": "/Slide3/Shapes/RectShape",
      "props": {
        "geometryPreset": "RoundedRectangle",
        "fill": {
          "type": "pattern",
          "pattern": {
            "name": "Cross",
            "foregroundColor": "#FF00FF",
            "backgroundColor": "#FFFF00"
          }
        }
      }
    }
  ]'

```

The CLI parses the JSON array, validates the batch structure, and forwards the commands to the resident process handling the specified `.pptx` file.

## Architecture and Source Code References

Understanding the underlying implementation helps debug complex shape operations.

**Batch Processing Core** – The `Document.batch` implementation in [`sdk/node/index.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js) (lines 496-506) constructs the JSON payload and manages the communication channel with the Office resident process.

**Shape Detection** – The file [`src/officecli/Resources/watch-overlay.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Resources/watch-overlay.js) contains the logic for identifying PowerPoint shape objects and routing non-cell commands. This resource handles the translation from JSON paths to actual shape instances within the presentation's object model.

**Type Definitions** – The TypeScript definitions in [`sdk/node/index.d.ts`](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.d.ts) document the `batch` method signature and available property interfaces for SDK consumers.

## Summary

- OfficeCLI uses a JSON batch protocol with `command`, `path`, and `props` fields to manipulate PowerPoint shapes.
- Set **geometry presets** using the `geometryPreset` property with values like `RoundedRectangle` or `Star5`.
- Configure **gradient fills** by setting `fill.type` to `"gradient"` and defining direction and color stops.
- Apply **pattern fills** by setting `fill.type` to `"pattern"` and specifying pattern names with foreground and background colors.
- The `Document.batch` method in [`sdk/node/index.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js) forwards operations to the resident process, while [`src/officecli/Resources/watch-overlay.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Resources/watch-overlay.js) handles shape-specific routing.

## Frequently Asked Questions

### What JSON structure does OfficeCLI expect for shape styling?

OfficeCLI expects batch items containing three fields: `command` (typically `"set"`), `path` (the URI-like location such as `/Slide1/Shapes/Shape1`), and `props` (an object containing `geometryPreset`, `fill`, or other style properties). The resident process validates this structure before applying changes to the presentation.

### Can I combine geometry presets with multiple fill types in one command?

Yes, you can combine a `geometryPreset` with either a gradient or pattern fill within the same `props` object in a single batch item. However, a shape can only have one active fill type at a time; specifying both `gradient` and `pattern` in the same `fill` object would result in the last defined property taking precedence.

### Where is the batch processing logic implemented in the OfficeCLI source?

The batch processing logic resides in [`sdk/node/index.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js) around lines 496-506, where the `Document.batch` method serializes the batch array into JSON and transmits it to the Office resident process. The resident side interprets these commands and maps them to the Office Open XML API for shape manipulation.

### Does OfficeCLI support all PowerPoint gradient directions?

OfficeCLI supports the standard PowerPoint gradient directions including `vertical`, `horizontal`, and `diagonal`. These values are passed directly to the underlying Office API, ensuring compatibility with PowerPoint's native gradient rendering engine.