Base Panel Configuration¶

All panel types used within a dashboard (e.g., Markdown, Lens charts, Search panels) share a common set of base configuration fields. These fields define fundamental properties like the panel's title, its position and size on the dashboard grid, and an optional description.

When defining a panel in your YAML, you must specify the configuration block for that specific panel type (e.g., markdown, lens) which serves as the key to identify the panel type.

A Poem for the Dashboard Builders¶

For those who lay the foundation for every panel:

Every panel needs a base:
A title, grid, and proper place.
From x and y, the starting spot,
To width and height—you plot the plot.

The id is yours, or auto-made,
Descriptions help when things must be weighed.
hide_title when you'd rather not—
The base provides what others forgot.

Whether metric, pie, or chart XY,
Markdown prose or links nearby,
They all inherit from this floor:
The BasePanel, forevermore.

So here's to grids that organize,
To coordinates that plot the prize.
The humble base, unsexy but true—
No panel works without you.

Minimal Example (Illustrating Base Fields within a Specific Panel Type)¶

This example shows how base panel fields are used within a markdown panel:

dashboards:
- name: "Example Dashboard"
  panels:
    - markdown:
        content: "System is **operational**." # MarkdownPanel specific config
      title: "Status Overview"
      description: "A quick look at system status." # BasePanel field
      hide_title: false                             # BasePanel field
      size:                                         # BasePanel field (recommended)
        w: quarter  # or numeric value like 12
        h: 8
      position:                                     # BasePanel field (optional)
        x: 0
        y: 0

Note: See Auto-Layout Guide for details on automatic panel positioning.

Full Configuration Options¶

Base Panel Fields¶

These fields are available for all panel types and are inherited from the BasePanel configuration.

YAML Key	Data Type	Description	Kibana Default	Required
`id`	`string`	A unique identifier for the panel. If not provided, one may be generated during compilation.	Generated ID	No
`title`	`string`	The title displayed on the panel header. Can be an empty string if you wish for no visible title.	`""` (empty string)	No
`hide_title`	`boolean`	If `true`, the panel title (even if defined) will be hidden.	`false` (title is shown)	No
`description`	`string`	A brief description of the panel's content or purpose. This is often shown on hover or in panel information.	`""` (empty string, if `None`)	No
`size`	`Size` object	Defines the panel's width and height. See Size Object Configuration below.	`w: 12, h: 8`	No
`position`	`Position` object	Optional: Defines the panel's x/y coordinates. Omit for automatic positioning. See Position Object Configuration below.	Auto-calculated	No
`drilldowns`	`list[Drilldown]`	Optional: List of drilldowns for interactive navigation. See Drilldowns Configuration.	`None`	No

Note on Panel Types: Each panel must have exactly one key identifying its type (e.g., markdown, lens, search, links, image, esql). This key contains the type-specific configuration.

Note on Auto-Layout: For automatic panel positioning without manual coordinate calculation, use the size field and omit the position field. See the Auto-Layout Guide for details.

Size Object Configuration (`size`)¶

The size object defines the panel's width and height on the dashboard grid. This is the recommended approach for new dashboards.

Both shorthand and verbose parameter names are supported for improved readability.

YAML Key	Verbose Alternative	Data Type	Description	Default	Required
`w`	`width`	`integer` or `SemanticWidth`	The width of the panel. Accepts semantic values (`whole`, `half`, `third`, `quarter`, `sixth`, `eighth`) or numeric values (1-48).	`12` (quarter)	No
`h`	`height`	`integer`	The height of the panel in grid units.	`8`	No

Semantic Width Values:

Value	Grid Units	Description
`whole`	48	Full dashboard width
`half`	24	Half width
`third`	16	One-third width
`quarter`	12	Quarter width
`sixth`	8	One-sixth width
`eighth`	6	One-eighth width

Example:

size:
  w: quarter  # Semantic value
  h: 8

# Or with numeric value:
size:
  width: 24   # Numeric value
  height: 12

Position Object Configuration (`position`)¶

The position object defines the panel's x/y coordinates on the dashboard grid. This field is optional - when omitted, the panel will be automatically positioned using the dashboard's layout algorithm.

