Expand Tool

Use Tools → Methods → Expand to convert tagged Illustrator artwork from editable live objects and appearances into the concrete artwork that produces their visible result. Darty combines Illustrator's Expand Appearance and Expand behavior, so one operation can expose effect-generated copies and then expand applicable objects, fills, strokes, and gradients.

Expand is useful when later rows must work with the actual shapes inside a symbol, outlined stroke, pattern, gradient, text object, blend, or complex appearance. It is a structural and potentially destructive conversion: the result can contain many paths, groups, clipping groups, mesh objects, or rasterized effect elements and cannot always be reconstructed into the original live artwork.

For extensive illustrated examples and spreadsheet syntax, see the Expand method reference.

Expand Editor

The editor organizes the operation around three decisions:

1. Which artwork should be expanded?
2. Which parts of that artwork should become concrete objects?
3. Should the generated result receive predictable numbered tags?

Choose the Artwork to Expand

Artwork Tags identifies the source artwork. Enter a focused Darty tag search such as productSymbol, headline | badge, or another supported expression.

The * target is deliberately broad and can structurally change every eligible object in scope. Expand can greatly increase the number of objects and nesting levels in a document, so prefer explicit tags for reusable rows.

Use Selection Tags copies existing Darty tags from the artwork currently selected in Illustrator into Artwork Tags. It helps construct the reusable search; it does not expand the selection or create tags.

Apply to Selection performs a one-time test on the currently selected artwork without adding a Table row or relying on the saved Artwork Tags value. This is often the safest way to learn what structure a particular appearance will produce before capturing the operation for a larger sheet.

See Darty Tags for tag-search operators and Tools Method Actions and Apply Modes for the difference between selection targeting and captured rows.

Choose What Illustrator Expands

Object, Fill, Stroke, and Gradient Mesh are three-state checkboxes. Each one can explicitly enable or disable an Illustrator expand flag, or remain Unset so the property is omitted from the generated row.

Unset is not the same as False:

• True writes the property as true and explicitly requests that conversion.
• False writes the property as false and explicitly prevents that part from being expanded.
• Unset omits the property and lets the underlying method use its normal behavior.

The existing method reference documents Object as enabled by default when object is omitted. Use explicit True or False values when a reusable row must produce the same decision independently of defaults.

Expand Live Objects

Object writes object. Enable it when live object types such as text, symbols, and blends should become editable artwork.

Typical results include:

• Text converted to outlined shapes.
• A symbol instance released into editable grouped artwork.
• A blend expanded into its generated component objects.
• Appearance-generated copies exposed as separate items or nested groups.

Object expansion does not guarantee a flat set of paths. Illustrator often preserves the visual result inside one or more groups.

Expand Fills

Fill writes fill. Enable it when the fill itself must become editable artwork.

A simple solid fill may show little visible change, while a pattern fill can produce many path-based elements and clipping groups. Complex fills can therefore increase document size and nesting substantially.

Fill does not automatically outline a stroke. Enable Stroke separately when both parts must be converted.

Expand Strokes

Stroke writes stroke. Enable it when stroked paths should become filled outline shapes.

This is useful when later operations must edit the visible stroke contour as artwork rather than preserve a center path plus stroke weight. Pattern and gradient strokes can produce more complex filled or clipped results than ordinary solid strokes.

After expansion, stroke weight and brush-like behavior are no longer edited as the original live stroke. Keep a recoverable copy of production artwork when those properties may still need adjustment.

Convert Gradients

Illustrator can represent an expanded gradient as a mesh or as a sequence of discrete colored shapes.

Gradient Mesh

Gradient Mesh writes gradientMesh. Set it to True when applicable gradients should become mesh artwork. This preserves a smooth editable color field through mesh points, but the result requires mesh-editing techniques rather than ordinary gradient controls.

False explicitly prevents mesh conversion. Unset leaves the property out of the row.

Gradient Steps

Gradient Steps writes gradientSteps as a number. It chooses how many discrete colored shapes Illustrator uses when a gradient is expanded into stepped artwork. The displayed 256 is a placeholder, not a value written automatically.

