> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: Presets

## Article: Presets

## Article Link: https://dev.wix.com/docs/site-extensions/editor-react-components/editor-element/presets/presets.md

## Article Content:

import { Property, PropertyList, ExpandableSection } from "@wix/docs-ui/content";


# Presets
The `presets` property lets you define named visual variations of your component. Each key in the `presets` map is the preset's unique identifier, which is referred to as the preset key throughout this documentation. Each value configures the preset's display name, thumbnail, sizing, default values, and optional style overrides.

## Where to define

You can define `presets` in [`editorElement`](https://dev.wix.com/docs/site-extensions/editor-react-components/editor-element/editor-element.md).

<blockquote className="important">

**Important:** For presets to work, your component must wrap its root element in a container and spread `wix.presetsWrapperProps` onto it.

</blockquote>

## Preset defaults vs. style overrides

Each preset item has 2 fields that control its appearance: `presetDefaults` and `styleOverrides`. Both are optional, and they serve different purposes:

- Use `presetDefaults` to define the initial values that apply when a Wix user switches to a preset. This includes layout behavior, CSS properties, CSS custom properties, display filters, and nested element defaults. These values replace the component's base configuration for that preset.
- Use `styleOverrides` when you need breakpoint-aware or state-aware value overrides. For example, you might use `styleOverrides` to set a different hover color on mobile, or to adjust font sizes across breakpoints. Overrides in the `default` breakpoint cascade to all other breakpoints, while `small` overrides apply only to the mobile breakpoint.

## Preset item properties

Each item in the `presets` map accepts the following properties:

<PropertyList bordered>
  <Property
    name="displayName"
    type="string"
    description="The name shown in the editor's preset selector. Maximum 100 characters. Translatable."
  />
  <Property
    name="thumbnailUrl"
    type="string"
    required
    description="A valid web URL to a thumbnail image for the preset, displayed in the editor's preset panel. Must start with `http://` or `https://`. 13 to 500 characters."
  />
  <Property
    name="initialSize"
    type="ComponentInitialSize"
    description="The initial size of the component when switching into this preset."
  >
    <ExpandableSection name="ComponentInitialSize properties">
      <PropertyList>
        <Property
          name="width"
          type="InitialSizeSetting"
          description="The initial width setting."
        >
          <ExpandableSection name="InitialSizeSetting properties">
            <PropertyList>
              <Property
                name="sizingType"
                type="SizingType"
                description="The method used to calculate the initial size."
              >
                <ExpandableSection name="SizingType values">
                  <PropertyList>
                    <Property name="'content'" description="Size fits to the content size." />
                    <Property name="'stretched'" description="Size stretches to the parent size and tracks it unless the Wix user changes it." />
                    <Property name="'pixels'" description="Sets the size to a specific pixel value." />
                  </PropertyList>
                </ExpandableSection>
              </Property>
              <Property
                name="pixels"
                type="number"
                description="The size in pixels. Required when sizingType is 'pixels'. Minimum 1."
              />
            </PropertyList>
          </ExpandableSection>
        </Property>
        <Property
          name="height"
          type="InitialSizeSetting"
          description="The initial height setting."
        />
        <Property
          name="preserveAspectRatio"
          type="boolean"
          description="Whether to maintain the relationship between height and width while resizing on stage and rendering."
        />
      </PropertyList>
    </ExpandableSection>
  </Property>
  <Property
    name="styleOverrides"
    type="BreakpointPresetStyleOverrides"
    description="Per-preset style values that vary across breakpoints, with optional state support. Use to override CSS property values for the root element and inner elements at different breakpoints."
  >
    <ExpandableSection name="BreakpointPresetStyleOverrides properties">
      <PropertyList>
        <Property
          name="default"
          type="PresetStyleOverrides"
          description="Style overrides for the default breakpoint. These cascade to all other breakpoints."
        >
          <ExpandableSection name="PresetStyleOverrides properties">
            <PropertyList>
              <Property
                name="style"
                type="map<string, PresetStyleItemOverrides>"
                description="Style overrides for the root element. Each key is a CSS property or CSS custom property key."
              >
                <ExpandableSection name="PresetStyleItemOverrides properties">
                  <PropertyList>
                    <Property
                      name="value"
                      type="Value"
                      description="The override value for this style item."
                    />
                    <Property
                      name="statesValues"
                      type="map<string, Value>"
                      description="Override values for specific states. Each key is a state key defined in the element's states map."
                    />
                  </PropertyList>
                </ExpandableSection>
              </Property>
              <Property
                name="elements"
                type="map<string, ElementStyleOverrides>"
                description="Style overrides for inner elements. Each key is an element key."
              >
                <ExpandableSection name="ElementStyleOverrides properties">
                  <PropertyList>
                    <Property
                      name="presetKey"
                      type="string"
                      description="The override preset key for this element. Maximum 100 characters."
                    />
                    <Property
                      name="style"
                      type="map<string, PresetStyleItemOverrides>"
                      description="Style overrides for this element."
                    />
                    <Property
                      name="elements"
                      type="map<string, ElementStyleOverrides>"
                      description="Style overrides for further nested inner elements."
                    />
                  </PropertyList>
                </ExpandableSection>
              </Property>
            </PropertyList>
          </ExpandableSection>
        </Property>
        <Property
          name="small"
          type="PresetStyleOverrides"
          description="Style overrides specifically for the small (mobile) breakpoint."
        >
          <ExpandableSection name="PresetStyleOverrides properties">
            <PropertyList>
              <Property
                name="style"
                type="map<string, PresetStyleItemOverrides>"
                description="Style overrides for the root element. Each key is a CSS property or CSS custom property key."
              >
                <ExpandableSection name="PresetStyleItemOverrides properties">
                  <PropertyList>
                    <Property
                      name="value"
                      type="Value"
                      description="The override value for this style item."
                    />
                    <Property
                      name="statesValues"
                      type="map<string, Value>"
                      description="Override values for specific states. Each key is a state key defined in the element's states map."
                    />
                  </PropertyList>
                </ExpandableSection>
              </Property>
              <Property
                name="elements"
                type="map<string, ElementStyleOverrides>"
                description="Style overrides for inner elements. Each key is an element key."
              >
                <ExpandableSection name="ElementStyleOverrides properties">
                  <PropertyList>
                    <Property
                      name="presetKey"
                      type="string"
                      description="The override preset key for this element. Maximum 100 characters."
                    />
                    <Property
                      name="style"
                      type="map<string, PresetStyleItemOverrides>"
                      description="Style overrides for this element."
                    />
                    <Property
                      name="elements"
                      type="map<string, ElementStyleOverrides>"
                      description="Style overrides for further nested inner elements."
                    />
                  </PropertyList>
                </ExpandableSection>
              </Property>
            </PropertyList>
          </ExpandableSection>
        </Property>
      </PropertyList>
    </ExpandableSection>
  </Property>
  <Property
    name="optimizedFor"
    type="Breakpoint[]"
    description="Restrict this preset to specific breakpoints in the editor panel. If omitted, the preset appears at all breakpoints. Maximum 2 items."
  >
    <ExpandableSection name="Breakpoint values">
      <PropertyList>
        <Property name="'small'" description="The small (mobile) breakpoint." />
        <Property name="'large'" description="The large (desktop) breakpoint." />
      </PropertyList>
    </ExpandableSection>
  </Property>
  <Property
    name="presetCssUrl"
    type="string"
    required
    description="A URL to a CSS file that the editor applies when a Wix user selects this preset. Maximum 500 characters."
  />
  <Property
    name="presetDefaults"
    type="PresetElementDefaults"
    description="Default values that take effect when a Wix user selects this preset."
  >
    <ExpandableSection name="PresetElementDefaults properties">
      <PropertyList>
        <Property
          name="displayName"
          type="string"
          description="The element display name when this preset is selected. Maximum 100 characters. Translatable."
        />
        <Property
          name="cssProperties"
          type="map<string, CssPropertyItemDefaults>"
          description="Default values for element CSS properties when this preset is selected. Each value is an object with a defaultValue field."
        />
        <Property
          name="cssCustomProperties"
          type="map<string, CssPropertyItemDefaults>"
          description="Default values for element CSS custom properties when this preset is selected. Each value is an object with a defaultValue field."
        />
        <Property
          name="elements"
          type="map<string, PresetInnerElementDefaults>"
          description="Default styles for inner elements when this preset is selected."
        >
          <ExpandableSection name="PresetInnerElementDefaults properties">
            Sets default values for nested elements in a preset. This schema is recursive, so each inner element can contain its own nested `elements`.

            <PropertyList>
              <Property
                name="cssProperties"
                type="map<string, CssPropertyItemDefaults>"
                description="Default values for this inner element's CSS properties. Each value is an object with a defaultValue field."
              />
              <Property
                name="cssCustomProperties"
                type="map<string, CssPropertyItemDefaults>"
                description="Default values for this inner element's CSS custom properties. Each value is an object with a defaultValue field."
              />
              <Property
                name="elements"
                type="map<string, PresetInnerElementDefaults>"
                description="Default values for further nested inner elements."
              />
            </PropertyList>
          </ExpandableSection>
        </Property>
        <Property
          name="layout"
          type={<><a href="fallback::https://dev.wix.com/docs/site-extensions/editor-react-components/editor-element/layout">EditorElementLayout</a></>}.md
          description="Layout behaviors to apply when this preset is selected."
        />
        <Property
          name="displayFilters"
          type={<><a href="fallback::https://dev.wix.com/docs/site-extensions/editor-react-components/editor-element/display-filters">DisplayFilters</a></>}.md
          description="Controls visibility of elements, properties, and actions for this preset."
        />
      </PropertyList>
    </ExpandableSection>
  </Property>
</PropertyList>

## Installation presets

The `installation.presets` object maps breakpoints to preset keys, controlling which preset the component starts with when first added to the page.

<PropertyList bordered>
  <Property
    name="large"
    type="string"
    description="The preset key to use at the large (desktop) breakpoint."
  />
  <Property
    name="small"
    type="string"
    description="The preset key to use at the small (mobile) breakpoint."
  />
</PropertyList>

## Examples

### Basic presets

The following defines 2 presets for a line component, 1 horizontal and 1 vertical, each with different initial sizes and layout defaults.

```typescript
editorElement: {
  presets: {
    horizontal: {
      displayName: 'Horizontal',
      initialSize: {
        width: {
          sizingType: 'pixels',
          pixels: 280,
        },
        height: {
          sizingType: 'content',
        },
      },
      presetDefaults: {
        layout: {
          resizeDirection: 'horizontal',
          contentResizeDirection: 'vertical',
          disableStretching: false,
          disablePositioning: false,
        },
      },
    },
    vertical: {
      displayName: 'Vertical',
      initialSize: {
        width: {
          sizingType: 'content',
        },
        height: {
          sizingType: 'pixels',
          pixels: 280,
        },
      },
      presetDefaults: {
        layout: {
          resizeDirection: 'vertical',
          contentResizeDirection: 'horizontal',
          disableStretching: false,
          disablePositioning: false,
        },
      },
    },
  },
}
```

### Preset element defaults

The following configures layout, CSS property defaults, and display filters for a menu preset. The `displayFilters` object controls which elements, actions, and properties appear in the editor for this preset. In this case, it shows the `navbar` element and hides the `manageMenu` action.

```typescript
editorElement: {
  presets: {
    menuPreset: {
      presetDefaults: {
        layout: {
          resizeDirection: 'horizontal',
          contentResizeDirection: 'horizontal',
          disableStretching: false,
          disablePositioning: false,
          disableRotation: true,
        },
        cssProperties: {
          writingMode: {
            defaultValue: 'horizontal-tb',
          },
        },
        displayFilters: {
          elements: {
            show: ['navbar'],
          },
          actions: {
            hide: ['manageMenu'],
          },
        },
      },
    },
  },
}
```

### Inner element defaults

The following configures CSS custom property defaults for a nested `line` element.

```typescript
editorElement: {
  presets: {
    myPreset: {
      presetDefaults: {
        elements: {
          line: {
            cssCustomProperties: {
              type: {
                defaultValue: 'solid',
              },
              lineColor: {
                defaultValue: '#000000',
              },
              lineSize: {
                defaultValue: '1px',
              },
            },
          },
        },
      },
    },
  },
}
```

### Component initial size

The following sets the initial width to 120 pixels and the height to fit the content.

```typescript
editorElement: {
  presets: {
    myPreset: {
      initialSize: {
        width: {
          sizingType: 'pixels',
          pixels: 120,
        },
        height: {
          sizingType: 'content',
        },
      },
    },
  },
}
```

### Installation presets

The following sets the horizontal preset for both breakpoints and defines a default initial width of 280 pixels.

```typescript
installation: {
  presets: {
    default: 'horizontal',
    small: 'horizontal',
  },
  initialSize: {
    width: {
      sizingType: 'pixels',
      pixels: 280,
    },
    height: {
      sizingType: 'content',
    },
  },
}
```

### Style overrides

The following overrides background color with state-specific hover values at the default breakpoint, and adjusts font size for mobile.

```typescript
editorElement: {
  presets: {
    myPreset: {
      styleOverrides: {
        default: {
          style: {
            backgroundColor: {
              value: '#ffffff',
              statesValues: {
                hover: '#f0f0f0',
              },
            },
            fontSize: {
              value: '16px',
            },
          },
          elements: {
            menuItem: {
              style: {
                padding: {
                  value: '12px 16px',
                },
              },
            },
          },
        },
        small: {
          style: {
            fontSize: {
              value: '14px',
            },
          },
          elements: {
            menuItem: {
              style: {
                padding: {
                  value: '8px 12px',
                },
              },
            },
          },
        },
      },
    },
  },
}
```