OPF
SpecDefinition referenceView source

Overlay

Solid scrim over a picture: the whole frame in the frame's shape, or a band along one edge. Shared by image backgrounds and image blocks. Drawn directly above its picture and beneath headings and content; PowerPoint export writes one native shape above the picture.

Metadata

Definition
#/$defs/Overlay
Form
object
Source
spec/schemas/opf.schema.json

Field index

FieldTypeReq.Description
colorref:ColorRefyesOverlay fill color: a hex color (eight-digit hex keeps its alpha), a color-scheme slot or role name, or a 'var:<id>' variable reference.
color · Named choices (see schema for other values and constraints)
"accent1""accent2""accent3""accent4""accent5""accent6""dark1""dark2""light1""light2""hyperlink""followedHyperlink""primary""secondary""accent""background""surface""surfaceAlt""text""textSecondary"
opacitynumberyesOverlay fill opacity.
edgeenum—Cover only a band along this edge of the frame, for example a caption strip. Backgrounds and rectangle image frames only; on another shape the overlay is not drawn and composition reports unsupported-image-treatment. Omit to cover the whole frame. In a right-to-left deck 'left' and 'right' are the start and end sides.
edge · Allowed values
"top""bottom""left""right"
sizenumber—Band share of the frame for an edge overlay. Default 0.3. Ignored without edge.

color

typeref:ColorRefrequiredyesdefault—

Overlay fill color: a hex color (eight-digit hex keeps its alpha), a color-scheme slot or role name, or a 'var:<id>' variable reference.

Named choices are not exhaustive. See the schema for other values and constraints.
color, color (anyOf 4).color · Named choices
"accent1", "accent2", "accent3", "accent4", "accent5", "accent6", "dark1", "dark2", "light1", "light2", "hyperlink", "followedHyperlink", "primary", "secondary", "accent", "background", "surface", "surfaceAlt", "text", "textSecondary"

opacity

typenumberrequiredyesdefault—

Overlay fill opacity.

edge

typeenumrequirednodefault—

Cover only a band along this edge of the frame, for example a caption strip. Backgrounds and rectangle image frames only; on another shape the overlay is not drawn and composition reports unsupported-image-treatment. Omit to cover the whole frame. In a right-to-left deck 'left' and 'right' are the start and end sides.

edge · Allowed values
"top""bottom""left""right"
edge.json
{
  "edge": "top"
}

size

typenumberrequirednodefault—

Band share of the frame for an edge overlay. Default 0.3. Ignored without edge.

Complete definition constraints
Schema constraints
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "color",
    "opacity"
  ],
  "description": "Solid scrim over a picture: the whole frame in the frame's shape, or a band along one edge. Shared by image backgrounds and image blocks. Drawn directly above its picture and beneath headings and content; PowerPoint export writes one native shape above the picture.",
  "properties": {
    "color": {
      "$ref": "#/$defs/ColorRef",
      "description": "Overlay fill color: a hex color (eight-digit hex keeps its alpha), a color-scheme slot or role name, or a 'var:<id>' variable reference."
    },
    "opacity": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "description": "Overlay fill opacity."
    },
    "edge": {
      "type": "string",
      "enum": [
        "top",
        "bottom",
        "left",
        "right"
      ],
      "description": "Cover only a band along this edge of the frame, for example a caption strip. Backgrounds and rectangle image frames only; on another shape the overlay is not drawn and composition reports unsupported-image-treatment. Omit to cover the whole frame. In a right-to-left deck 'left' and 'right' are the start and end sides."
    },
    "size": {
      "type": "number",
      "minimum": 0.05,
      "maximum": 1,
      "description": "Band share of the frame for an edge overlay. Default 0.3. Ignored without edge."
    }
  },
  "examples": [
    {
      "color": "dark1",
      "opacity": 0.4
    },
    {
      "color": "#000000",
      "opacity": 0.75,
      "edge": "bottom",
      "size": 0.25
    }
  ]
}