<zg-caption>

Interactive Storybook Playground

The <zg-caption> tag is a web component that controls the styling and display of the grid's caption (title).

Image of the DOM relationship for the zg-caption web component tag

Related Web Components

Usage

A <zg-caption> tag can be manually inserted inside the grid as slotted content or automatically inserted when the caption is enabled via the caption attribute. The caption is styleable via CSS variables or the zg-caption CSS selector.

You can use the caption attribute, like so:

<zing-grid caption="Hello World"></zing-grid>

You can slot the <zg-caption> tag as well:

<zing-grid>
  <zg-caption>Hello World</zg-caption>
</zing-grid>
Top

Attributes

There are a couple attributes to help position the <zg-caption> element in the grid and align the text within the <zg-caption>.

Example Usage

<zing-grid
  src="https://cdn.zinggrid.com/datasets/user-roles.json">
  <zg-caption align="center" position="both">Hello World</zg-caption>
</zing-grid>

align

String

Description

The alignment of content in the caption

Default Value

"start"

Accepted Values

  • "start"
  • "left"
  • "right"
  • "center"
Demo

position

String

Description

Indicates where to position the caption

Default Value

"top"

Accepted Values

  • "top"
  • "bottom"
  • "both"
Demo
Top

CSS Variables

<zg-caption> can be styled by CSS variables, like so:

:root {
  --zg-caption-background: red;
}

Below is a list of all the associated --zg-caption CSS variables. Check out the full list of CSS variables or our Styling Basics guide to learn more about styling the grid.

ZGCaption CSS Variables and Default Values
Name Default Description Demo CSS Ref
--zg-caption-align-items center Sets the vertical alignment of items (title and toolbar) in caption
--zg-caption-background Browser's default value Styles the background of caption
--zg-caption-border 0 Styles the border of caption
--zg-caption-border-bottom var(--zg-caption-border, 0) Styles the bottom border of caption
--zg-caption-border-left var(--zg-caption-border, 0) Styles the left border of caption
--zg-caption-border-radius 0 Applies a border-radius to the caption
--zg-caption-border-right var(--zg-caption-border, 0) Styles the right border of caption
--zg-caption-border-top var(--zg-caption-border, 0) Styles the top border of caption
--zg-caption-box-shadow none Applies a box shadow behind caption
--zg-caption-button-background var(--zg-button-background) Styles the background of button in caption
--zg-caption-button-background_active var(--zg-caption-button-background, var(--zg-button-background)) Styles the background of button in caption when the button is in an `active` state
--zg-caption-button-background_focus var(--zg-caption-button-background, var(--zg-button-background)) Styles the background of button in caption when the button is in a `focus` state
--zg-caption-button-background_hover var(--zg-caption-button-background, var(--zg-button-background)) Styles the background of button in caption when the button is in a `hover` state
--zg-caption-color Browser's default value Sets the font color of caption
--zg-caption-flex-direction row Sets the flex direction of items (title and toolbar) in caption
--zg-caption-font-family Browser's default value Sets the font family of caption
--zg-caption-font-size 1.25rem Sets the font size of caption
--zg-caption-font-style Browser's default value Sets the font style of caption
--zg-caption-font-weight Browser's default value Sets the font weight of caption
--zg-caption-height Browser's default value Sets the height of caption
--zg-caption-margin 0 Sets the margin of caption
--zg-caption-opacity Browser's default value Sets the opacity of caption
--zg-caption-padding 0 var(--theme-padding_x) Sets the padding of caption
--zg-caption-title-align-self center Sets vertical alignment of items in caption title
--zg-caption-title-flex 0 1 auto Sets how items are flexed in caption title
--zg-caption-title-font-family inherit Sets the font-family of caption title
--zg-caption-title-font-size inherit Sets the font size of caption title
--zg-caption-title-font-style inherit Sets the font style of caption title
--zg-caption-title-font-weight inherit Sets the font weight of caption title
--zg-caption-title-margin 0 Sets the margin of caption title
--zg-caption-title-order Browser's default value Sets the order of caption title with respect to caption toolbar
--zg-caption-title-padding 0 Sets the padding of caption title
--zg-caption-title-text-align inherit Sets the text alignment of caption title
--zg-caption-title-transform none Sets the transform of caption title
--zg-caption-title-width 100% Sets the width of caption title
--zg-caption-toolbar-align-self Browser's default value Sets vertical alignment of items in caption toolbar
--zg-caption-toolbar-bottom Browser's default value Sets the position from bottom of caption toolbar. To apply, set --zg-caption-toolbar-position.
--zg-caption-toolbar-justify-content flex-start Sets the horizontal alignment of contents in caption toolbar
--zg-caption-toolbar-left auto Sets the left of caption toolbar. To apply, set --zg-caption-toolbar-position.
--zg-caption-toolbar-margin 0 Sets the margin of caption toolbar
--zg-caption-toolbar-position Browser's default value Sets the position of caption toolbar
--zg-caption-toolbar-right auto Sets the right of caption toolbar. To apply, set --zg-caption-toolbar-position.
--zg-caption-toolbar-top auto Sets the top of caption toolbar. To apply, set --zg-caption-toolbar-position.
--zg-caption-toolbar-transform none Sets the transform of caption toolbar
--zg-caption-toolbar-width auto Sets the width of caption toolbar
--zg-caption-transition Browser's default value Sets the transition of caption
Top

CSS Selector

<zg-caption> can be styled by common CSS selectors.

zg-caption {
  background: red;
}
Top

CSS Shadow Parts

<zg-caption> exposed elements within the shadow can be styled by CSS shadow parts, like so:

zg-caption::part(caption) {
  background-color: red;
}

Below is a list of all the associated ZGCaption shadow parts. Check out the full list of CSS shadow parts or our Styling Basics guide to learn more about styling the grid.

ZGCaption CSS Shadow Parts
Name Description
caption Caption container
title The title container
toolbar The toolbar container
Top

Slots

<zg-caption> contains placeholders to allow adding markup inside the component.

<!-- Default slot -->
<zg-caption>Slotted Content</zg-caption>

<!-- Named slot -->
<zg-caption><span slot="message">Slotted Content</span></zg-caption>

Below is a list of all the associated ZGCaption slots. Check out the full list of slots.

ZGCaption Slots
Name Description Demo
Caption title.
message Caption title. Use when using a feature that enables caption toolbar ([contextMenu], [search], [staticMenu]).
tool Caption toolbar, which is added to the rightmost of caption by default.
Top

[api: <zg-caption>]