<zg-column>

ZingGrid has a predefined set of column types which have default behavior on render and edit. This behavior can be extended and modified. If you are not familiar with the <zg-column> tag, please refer to the column types guide.

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

Related Web Components

Usage

zg-column types are an extension of the ZingGrid library and are used to increase and alter column display, functionality, and editing.

<zing-grid src="https://cdn.zinggrid.com/datasets/users.json">
  <zg-colgroup>
    <!-- default type is text -->
    <zg-column index="name"></zg-column>
    <!-- explicitly set text -->
    <zg-column type="text" index="job"></zg-column>
    <!-- set image column type -->
    <zg-column type="image" index="img" type-image-mask="circle" content-style="width:50px;height:50px;"></zg-column>
    <!-- set url column type -->
    <zg-column type="url" index="episode_link" type-url-icon="outsidearrow"></zg-column>
  </zg-colgroup>
</zing-grid>

Attributes

The <zg-column> tag is used to associate the columns of the grid to the values in a dataset. Attributes on the tag are used to configure both the data type, style, and function of the grid column. It is possible to build grids without explicit <zg-column> tags; ZingGrid will add a column for each index in the dataset. However, developers are encouraged to explore the features available with <zg-column> to utilize the powerful features ZingGrid has to offer.

Example Usage

<zing-grid src="https://cdn.zinggrid.com/datasets/user-roles.json">
  <zg-column index="firstName" header="First"></zg-column>
</zing-grid>

align

String

Description

Aligns the contents of all column's cells.

Default Value

"left"

Accepted Values

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

Description

If the index is an array of objects, use array-index to indicate which index of the array object to include

Default Value

N/A

Accepted Values

  • "title"
Demo

Description

If the index is an array, you can use array-slice to indicate which array indexes to include.

Default Value

N/A

Accepted Values

  • "0,1", "-1", "0,4"
Demo

Description

The type of word-break style for body cells. When not set, cell-break style is normal by default. If the width of a column is set, cell-break is word by default.

Default Value

"normal"

Accepted Values

  • "all"
  • "ellipsis"
  • "normal"
  • "word"
Demo

Description

The class to be set directly on <zg-cell> within the column. cell-class applied to <zg-column> will overwrite the cell-class applied to <zing-grid>.

Default Value

""

Accepted Values

  • "userCustomClass"
Demo

Description

Sets the execution method of custom 'icon' type tooltips to either activate on hover or click of the icon

Default Value

"hover"

Accepted Values

  • click
  • hover
Demo

Description

Sets the hover delay in milliseconds before displaying the tooltip

Default Value

1000

Accepted Values

  • 2000
Demo

Description

Specify the icon to use for the cell tooltip trigger icon when using the info column type.

Default Value

info

Accepted Values

  • 'checkmark'
Demo

Description

Sets the tooltip-position for the cell

Default Value

"top"

Accepted Values

  • top
  • left
  • right
  • bottom
Demo

Description

Gets the name of the user's custom render function, on window, to use the function's return value as the tooltip content.

Default Value

""

Accepted Values

  • "functionName"
Demo

Description

Points to an external template element to be used as the template for the tooltip display.

Default Value

""

Accepted Values

  • "myTemplateId"
Demo

Description

Sets the tooltip text for the cell of the column. Can pass this value to renderer or template if using

Default Value

""

Accepted Values

  • "Tooltip Value"
Demo

Description

Sets the style to use for the tooltips. Uses the default style by default. Can set to system to match the tooltips used on icons throughout <zing-grid>

Default Value

default

Accepted Values

  • default
  • system
Demo

Description

When an additional HTML element is added to the renderer, as in the case of image and url, content-style will be put into a style attribute directly on the element.

Default Value

""

Accepted Values

  • "max-width: 50px;"
Demo

Description

Sets the width of the content inside of the cell. Used on cells of column type element, iframe, image, or url.

Default Value

""

Accepted Values

  • "500"
  • "500px"
  • 500
Demo

Description

The data to display in each cell where the data value is null or undefined.

Default Value

""

Accepted Values

  • "N/A"
Demo

Description

Renderer for the details page of a column. To use a custom renderer, the attribute should be set to the name of the function. The renderer function takes in the following arguments, value of index (for each index), domCell, and cellObject. The returned value of the renderer function is set as the innerHTML of the details dialog.

Default Value

""

Accepted Values

  • "functionName"
Demo

Description

Points to an external template element to be used as the template for the column's details.

Default Value

""

Accepted Values

  • "myTemplateId"
Demo

draggable

Boolean

Description

Disable the draggable state of a specific column when draggable enabled on <zing-grid>.

Default Value

""

Accepted Values

  • "disabled"
Demo

editor

function

Description

