OPF
OpenPresentation/opf
SpecDefinition referenceView source

Image Background

Picture background: the image fills the whole canvas behind everything and never moves content (to push content aside, use an image block with placement). The string shorthand 'asset:x' (or any image source) is { type: 'image', src: 'asset:x' }, a cover image. Paint order: the colour scheme's default slide background, the picture, then the overlay, then furniture and content.

Metadata

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

Field index

FieldTypeReq.Description
toneenum—Whether the background is dark or light, which picks the color map (dark1 or light1) so text, lines and neutrals read on it. Without a tone a picture or gradient takes the deck's variant, else counts as light.
tone · Allowed values
"dark""light"
typeconstyesPicture background.
type · Allowed values
"image"
srcstringyesSource for the background image: an 'asset:<id>' reference, HTTPS URL, data URI, or a relative path resolved against the OPF file location.
altstring—Alternative text. A background with alt is meaningful: PowerPoint export draws it as a full-slide picture at the back that carries the text, so screen readers see it. Without alt it is decorative and exports as the native slide background; the alt text of a referenced asset does not count, so a background is decorative unless it says otherwise.
fitenum—How the picture fills the canvas: 'cover' fills it and crops what overflows around focus; 'contain' shows the whole picture centered over the colour scheme's default background; 'stretch' scales it to the canvas exactly; 'tile' repeats it at its own size from the top-left corner. Default 'cover'.
fit · Allowed values
"cover""contain""stretch""tile"
focusref:ImageFocus—Point of the picture to keep in view when 'cover' crops it. Ignored by the other fits.
opacitynumber—Picture opacity from 0 (fully transparent) to 1 (fully opaque); the overlay keeps its own opacity. Default 1.
recolorref:ImageRecolor—Grayscale or duotone treatment of the picture's pixels, as on an image block: recolor and opacity apply to the pixels, then the overlay is drawn above.
recolor · Named choices (see schema for other values and constraints)
"grayscale"
overlayref:Overlay—Scrim over the whole picture or a band along one edge (edge, size), beneath furniture and content, for example to keep a title readable over a busy photo.

tone

typeenumrequirednodefault—

Whether the background is dark or light, which picks the color map (dark1 or light1) so text, lines and neutrals read on it. Without a tone a picture or gradient takes the deck's variant, else counts as light.

tone · Allowed values
"dark""light"
tone.json
{
  "tone": "dark"
}

type

typeconstrequiredyesdefault—

Picture background.

type · Allowed values
"image"
type.json
{
  "type": "image"
}

src

typestringrequiredyesdefault—

Source for the background image: an 'asset:<id>' reference, HTTPS URL, data URI, or a relative path resolved against the OPF file location.

src.json
{
  "src": "https://cdn.acme.com/backgrounds/cover.jpg"
}

alt

typestringrequirednodefault—

Alternative text. A background with alt is meaningful: PowerPoint export draws it as a full-slide picture at the back that carries the text, so screen readers see it. Without alt it is decorative and exports as the native slide background; the alt text of a referenced asset does not count, so a background is decorative unless it says otherwise.

fit

typeenumrequirednodefault—

How the picture fills the canvas: 'cover' fills it and crops what overflows around focus; 'contain' shows the whole picture centered over the colour scheme's default background; 'stretch' scales it to the canvas exactly; 'tile' repeats it at its own size from the top-left corner. Default 'cover'.

fit · Allowed values
"cover""contain""stretch""tile"
fit.json
{
  "fit": "cover"
}

focus

typeref:ImageFocusrequirednodefault—

Point of the picture to keep in view when 'cover' crops it. Ignored by the other fits.

opacity

typenumberrequirednodefault—

Picture opacity from 0 (fully transparent) to 1 (fully opaque); the overlay keeps its own opacity. Default 1.

recolor

typeref:ImageRecolorrequirednodefault—

Grayscale or duotone treatment of the picture's pixels, as on an image block: recolor and opacity apply to the pixels, then the overlay is drawn above.

recolor · Named choices (see schema for other values and constraints)
"grayscale"
recolor (oneOf 2).dark · 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"
recolor (oneOf 2).light · 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"

overlay

typeref:Overlayrequirednodefault—

Scrim over the whole picture or a band along one edge (edge, size), beneath furniture and content, for example to keep a title readable over a busy photo.

overlay.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"
overlay.edge · Allowed values
"top""bottom""left""right"
Complete definition constraints
Schema constraints
{
  "type": "object",
  "additionalProperties": false,
  "description": "Picture background: the image fills the whole canvas behind everything and never moves content (to push content aside, use an image block with placement). The string shorthand 'asset:x' (or any image source) is { type: 'image', src: 'asset:x' }, a cover image. Paint order: the colour scheme's default slide background, the picture, then the overlay, then furniture and content.",
  "required": [
    "type",
    "src"
  ],
  "properties": {
    "tone": {
      "type": "string",
      "enum": [
        "dark",
        "light"
      ],
      "description": "Whether the background is dark or light, which picks the color map (dark1 or light1) so text, lines and neutrals read on it. Without a tone a picture or gradient takes the deck's variant, else counts as light."
    },
    "type": {
      "type": "string",
      "const": "image",
      "description": "Picture background."
    },
    "src": {
      "type": "string",
      "description": "Source for the background image: an 'asset:<id>' reference, HTTPS URL, data URI, or a relative path resolved against the OPF file location.",
      "examples": [
        "https://cdn.acme.com/backgrounds/cover.jpg",
        "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAA...",
        "./backgrounds/cover.jpg",
        "asset:bg-cover"
      ]
    },
    "alt": {
      "type": "string",
      "description": "Alternative text. A background with alt is meaningful: PowerPoint export draws it as a full-slide picture at the back that carries the text, so screen readers see it. Without alt it is decorative and exports as the native slide background; the alt text of a referenced asset does not count, so a background is decorative unless it says otherwise."
    },
    "fit": {
      "type": "string",
      "enum": [
        "cover",
        "contain",
        "stretch",
        "tile"
      ],
      "description": "How the picture fills the canvas: 'cover' fills it and crops what overflows around focus; 'contain' shows the whole picture centered over the colour scheme's default background; 'stretch' scales it to the canvas exactly; 'tile' repeats it at its own size from the top-left corner. Default 'cover'."
    },
    "focus": {
      "$ref": "#/$defs/ImageFocus",
      "description": "Point of the picture to keep in view when 'cover' crops it. Ignored by the other fits."
    },
    "opacity": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "description": "Picture opacity from 0 (fully transparent) to 1 (fully opaque); the overlay keeps its own opacity. Default 1."
    },
    "recolor": {
      "$ref": "#/$defs/ImageRecolor",
      "description": "Grayscale or duotone treatment of the picture's pixels, as on an image block: recolor and opacity apply to the pixels, then the overlay is drawn above."
    },
    "overlay": {
      "$ref": "#/$defs/Overlay",
      "description": "Scrim over the whole picture or a band along one edge (edge, size), beneath furniture and content, for example to keep a title readable over a busy photo."
    }
  },
  "examples": [
    {
      "type": "image",
      "src": "asset:cover-photo"
    },
    {
      "type": "image",
      "src": "./images/harbour.jpg",
      "alt": "Container ships at dawn",
      "focus": {
        "x": 0.5,
        "y": 0.7
      },
      "overlay": {
        "color": "dark1",
        "opacity": 0.4
      }
    }
  ]
}