<zg-caption>

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>

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

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
NameDefaultDescriptionDemoCSS Ref
--zg-caption-align-itemscenterSets the vertical alignment of items (title and toolbar) in caption
--zg-caption-backgroundBrowser's default valueStyles the background of caption
--zg-caption-border0Styles the border of caption
--zg-caption-border-bottomvar(--zg-caption-border, 0)Styles the bottom border of caption
--zg-caption-border-leftvar(--zg-caption-border, 0)Styles the left border of caption
--zg-caption-border-radius0Applies a border-radius to the caption
--zg-caption-border-rightvar(--zg-caption-border, 0)Styles the right border of caption
--zg-caption-border-topvar(--zg-caption-border, 0)Styles the top border of caption
--zg-caption-box-shadownoneApplies a box shadow behind caption
--zg-caption-button-backgroundvar(--zg-button-background)Styles the background of button in caption
--zg-caption-button-background_activevar(--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_focusvar(--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_hovervar(--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-colorBrowser's default valueSets the font color of caption
--zg-caption-flex-directionrowSets the flex direction of items (title and toolbar) in caption
--zg-caption-font-familyBrowser's default valueSets the font family of caption
--zg-caption-font-size1.25remSets the font size of caption
--zg-caption-font-styleBrowser's default valueSets the font style of caption
--zg-caption-font-weightBrowser's default valueSets the font weight of caption
--zg-caption-heightBrowser's default valueSets the height of caption
--zg-caption-margin0Sets the margin of caption
--zg-caption-opacityBrowser's default valueSets the opacity of caption
--zg-caption-padding0 var(--theme-padding_x)Sets the padding of caption
--zg-caption-title-align-selfcenterSets vertical alignment of items in caption title
--zg-caption-title-flex0 1 autoSets how items are flexed in caption title
--zg-caption-title-font-familyinheritSets the font-family of caption title
--zg-caption-title-font-sizeinheritSets the font size of caption title
--zg-caption-title-font-styleinheritSets the font style of caption title
--zg-caption-title-font-weightinheritSets the font weight of caption title
--zg-caption-title-margin0Sets the margin of caption title
--zg-caption-title-orderBrowser's default valueSets the order of caption title with respect to caption toolbar
--zg-caption-title-padding0Sets the padding of caption title
--zg-caption-title-text-aligninheritSets the text alignment of caption title
--zg-caption-title-transformnoneSets the transform of caption title
--zg-caption-title-width100%Sets the width of caption title
--zg-caption-toolbar-align-selfBrowser's default valueSets vertical alignment of items in caption toolbar
--zg-caption-toolbar-bottomBrowser's default valueSets the position from bottom of caption toolbar. To apply, set --zg-caption-toolbar-position.
--zg-caption-toolbar-justify-contentflex-startSets the horizontal alignment of contents in caption toolbar
--zg-caption-toolbar-leftautoSets the left of caption toolbar. To apply, set --zg-caption-toolbar-position.
--zg-caption-toolbar-margin0Sets the margin of caption toolbar
--zg-caption-toolbar-positionBrowser's default valueSets the position of caption toolbar
--zg-caption-toolbar-rightautoSets the right of caption toolbar. To apply, set --zg-caption-toolbar-position.
--zg-caption-toolbar-topautoSets the top of caption toolbar. To apply, set --zg-caption-toolbar-position.
--zg-caption-toolbar-transformnoneSets the transform of caption toolbar
--zg-caption-toolbar-widthautoSets the width of caption toolbar
--zg-caption-transitionBrowser's default valueSets the transition of caption

CSS Selector

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

zg-caption {
  background: red;
}

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
NameDescriptionDemo
Caption title.
messageCaption title. Use when using a feature that enables caption toolbar ([contextMenu], [search], [staticMenu]).
toolCaption toolbar, which is added to the rightmost of caption by default.

[api: <zg-caption>]