Overrides the default editor for the column. Can be set to a different built in editor (based on type of column), custom editor, or false to turn off editor. If set to a custom editor, the attribute value should be set to the name of the object. See "Features" page on "Editing: Custom Editor" for more details on custom editor.

Default Value

""

Accepted Values

  • "columnType"
  • "objectName"
  • false
Demo

Description

Points to an external template element to be used as the template for the column's editor.

Default Value

""

Accepted Values

  • "myTemplateId"
Demo

filter

String

Description

Overrides the grid level filter attribute. Presence of attribute enables on filter column, otherwise set to disabled to disable.

Default Value

""

Accepted Values

  • "disabled"
Demo

foot-cell

String

Description

The aggregate function, tokenized string or function to evaluate for the foot cell of the column. If using a function, the functin takes the parameters columnData and columnFieldIndex.

Default Value

""

Accepted Values

  • "sum"
  • "avg"
  • "max"
  • "min"
  • "count"
  • "tokenized string"
  • "functionName"
Demo

head-cell

String

Description

The aggregate function to evaluate for the head cell of the column. If using a function, the functin takes the parameters columnData and columnFieldIndex.

Default Value

""

Accepted Values

  • "sum"
  • "avg"
  • "max"
  • "min"
  • "count"
  • "tokenized string"
  • "functionName"
Demo

header

String

Description

The header name for the column. If it is not set, the default is to format the index value.

Default Value

"index"

Accepted Values

  • "My Header"
Demo

Description

Setting to disabled will turn off formatting on the header of the column. By default, headers will convert from camel-, dash-, or kebab-case to a properly spaced and capitalized string. Or set to a function name to customize formatting of header text. The custom function takes in two parameters, index and headerText, and returns the formatted header text.

Default Value

""

Accepted Values

  • "disabled"
  • "functionName"
Demo

Description

Sets the execution method of custom 'icon' type tooltips to either activate on hover or click of the icon

Default Value

"hover"

Accepted Values

  • click
  • hover
Demo

Description

Sets the hover delay in milliseconds before displaying the header tooltip

Default Value

0

Accepted Values

  • 2000
Demo

Description

Specify the icon to use for the header tooltip trigger icon.

Default Value

info

Accepted Values

  • 'checkmark'
Demo

Description

Sets the tooltip icon position for the tooltip icon in the header cells

Default Value

"right"

Accepted Values

  • left
  • right
  • after-text
Demo

Description

Sets the tooltip-position for the header cell

Default Value

"top"

Accepted Values

  • top
  • left
  • right
  • bottom
Demo

Description

Gets the name of the user's custom render function, on window, to use the function's return value as the tooltip content.

Default Value

""

Accepted Values

  • "functionName"
Demo

Description

Points to an external template element to be used as the template for the tooltip display.

Default Value

""

Accepted Values

  • "myTemplateId"
Demo

Description

Sets the tooltip text for the header cell of the column. Can pass this value to renderer or template if using

Default Value

""

Accepted Values

  • "Tooltip Value"
Demo

Description

Sets what part of the header triggers the tooltip. If set to 'icon', an info icon is added to the header

Default Value

text

Accepted Values

  • text
  • icon
Demo

Description

Sets the style to use for the tooltips. Uses the default style by default. Can set to system to match the tooltips used on icons throughout <zing-grid>

Default Value

default

Accepted Values

  • default
  • system
Demo

hidden

Boolean

Description

Presence of attribute hides the column.

Default Value

""

Accepted Values

  • N/A
Demo

index

String

Description

A single index or multiple indices (separated by comma), to associate information in the data source to a column in the grid. Nested data keys are referenced by the member character . (Ex. data.key).

Default Value

""

Accepted Values

  • "recordkey"
  • "key1"
  • "object.key1"
  • "key1, key2, keyN"
Demo

locale

String

Description

Localization code used with column type currency and number.

Default Value

"en-us"

Accepted Values

  • "de-De"
Demo

menu-text

String

Description

The text to display in the control menu for the column. If it is not set, it is set to the header text.

Default Value

"index"

Accepted Values

  • "My Header"
Demo

min-width

Number

Description

Sets the minimum width of the column in pixels.

Default Value

n/a

Accepted Values

  • 150
Demo

renderer

function

Description

Overrides the default renderer for the column. Can be set to a different built-in or custom renderer. To use a custom renderer, the attribute should be set to the name of the function. The renderer function takes in the following arguments, value of index (for each index), domCell, and cellObject. The returned value of the renderer function is set as the innerHTML of the cell.

Default Value

""

Accepted Values

  • "functionName"
Demo

Description

Points to an external template element to be used as the template for the column's renderer.

Default Value

""

Accepted Values

  • "myTemplateId"
Demo

required

Boolean

Description

Indicates that the column is required to have a value on edit

Default Value