YAML Key	Verbose Alternative	Data Type	Description	Default	Required
`x`	`from_left`	`integer` or `None`	The horizontal starting position (0-based, 0-48). If `None`, position is auto-calculated.	`None`	No
`y`	`from_top`	`integer` or `None`	The vertical starting position (0-based). If `None`, position is auto-calculated.	`None`	No

Example with fixed position:

position:
  x: 0
  y: 0

# Or verbose:
position:
  from_left: 24
  from_top: 10

Example with auto-positioning (omit position entirely):

# No position field - will be auto-positioned
size:
  w: quarter
  h: 8

Panel Types (Specific Configurations)¶

The BasePanel fields are common to all panel types. For details on the specific configuration fields available for each panel type, refer to their individual documentation pages:

Color Mapping Configuration¶

Quick Reference: Want to customize chart colors? See Color Mapping Examples below for palette selection, or the Custom Color Assignments guide for manual color assignments.

Many chart panel types (Pie, XY, Metric) support color customization through the color field. You can select from built-in color palettes or manually assign specific colors to data values.

ColorValueMapping Object¶

Categorical color mapping for charts keyed by exact values.

Attributes:

Name	Type	Description
`palette`	`str`	The palette ID to use for unassigned colors. Available palettes: - 'default' - Standard EUI palette - 'eui_amsterdam_color_blind' - Color-blind safe palette (default) - 'kibana_palette' or 'legacy' - Legacy Kibana colors - 'elastic_brand' - Elastic brand colors - 'gray' - Grayscale palette
`assignments`	`list[ColorValueAssignment]`	Manual color assignments to specific data values.

Show JSON schema:

{
  "$defs": {
    "ColorValueAssignment": {
      "additionalProperties": false,
      "description": "Manual color assignment to specific categorical values.",
      "properties": {
        "value": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "A single category value to assign a color to.",
          "title": "Value"
        },
        "values": {
          "anyOf": [
            {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Multiple category values to assign the same color to.",
          "title": "Values"
        },
        "color": {
          "description": "The hex color code to assign (e.g., '#FF0000').",
          "title": "Color",
          "type": "string"
        }
      },
      "required": [
        "color"
      ],
      "title": "ColorValueAssignment",
      "type": "object"
    }
  },
  "additionalProperties": false,
  "description": "Categorical color mapping for charts keyed by exact values.",
  "properties": {
    "palette": {
      "default": "eui_amsterdam_color_blind",
      "description": "The palette ID to use for unassigned colors.\n\nAvailable palettes:\n- 'default' - Standard EUI palette\n- 'eui_amsterdam_color_blind' - Color-blind safe palette (default)\n- 'kibana_palette' or 'legacy' - Legacy Kibana colors\n- 'elastic_brand' - Elastic brand colors\n- 'gray' - Grayscale palette",
      "title": "Palette",
      "type": "string"
    },
    "assignments": {
      "description": "Manual color assignments to specific data values.",
      "items": {
        "$ref": "#/$defs/ColorValueAssignment"
      },
      "title": "Assignments",
      "type": "array"
    }
  },
  "title": "ColorValueMapping",
  "type": "object"
}

ColorValueAssignment Object¶

Manual color assignments are an advanced feature. For an introduction and examples, see the Custom Color Assignments guide.

Manual color assignment to specific categorical values.

Attributes:

Name	Type	Description
`value`	`str \| None`	A single category value to assign a color to.
`values`	`list[str] \| None`	Multiple category values to assign the same color to.
`color`	`str`	The hex color code to assign (e.g., '#FF0000').

Show JSON schema:

{
  "additionalProperties": false,
  "description": "Manual color assignment to specific categorical values.",
  "properties": {
    "value": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "A single category value to assign a color to.",
      "title": "Value"
    },
    "values": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Multiple category values to assign the same color to.",
      "title": "Values"
    },
    "color": {
      "description": "The hex color code to assign (e.g., '#FF0000').",
      "title": "Color",
      "type": "string"
    }
  },
  "required": [
    "color"
  ],
  "title": "ColorValueAssignment",
  "type": "object"
}

Validators:

check_value_or_values

check_value_or_values `pydantic-validator` ¶

check_value_or_values()

Validate that at least one of value or values is provided.

ColorRangeMapping Object¶

Range-based color mapping is used for threshold-oriented visualizations (for example, gauge palettes). Use this with the gauge chart color field.