A larger number can approximate a smoother gradient but creates more objects and a heavier document. A smaller number creates fewer shapes with more visible transitions. Enter a positive whole number only when stepped gradient expansion is intended; leave it blank when the row should not specify a step count.

Gradient Mesh and Gradient Steps describe alternative gradient outcomes. Configure the one that matches the needed result and test representative artwork before processing a complex document.

Tag the Expanded Results

Expand can create one result group or many generated objects, often with additional nesting. The optional Series fields provide predictable Darty tags for the artwork produced by the operation.

Series Tag writes seriesTag and supplies the shared prefix. Series Start writes seriesStart and chooses the first number.

For example, Series Tag expandedPart with Series Start 1 can create tags such as expandedPart1, expandedPart2, and expandedPart3 on generated results. Starting at 5 begins the numbering at expandedPart5.

The exact number and nesting of tagged results depend on the source artwork and enabled expand options. A pattern, complex appearance, or effect-generated copy can produce a very different structure from a simple stroked path. Inspect a sample result before later rows rely on a particular numbered item.

Series Start is meaningful only with Series Tag. Leave both fields blank when the expanded structure does not need new numbered targets.

When expansion produces deeply nested groups, later Ungroup rows can release successive levels and apply another series to the exposed contents. The method reference demonstrates this advanced series-tag reuse workflow.

Skip a Reusable Expand Row

Skip is a three-state checkbox that writes skip only when True or False is selected.

• True writes skip:true and preserves the original artwork for that data record.
• False writes skip:false and explicitly allows Expand to run.
• Unset omits the property and leaves the row to normal execution.

Skip is useful when the same sheet processes records that do not all require structural conversion. See Skip and *.

Understand the Possible Results

Expand follows the structure needed to reproduce Illustrator's visible artwork. Depending on the source, it can produce:

• No effective change because the selected option does not apply to that object type.
• One or more nested groups.
• Outlined text or strokes.
• Paths and clipping groups created from patterns.
• Mesh objects or many stepped shapes created from gradients.
• Additional objects created by live effects or appearance-level copies.
• Raster items for appearance effects whose visible result is raster-based.

The operation can change how later tag searches reach the artwork because a previously tagged object may become a container around generated children. Result series tags and deliberate Ungroup rows help make those new structures addressable.

Build a Safe Expand Configuration

1. Save a recoverable copy of important live artwork or work on a duplicate.
2. Select one representative object and use Apply to Selection to inspect its actual expanded structure.
3. Enter a narrow Artwork Tags search for the reusable row.
4. Set Object, Fill, Stroke, and the intended gradient strategy explicitly when the conversion must be predictable.
5. Add Series Tag and Series Start when later rows must identify generated results.
6. Use Add Row to inspect the generated properties before applying the reusable configuration.
7. After applying, inspect the Layers panel, clipping groups, object count, appearance, and generated tags.
8. Only then reuse the row across a larger document or data set.

Validation, Warnings, and Common Problems

• Apply to Selection requires selected Illustrator artwork.
• A broad * target can expand far more artwork than intended.
• Gradient Steps expects a numeric count; the placeholder is not an automatic value.
• Series Start expects a number and should be paired with Series Tag.
• If nothing changes, the source may not contain artwork applicable to the enabled option.
• If too many objects are created, review Fill, gradient conversion, patterns, and live effects before repeating the operation.
• If later methods cannot find the expected object, inspect whether expansion placed it inside a new group or applied a series tag to a generated result.
• Expand is not the same as Group, Compound Path, Pathfinder, or Outline alone; it can invoke several Illustrator conversions as required by the source appearance.

Control-to-Property Summary

Capture, Apply, and Review

• Tools Method Actions and Apply Modes explains Reset, Add Row, Apply, and Apply to Selection.
• Tools Method Table Preview explains how to inspect, edit, reorder, copy, download, and apply captured Expand rows.
• Expand method reference provides detailed examples, sample spreadsheets, downloads, and advanced nested-result workflows.