{"type":"","bReflectToAttribute":true,"mapping":"bRequired"}

Accepted Values

  • N/A
Demo

resizable

String

Description

Presence of attribute turns on column resizing for single column. Set to disabled to turn off resizing on a single column.

Default Value

""

Accepted Values

  • "disabled"
Demo

Description

Sets the maximum width the column can be set to when resizing.

Default Value

n/a

Accepted Values

  • 150
Demo

Description

Sets the minimum width the column can be set to when resizing.

Default Value

n/a

Accepted Values

  • 150
Demo

Description

Modifies the default column resizable persistence. Set to disabled to turn off persistence on a single column.

Default Value

No Default Value

Accepted Values

No Example Values Demo

search

String

Description

Turns off the search on a column if search is present on <zing-grid>.

Default Value

""

Accepted Values

  • "disabled"
Demo

separator

String

Description

If multiple indices are set, this is the string that separates them in the display. By default, it is a comma.

Default Value

","

Accepted Values

  • "-"
Demo

sort

String

Description

Turns off the sort on a column if sort is present on <zing-grid>.

Default Value

""

Accepted Values

  • "disabled"
Demo

sort-asc

Boolean

Description

Presence of attribute sorts the column data in ascending order.

Default Value

""

Accepted Values

  • N/A
Demo

sort-desc

Boolean

Description

Presence of attribute sorts the column data in descending order.

Default Value

""

Accepted Values

  • N/A
Demo

sort-intl

String

Description

Overrides default behavior for setting special sort for Intl Data.

Default Value

""

Accepted Values

  • "disabled"
Demo

sorter

function

Description

Overrides the default sorter for the column. It is also possible to override the column sorting by passing in method name of sort function instead or setting to disabled to diable sorting. Sorter function takes in two values (a, b) and returns 1, -1, or 0 indicating if a > b, a < b, or a = b. Can also be set to a path in the dataset to perform the sort on. This is useful for sorting object indices.

Default Value

""

Accepted Values

  • "functionName"
Demo

type

String

Description

The type of the data stored in the column. The column renderer/editor will behave based on the column type.

Default Value

""

Accepted Values

  • "boolean"
  • "button"
  • "currency"
  • "custom"
  • "date"
  • "editor"
  • "element"
  • "email"
  • "icon"
  • "image"
  • "iframe"
  • "number"
  • "password"
  • "range"
  • "remover"
  • "row-number"
  • "select"
  • "selector"
  • "tel"
  • "text"
  • "toggle"
  • "url"
Demo

Description