Range/threshold-based color mapping for numeric values.

Attributes:

Name	Type	Description
`range_type`	`Literal['number', 'percent']`	How threshold values are interpreted by Kibana.
`range_min`	`float \| None`	Optional lower bound for the palette domain. Use null for auto/open lower bound.
`range_max`	`float \| None`	Optional upper bound for the palette domain. Use null for auto/open upper bound.
`thresholds`	`list[ColorThreshold]`	Ordered threshold bands used to build gauge-style color palettes.

Show JSON schema:

{
  "$defs": {
    "ColorThreshold": {
      "additionalProperties": false,
      "description": "Single threshold band in a range-based color map.",
      "properties": {
        "up_to": {
          "description": "Upper bound for this threshold band.",
          "title": "Up To",
          "type": "number"
        },
        "color": {
          "description": "The color applied within this threshold band (hex color code).",
          "title": "Color",
          "type": "string"
        }
      },
      "required": [
        "up_to",
        "color"
      ],
      "title": "ColorThreshold",
      "type": "object"
    }
  },
  "additionalProperties": false,
  "description": "Range/threshold-based color mapping for numeric values.",
  "properties": {
    "range_type": {
      "default": "number",
      "description": "How threshold values are interpreted by Kibana.",
      "enum": [
        "number",
        "percent"
      ],
      "title": "Range Type",
      "type": "string"
    },
    "range_min": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": 0,
      "description": "Optional lower bound for the palette domain. Use null for auto/open lower bound.",
      "title": "Range Min"
    },
    "range_max": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional upper bound for the palette domain. Use null for auto/open upper bound.",
      "title": "Range Max"
    },
    "thresholds": {
      "description": "Ordered threshold bands used to build gauge-style color palettes.",
      "items": {
        "$ref": "#/$defs/ColorThreshold"
      },
      "minItems": 1,
      "title": "Thresholds",
      "type": "array"
    }
  },
  "required": [
    "thresholds"
  ],
  "title": "ColorRangeMapping",
  "type": "object"
}

Validators:

validate_thresholds

validate_thresholds `pydantic-validator` ¶

validate_thresholds()

Validate threshold ordering and percent bounds.

Color Mapping Examples¶

Example 1: Using a Different Palette¶

dashboards:
  - name: "Sales Dashboard"
    panels:
      - title: "Revenue by Region"
        size: { w: 6, h: 6 }
        lens:
          type: pie
          data_view: "logs-*"
          breakdowns:
            - field: "region"
              type: values
          metrics:
            - aggregation: sum
              field: revenue
          color:
            palette: 'elastic_brand'  # Use Elastic brand colors

Example 2: Manual Color Assignments (Advanced)¶

For a detailed introduction to color assignments, see the Custom Color Assignments guide.

dashboards:
  - name: "Status Monitoring"
    panels:
      - title: "Request Status Distribution"
        size: { w: 6, h: 6 }
        lens:
          type: pie
          data_view: "logs-*"
          breakdowns:
            - field: "http.response.status_code"
              type: values
          metrics:
            - aggregation: count
          color:
            palette: 'eui_amsterdam_color_blind'
            assignments:
              - values: ['200', '201', '204']
                color: '#00BF6F'  # Green for success
              - values: ['404']
                color: '#FFA500'  # Orange for not found
              - values: ['500', '502', '503']
                color: '#BD271E'  # Red for errors

Dashboard Configuration

Base Panel Configuration¶

A Poem for the Dashboard Builders¶

Minimal Example (Illustrating Base Fields within a Specific Panel Type)¶

Full Configuration Options¶

Base Panel Fields¶

Size Object Configuration (size)¶

Position Object Configuration (position)¶

Panel Types (Specific Configurations)¶

Color Mapping Configuration¶

ColorValueMapping Object¶

ColorValueAssignment Object¶

check_value_or_values pydantic-validator ¶

ColorRangeMapping Object¶

validate_thresholds pydantic-validator ¶

Color Mapping Examples¶

Example 1: Using a Different Palette¶

Example 2: Manual Color Assignments (Advanced)¶

Related Documentation¶

Size Object Configuration (`size`)¶

Position Object Configuration (`position`)¶

check_value_or_values `pydantic-validator` ¶

validate_thresholds `pydantic-validator` ¶