Skip to content

How to use X/Y/Z Grid

Introduction

The X/Y/Z Grid script generates multiple images while automatically varying selected values, then displays results in labeled grids.

To activate X/Y/Z Grid, open the Script dropdown and select "X/Y/Z Grid".

Several new UI controls will appear.

X, Y, and Z Types define what changes across generated images.

X Type creates columns, Y Type creates rows, and Z Type creates separate grid images (a "3D grid" effect). X/Y/Z Values define the actual values to test. For some types, values are selected from a dropdown. For others, values are comma-separated.

Most options are self-explanatory, such as Model, Seed, VAE, and CLiP Skip.

Prompt S/R

"Prompt S/R" means Prompt Search and Replace, the [Prompt] Search & replace type. Its values are a comma-separated list that normally starts with text already present in the prompt, followed by the replacements. One image is created per value.

For example, with the prompt a lazy cat and Prompt S/R cat,dog,monkey, three images are created: a lazy cat, a lazy dog, and a lazy monkey.

Values are not limited to single words. Phrases work, for example lazy cat,boisterous dog,mischievous monkey, and so does the full prompt, for example a lazy cat,three blind mice,an astronaut on the moon.

Embeddings and LoRAs are also valid search-and-replace terms, for example <lora:FirstLora:1>,<lora:SecondLora:1>,<lora:ThirdLora:1>.

LoRA strength is varied the same way, for example <lora:FirstLora:1>,<lora:FirstLora:0.75>,<lora:FirstLora:0.5>,<lora:FirstLora:1.5>, or shortened to FirstLora:1,FirstLora:0.75,FirstLora:0.5,FirstLora:1.5.

Search term

Each image replaces a single search term:

  • the first value, when it occurs in the searched text
  • otherwise, the longest value that occurs there

The search term is replaced by the image's value wherever it occurs, in the prompt and the negative prompt alike. No other value is searched for, so values that contain one another produce exactly the listed prompts: woman,man,child on photo of a woman gives photo of a woman, photo of a man and photo of a child, and 0.8,1,1.2 on (red hair:0.8) gives (red hair:0.8), (red hair:1) and (red hair:1.2).

The first value does not have to be in the prompt. With the prompt a lazy dog and Prompt S/R cat,dog,monkey, dog is the search term and the images are a lazy cat, a lazy dog, and a lazy monkey. A term found only in the negative prompt works the same way: the negative prompt blurry with Prompt S/R blurry,lowres,jpeg artifacts varies the negative prompt alone.

When several values occur in the prompt, only the search term changes: a cat and a dog with cat,dog gives a cat and a dog and a dog and a dog.

When no value occurs in the searched text, every image shows the unchanged prompt and the server log shows the warning XYZ grid: search values=[...] not found fields=[...].

Searched text

The search runs on the text entered in the prompt boxes, before styles and wildcards are applied. A term that only a selected style adds, or that a wildcard expands to, is not found.

Each Prompt S/R type searches its own boxes:

  • [Prompt] Search & replace: Prompt and Negative prompt
  • [Prompt] Search & replace refine: Refine prompt and Refine negative prompt
  • [Prompt] Search & replace detailer: Detailer prompt and Detailer negative prompt
  • [Prompt] Search & replace all: all six, with one search term shared by them

An empty box is not searched, even where its pass falls back to the main prompt, so the refine and detailer types find nothing until their boxes are filled in.

Commas in replacement values

Replacement values are separated by commas, so every comma in the field is treated as a separator. Quotation marks are not special and do not group a value; wrapping a replacement in "..." only adds literal quote characters to the prompt. Spaces around each value are trimmed, and an empty value, such as the one after a trailing comma, is skipped.

A comma that belongs inside a single replacement is escaped with a backslash, written as \,. The backslash is stripped before the prompt is used, leaving an ordinary comma. This matters most when the whole prompt is replaced with alternatives that themselves contain commas.

For example, the prompt is a lazy cat and the goal is to swap the whole prompt for two alternatives that contain commas.

Without escaping, the value a lazy cat,a happy dog, wearing a hat,a wise owl, perched on a branch is split on every comma into five values: a lazy cat, a happy dog, wearing a hat, a wise owl, and perched on a branch. The result is five images with broken prompts.

With escaping, the value a lazy cat,a happy dog\, wearing a hat,a wise owl\, perched on a branch is split into three values. Because the search term a lazy cat is the full prompt, each value becomes a complete prompt, producing the three intended images: a lazy cat, a happy dog, wearing a hat, and a wise owl, perched on a branch.

Search terms match anywhere in the prompt

The search term is a plain text replacement with no word boundaries, so it is replaced wherever it occurs, including inside longer words. With the prompt a cat, intricate details and Prompt S/R cat,dog,owl, the cat inside intricate is replaced along with the standalone word: the second image becomes a dog, intridoge details and the third becomes a owl, intriowle details.

Distinctive terms avoid this. With Prompt S/R a cat,a fox,a wolf, none of the values occur inside intricate, so only the subject changes, giving a cat, intricate details, a fox, intricate details, and a wolf, intricate details.

Placeholder tokens

A placeholder token marks a fixed insertion point in the prompt and can be reused to fill several positions from a single value. The token works best when it is distinctive, so it does not match inside other words, and it avoids the __name__ form, which is reserved for wildcards.

For a fixed insertion point, the prompt portrait of SUBJECT_SLOT, oil painting, golden hour with Prompt S/R SUBJECT_SLOT,a fox,a deer,an owl varies only the subject while the style and lighting stay constant, giving portrait of a fox, oil painting, golden hour, portrait of a deer, oil painting, golden hour, and portrait of an owl, oil painting, golden hour.

For repeated positions, a token is replaced everywhere it appears. The prompt COLOR_SLOT hair and COLOR_SLOT eyes with Prompt S/R COLOR_SLOT,red,blue,green fills both positions from one value, giving red hair and red eyes, blue hair and blue eyes, and green hair and green eyes.

A placeholder also replaces the whole prompt with unrelated alternatives. The prompt PROMPT with Prompt S/R PROMPT,a serene lake at dawn\, misty,a neon cyberpunk alley\, raining produces three images:

  • PROMPT (the first value is the search term, so the first cell renders the literal token unchanged)
  • a serene lake at dawn, misty
  • a neon cyberpunk alley, raining

Each replacement is a complete prompt on its own: the token is not repeated in front of it, and internal commas are escaped as \,. When a usable first image matters more than a comma-free anchor, a complete prompt is placed in the prompt box and used as the first value instead of a token.