The currency to be used in currency formatting. Currency is set using using the 3 letter currency code specified by ISO 4217 specification (https://en.wikipedia.org/wiki/ISO_4217)

Default Value

"USD" | "EUR"

Accepted Values

No Example Values Demo

Description

The tokanized formatting for a date column

Default Value

Browser Default based on locale

Accepted Values

  • "dddd, MMMM Do YYYY"
Demo

Description

Indicates if date should be displayed in FromNow format

Default Value

n/a

Accepted Values

  • n/a
Demo

Description

Sets the attribute of the custom-element in the column when <zg-column> has type set to element.

Default Value

""

Accepted Values

  • "attributeName"
Demo

Description

Sets the tag to wrap content when <zg-column> has type set to element. If type-element-attribute-name isn't set, it will put the rendered data into the body of the element. If type-element-attribute-name is set, it will set the attribute to the indexed value.

Default Value

""

Accepted Values

No Example Values Demo

Description

To set a square ratio instead of the default 16:9.

Default Value

'square'

Accepted Values

  • 'square'
Demo

Description

The alternative text used with the image type column.

Default Value

Full Image URL

Accepted Values

  • "Logo"
Demo

Description

The alternative shape to mask the image.

Default Value

N/A

Accepted Values

  • "circle"
Demo

Description

Indicates the exact numbers to display after the decimal

Default Value

{"bReflectToAttribute":true,"type":"","mapping":"nTypeNumberDecimals","bRefreshContent":true}

Accepted Values

  • 2
Demo

Description

Set to "disabled" to turn off default number formatting

Default Value

{"bReflectToAttribute":true,"type":"","mapping":"sTypeNumberFormatting","bRefreshContent":true}

Accepted Values

  • "disabled"
Demo

Description

Indicates the maximum numbers to display after the decimal

Default Value

{"bReflectToAttribute":true,"type":"","mapping":"nTypeNumberMaxDecimals","bRefreshContent":true}

Accepted Values

  • 2
Demo

Description

Maximum value for the input box. Used with the range type column in edit mode.

Default Value

100

Accepted Values

  • 150
Demo

Description

Minimum value for the input box. Used with range type column in edit mode.

Default Value

0

Accepted Values

  • 100
Demo

Description

Specifies the step between each legal value for the input box. Used with range type column in edit mode.

Default Value

1

Accepted Values

  • 20
Demo

Description

In edit mode, presence of attribute allows column type select to have mulitple selections, instead of the default of a single selection.

Default Value

""

Accepted Values

  • N/A
Demo

type-select-options

String | Array

Description

To set the options for the select box for a select column when editor is enabled on <zing-grid>. Can also set as array of name/value pairs where the name is displayed for the given value

Default Value

""

Accepted Values

  • "M, T, W, Th, F"
  • [{"name": "Monday", "value": "M"}, {"name": "Tuesday", "value": "T"}, {"name": "Wednesday", "value": "W"}, {"name": "Thursday", "value": "Th"}, {"name": "Friday", "value": "F"}]
Demo

Description

When the column type is set to toggle, use typeToggleOptions to set the list of options for the display.

Default Value

[]

Accepted Values

  • ["red", "orange", "yellow", "green", "blue"]
Demo

type-toggle-options

String | Array

Description

When the column type is set to radio, use typeRadioOptions to add rendered radio options in the cell. Can also set as array of name/value pairs where the name is displayed for the given value

Default Value

undefined

Accepted Values

  • 'one,two,three'
Demo

Description

When the column type is set, the render and value will be the same. This prevents the default creating of true/false for toggles.

Default Value

false

Accepted Values

  • N/A
Demo

Description

If the column type is url, use this attribute to reference any <zg-icon> within the library to replace the link text with this icon.

Default Value

""

Accepted Values

  • "link"
  • "outsidearrow"
Demo

Description

If the column type is url, use the type-url-src attribute to set the src for the link. The link will be the index value by default.

Default Value

""

Accepted Values

  • "https://www.example.com/?searchfor=[[index.id]]"
Demo

Description

If the column type is url, use the type-url-text attribute to set the text displayed for the link.

Default Value

""

Accepted Values

  • "Go to site"
Demo

Description

Sets the validation error message for the column. Overrides any other settings.

Default Value

N/A

Accepted Values

  • "Please provide valid input."
Demo

Description

Sets the validation required message for the column. Overrides any other settings.

Default Value

N/A

Accepted Values

  • "This field is required"
Demo

validator

String | function

Description

Sets the validation method for the column. Overrides the default for the column type

Default Value

N/A

Accepted Values

  • "number"
Demo

Description

Used in the case of automatically removing columns on resize. Columns without a visibility-priority never gets removed. The rest of the columns are removed from highest visibility-priority value to the lowest.

Default Value

""

Accepted Values

  • 2
Demo

width

String | Number

Description

Sets the width of the column.

Default Value

fit

Accepted Values

  • "fit"
  • "fitheader"
  • "fitcontent"
  • "stretch"
  • "10%"
  • "150px"
  • 150
Demo

Type Attribute Values

Below is a list of the accepted values for the <zg-column> type attribute:

zg-column type Values
NameDescriptionDemo
booleanWill render a true|false string value and the editor will use an input field with type="checkbox".
buttonWill render a button and the editor is disabled.
currencyWill render the currency symbol in front of the number and the editor will use an input field with type="number".
customWill slot in column content and allow referencing data via [[index.key]] or [[record.key]], and the editor will use an input field with type="text".
dateWill render the date as a string value and the editor will use an input field with type="date" expecting (dd/mm/yyyy) dates.
editorA render only field to display an icon to edit the record on click.
elementWill wrap cell content with value specified in [type-element-tag-name] with the attribute specified in [type-element-attribute-name].
emailWill render a string value and the editor will use an input field with type="email".
iconA render only field to set icon to convert the cell data into a built-in grid <zg-icon name=""> element. By default, the value must match the name of a native grid icon or the name of a custom icon. Editing will use an input field with type="text".
imageWill render an <img> and the editor will use an input field with type="text".
iframeA render only field to display an <iframe>. Editing will use an input field with type="text".
numberWill render a number as a thousand's separated string value and the editor will use an input field with type="number".
passwordWill render a hidden string value and the editor will use an input field with type="password".
rangeWill render a number as a thousand's separated string value and the editor will use an input field with type="number" with optional min, max and step fields defined on the input.
removerA render only field to display an icon to remove the record on click.
row-numberA render only field to display the current row index of this row.
selectWill render a string value and the editor will use an input field with type="select".
selectorA render only field to display an checkbox to selector and remove the record on click.
telWill render a string value and the editor will use an input field with type="tel".
text(Default Type) Sets the column type to text.
toggleN/A
urlWill render the field to to display an <a> tag. The editor will use an input field with type="text".

CSS Variables

No CSS variables are available for the <zg-column> tag.

CSS Selector

No CSS selectors are available for the <zg-column> tag.

On This Page