OPF

Search docs

Loading documentation…
    OpenPresentation/opf
    Browse docs
    On this page
    View source

    Shape Fill

    A shape block's fill: 'none', a ColorRef, { gradient } or { pattern }. Without a fill a shape takes its style's fill (the theme's accent1 for the default style). Fills rotate with the shape (rotWithShape).

    Metadata

    Definition
    #/$defs/ShapeFill
    Form
    4 inclusive forms (anyOf)
    Source
    spec/schemas/opf.schema.json

    Field index

    This definition uses the forms or value constraints below.

    anyOf 1 · const

    No fill (a:noFill).

    Exact constraints for anyOf 1
    anyOf 1 schema
    {
      "type": "string",
      "const": "none",
      "description": "No fill (a:noFill)."
    }

    anyOf 2 · ref:ColorRef

    A solid fill (a:solidFill): any ColorRef; eight-digit hex keeps its alpha.

    Referenced ColorRef · ref:HexColor | enum | string | ref:ColorTransform

    A color value or reference, enforced on shape fills and strokes, image strokes, styled table cell fill and text colors, cell border colors, solid background colors, gradient stop colors and pattern foreground and background colors. Four forms: - Literal hex: '#RGB', '#RRGGBB', or '#RRGGBBAA'. - Color-scheme name, resolved through the effective color scheme after design resolution: an OOXML slot ('accent1'-'accent6', 'dark1', 'dark2', 'light1', 'light2', 'hyperlink', 'followedHyperlink') or an abstract role ('primary', 'secondary', 'accent', 'background', 'surface', 'surfaceAlt', 'text', 'textSecondary'). Roles resolve through the same role-to-slot mapping engines already apply to color schemes. 'surfaceAlt' has no slot: it is the alternate surface of banded table rows, derived from 'surface' and 'text' (the surface mixed a tenth of the way towards the text color, further when needed, so it always differs visibly from 'surface' and keeps 4.5:1 text contrast; core surfaceAltColor). - Variable reference: 'var:<id>' into the top-level variables map. - Lighter or darker: { "color": <ColorRef>, "lighten": 0..1 } or { "color": <ColorRef>, "darken": 0..1 }, PowerPoint's "Lighter 40%" and "Darker 25%": the color's HSL luminance moved that share of the way to white (lighten) or to black (darken). Core resolves it (resolveColorRef); PPTX export writes the base color (a scheme color where it is one) with a:lumMod and a:lumOff. Names keep content theme-portable: re-theming the deck updates every named reference, where a literal hex stays frozen. Unknown 'var:' ids produce a validation warning, never an error, and engines fall back to their default text color. TextRun.color documents the same three forms but remains an open string so imported decks with unrecognized run colors stay valid; validators warn there instead of erroring.

    anyOf 1 · ref:HexColor

    Referenced HexColor · string

    Hex color shorthand accepted by selected string fields.

    Exact constraints for Referenced HexColor
    Referenced HexColor schema
    {
      "type": "string",
      "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$",
      "description": "Hex color shorthand accepted by selected string fields.",
      "examples": [
        "#fff",
        "#ffff00",
        "#0F172AFF"
      ]
    }
    Exact constraints for anyOf 1
    anyOf 1 schema
    {
      "$ref": "#/$defs/HexColor"
    }

    anyOf 2 · enum

    Exact constraints for anyOf 2
    anyOf 2 schema
    {
      "type": "string",
      "enum": [
        "accent1",
        "accent2",
        "accent3",
        "accent4",
        "accent5",
        "accent6",
        "dark1",
        "dark2",
        "light1",
        "light2",
        "hyperlink",
        "followedHyperlink",
        "primary",
        "secondary",
        "accent",
        "background",
        "surface",
        "surfaceAlt",
        "text",
        "textSecondary"
      ]
    }

    anyOf 3 · string

    Exact constraints for anyOf 3
    anyOf 3 schema
    {
      "type": "string",
      "pattern": "^var:[a-z][a-z0-9-]*$"
    }

    anyOf 4 · ref:ColorTransform

    Referenced ColorTransform · object | object

    A ColorRef made lighter or darker, as PowerPoint's theme color tints and shades: 'lighten' moves the color's HSL luminance that share of the way to white (lumMod 1 - lighten, lumOff lighten), 'darken' that share of the way to black (lumMod 1 - darken). Exactly one of the two. PPTX export writes a:lumMod and a:lumOff on the base color, a scheme color where the base names one, so re-theming the deck keeps the tint.

    FieldTypeReq.DefaultDescription
    colorref:ColorRefyes—The base color: any ColorRef.
    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"
    lightennumber——Share of the way to white, 0 to 1. 0.4 is PowerPoint's "Lighter 40%".
    darkennumber——Share of the way to black, 0 to 1. 0.25 is PowerPoint's "Darker 25%".

    color

    typeref:ColorRefrequiredyesdefault—

    The base color: any ColorRef.

    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"

    lighten

    typenumberrequirednodefault—

    Share of the way to white, 0 to 1. 0.4 is PowerPoint's "Lighter 40%".

    darken

    typenumberrequirednodefault—

    Share of the way to black, 0 to 1. 0.25 is PowerPoint's "Darker 25%".

    oneOf 1 · object

    Exact constraints for oneOf 1
    oneOf 1 schema
    {
      "required": [
        "lighten"
      ]
    }

    oneOf 2 · object

    Exact constraints for oneOf 2
    oneOf 2 schema
    {
      "required": [
        "darken"
      ]
    }
    Exact constraints for Referenced ColorTransform
    Referenced ColorTransform schema
    {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "color"
      ],
      "description": "A ColorRef made lighter or darker, as PowerPoint's theme color tints and shades: 'lighten' moves the color's HSL luminance that share of the way to white (lumMod 1 - lighten, lumOff lighten), 'darken' that share of the way to black (lumMod 1 - darken). Exactly one of the two. PPTX export writes a:lumMod and a:lumOff on the base color, a scheme color where the base names one, so re-theming the deck keeps the tint.",
      "properties": {
        "color": {
          "$ref": "#/$defs/ColorRef",
          "description": "The base color: any ColorRef."
        },
        "lighten": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "Share of the way to white, 0 to 1. 0.4 is PowerPoint's \"Lighter 40%\"."
        },
        "darken": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "Share of the way to black, 0 to 1. 0.25 is PowerPoint's \"Darker 25%\"."
        }
      },
      "oneOf": [
        {
          "required": [
            "lighten"
          ]
        },
        {
          "required": [
            "darken"
          ]
        }
      ],
      "examples": [
        {
          "color": "accent1",
          "lighten": 0.4
        },
        {
          "color": "#0F4C81",
          "darken": 0.25
        }
      ]
    }
    Exact constraints for anyOf 4
    anyOf 4 schema
    {
      "$ref": "#/$defs/ColorTransform"
    }
    Exact constraints for Referenced ColorRef
    Referenced ColorRef schema
    {
      "anyOf": [
        {
          "$ref": "#/$defs/HexColor"
        },
        {
          "type": "string",
          "enum": [
            "accent1",
            "accent2",
            "accent3",
            "accent4",
            "accent5",
            "accent6",
            "dark1",
            "dark2",
            "light1",
            "light2",
            "hyperlink",
            "followedHyperlink",
            "primary",
            "secondary",
            "accent",
            "background",
            "surface",
            "surfaceAlt",
            "text",
            "textSecondary"
          ]
        },
        {
          "type": "string",
          "pattern": "^var:[a-z][a-z0-9-]*$"
        },
        {
          "$ref": "#/$defs/ColorTransform"
        }
      ],
      "description": "A color value or reference, enforced on shape fills and strokes, image strokes, styled table cell fill and text colors, cell border colors, solid background colors, gradient stop colors and pattern foreground and background colors. Four forms:\n- Literal hex: '#RGB', '#RRGGBB', or '#RRGGBBAA'.\n- Color-scheme name, resolved through the effective color scheme after design resolution: an OOXML slot ('accent1'-'accent6', 'dark1', 'dark2', 'light1', 'light2', 'hyperlink', 'followedHyperlink') or an abstract role ('primary', 'secondary', 'accent', 'background', 'surface', 'surfaceAlt', 'text', 'textSecondary'). Roles resolve through the same role-to-slot mapping engines already apply to color schemes. 'surfaceAlt' has no slot: it is the alternate surface of banded table rows, derived from 'surface' and 'text' (the surface mixed a tenth of the way towards the text color, further when needed, so it always differs visibly from 'surface' and keeps 4.5:1 text contrast; core surfaceAltColor).\n- Variable reference: 'var:<id>' into the top-level variables map.\n- Lighter or darker: { \"color\": <ColorRef>, \"lighten\": 0..1 } or { \"color\": <ColorRef>, \"darken\": 0..1 }, PowerPoint's \"Lighter 40%\" and \"Darker 25%\": the color's HSL luminance moved that share of the way to white (lighten) or to black (darken). Core resolves it (resolveColorRef); PPTX export writes the base color (a scheme color where it is one) with a:lumMod and a:lumOff.\n\nNames keep content theme-portable: re-theming the deck updates every named reference, where a literal hex stays frozen. Unknown 'var:' ids produce a validation warning, never an error, and engines fall back to their default text color. TextRun.color documents the same three forms but remains an open string so imported decks with unrecognized run colors stay valid; validators warn there instead of erroring.",
      "examples": [
        "#0F4C81",
        "accent2",
        "text",
        "var:risk",
        {
          "color": "accent1",
          "lighten": 0.4
        },
        {
          "color": "text",
          "darken": 0.25
        }
      ]
    }
    Exact constraints for anyOf 2
    anyOf 2 schema
    {
      "$ref": "#/$defs/ColorRef",
      "description": "A solid fill (a:solidFill): any ColorRef; eight-digit hex keeps its alpha."
    }

    anyOf 3 · object

    A gradient fill (a:gradFill).

    FieldTypeReq.DefaultDescription
    gradientref:Gradientyes—

    gradient

    typeref:Gradientrequiredyesdefault—

    Named choices are not exhaustive. See the schema for other values and constraints.
    gradient.type · Allowed values
    "linear", "radial", "rectangle", "shape"
    gradient.stops[].color, gradient.stops[].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"
    Exact constraints for anyOf 3
    anyOf 3 schema
    {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "gradient"
      ],
      "properties": {
        "gradient": {
          "$ref": "#/$defs/Gradient"
        }
      },
      "description": "A gradient fill (a:gradFill)."
    }

    anyOf 4 · object

    A pattern fill (a:pattFill).

    FieldTypeReq.DefaultDescription
    patternref:Patternyes—

    pattern

    typeref:Patternrequiredyesdefault—

    Named choices are not exhaustive. See the schema for other values and constraints.
    pattern.foregroundColor, pattern.foregroundColor (anyOf 4).color, pattern.backgroundColor · Named choices
    "accent1", "accent2", "accent3", "accent4", "accent5", "accent6", "dark1", "dark2", "light1", "light2", "hyperlink", "followedHyperlink", "primary", "secondary", "accent", "background", "surface", "surfaceAlt", "text", "textSecondary"
    Exact constraints for anyOf 4
    anyOf 4 schema
    {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "pattern"
      ],
      "properties": {
        "pattern": {
          "$ref": "#/$defs/Pattern"
        }
      },
      "description": "A pattern fill (a:pattFill)."
    }
    Complete definition constraints
    Schema constraints
    {
      "anyOf": [
        {
          "type": "string",
          "const": "none",
          "description": "No fill (a:noFill)."
        },
        {
          "$ref": "#/$defs/ColorRef",
          "description": "A solid fill (a:solidFill): any ColorRef; eight-digit hex keeps its alpha."
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "gradient"
          ],
          "properties": {
            "gradient": {
              "$ref": "#/$defs/Gradient"
            }
          },
          "description": "A gradient fill (a:gradFill)."
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "pattern"
          ],
          "properties": {
            "pattern": {
              "$ref": "#/$defs/Pattern"
            }
          },
          "description": "A pattern fill (a:pattFill)."
        }
      ],
      "description": "A shape block's fill: 'none', a ColorRef, { gradient } or { pattern }. Without a fill a shape takes its style's fill (the theme's accent1 for the default style). Fills rotate with the shape (rotWithShape).",
      "examples": [
        "accent2",
        "none",
        {
          "color": "accent1",
          "lighten": 0.6
        },
        {
          "gradient": {
            "type": "radial",
            "stops": [
              {
                "color": "light1",
                "position": 0
              },
              {
                "color": "accent1",
                "position": 1
              }
            ]
          }
        },
        {
          "pattern": {
            "preset": "ltUpDiag",
            "foregroundColor": "accent1"
          }
        }
      ]
    }
    value · Named choices (see schema for other values and constraints)
    "none""accent1""accent2""accent3""accent4""accent5""accent6""dark1""dark2""light1""light2""hyperlink""followedHyperlink""primary""secondary""accent""background""surface""surfaceAlt""text""textSecondary"