Theming documentation

docs/vaadin-grid-styling.adoc

@@ -0,0 +1,157 @@
+---
+title: Styling
+order: 6
+layout: page
+---
+
+[[vaadin-grid.styling]]
+= Styling
+
+The default appearance of [vaadinelement]#vaadin-grid# is quite neutral.
+It inherits CSS properties such as [propertyname]#font-size# from the containing document, data rows are divided with gray borders and selected rows get highlighted.
+
+[[figure.vaadin-grid.styling.default]]
+image::img/vaadin-grid-styling-default.png[width="450"]
+
+This section explains how you can customize the [vaadinelement]#vaadin-grid#'s appearance to make it better fit your application theme by using the built-in style mixins and how to leverage the column templates for further modifications.
+
+See the link:https://cdn.vaadin.com/vaadin-core-elements/preview/vaadin-grid/demo/styling.html[live demos] for more thorough examples on how the grid can be modified to comply to link:https://material.io/guidelines/components/data-tables.html[Material Design] specs or how to define data rows with rounded borders and more.
+
+[[vaadin-grid.styling.mixins]]
+== Theming With Style Mixins
+
+The vaadin-grid bundles a set of pre-defined style mixins intended for easy stylability of the grid's cells in various different states and contexts.
+
+For example you might want a specific background color just for the header cells or to separate the frozen columns from other columns by a drop shadow.
+The style mixins of vaadin-grid are just the tool for that.
+
+[NOTE]
+====
+If you're not familiar with how style mixins work, take a look at Polymer's link:https://www.polymer-project.org/1.0/docs/devguide/styling#custom-css-mixins[guide on the topic].
+====
+
+A comprehensive list of the [vaadinelement]#vaadin-grid#'s style mixins is available at the link:https://cdn.vaadin.com/vaadin-core-elements/preview/vaadin-grid/[API documentation].
+
+The following example demonstrates how you could achieve a striped, borderless [vaadinelement]#vaadin-grid# with the header section colored differently.
+
+[source,html]
+----
+<style is="custom-style">
+  vaadin-grid {
+
+    --divider-color: transparent;
+
+    --vaadin-grid-body-row-odd-cell: {
+      background-color: #d6d6d6;
+    };
+
+    --vaadin-grid-header-cell: {
+      background-color: #42849e;
+      color: #fff;
+      text-transform: uppercase;
+    };
+
+  }
+</style>
+----
+
+[[figure.vaadin-grid.styling.striped]]
+image::img/vaadin-grid-styling-striped.png[width="450"]
+
+By default, [vaadinelement]#vaadin-grid# divides it's data rows with horizontal borders.
+Borders are also used for separating the header and footer sections from the body and the frozen columns from other columns.
+Their color defaults to [propertyname]#--divider-color# CSS property and while not available, a fallback color is used instead.
+
+Another default style in [vaadinelement]#vaadin-grid# is the background color of selected rows.
+It derives from [propertyname]#--paper-grey-100# and when not available a fallback color is used.
+
+Changing the [vaadinelement]#vaadin-grid#'s border color and the background color of selected row cells can be achieved as follows.
+
+[source,html]
+----
+<style is="custom-style">
+  vaadin-grid {
+
+    --divider-color: #eaebec;
+
+    --vaadin-grid-body-row-selected-cell: {
+      background-color: #d8f4fd;
+    };
+
+  }
+</style>
+----
+
+[[figure.vaadin-grid.styling.default-modified]]
+image::img/vaadin-grid-styling-default-modified.png[width="450"]
+
+Individual helper elements such as the [vaadinelement]#vaadin-grid-sorter# also exposes link:https://cdn.vaadin.com/vaadin-core-elements/preview/vaadin-grid/#vaadin-grid-sorter[mixins].
+The following example shows how to customize the [vaadinelement]#vaadin-grid-sorter#.
+
+[source,html]
+----
+<style is="custom-style">
+  vaadin-grid-sorter {
+    --vaadin-grid-sorter-arrow: {
+      content: "\21E7";
+    }
+  }
+</style>
+----
+
+[[figure.vaadin-grid.styling.sorter]]
+image::img/vaadin-grid-styling-sorter.png[width="450"]
+
+
+[[vaadin-grid.styling.templates]]
+== Custom Theming With Column Templates
+
+In addition to the style mixins, column templates provide a handy means for making specific style adjustment's to [vaadinelement]#vaadin-grid#'s cells.
+Since the cell content doesn't get hidden inside the [vaadinelement]#vaadin-grid#'s shadow root, it can be targeted with standard CSS selectors.
+
+For example, you might want to align columns with numeric data to the right and have the frozen columns styled with a different background.
+
+[source,html]
+----
+<style is="custom-style">
+  .cell {
+    height: 100%;
+    display: flex;
+    align-items: center;
+    padding: 8px;
+  }
+
+  .frozen {
+    background: #54c6ea;
+  }
+
+  .numeric {
+    justify-content: flex-end;
+  }
+</style>
+
+...
+
+<vaadin-grid-column width="100px" frozen>
+  <template class="header">
+    <div class="cell frozen">User Name</div>
+  </template>
+  <template>
+    <div class="cell frozen">[[item.user.username]]</div>
+  </template>
+</vaadin-grid-column>
+
+...
+
+<vaadin-grid-column>
+  <template class="header">
+    <div class="cell numeric">Age</div>
+  </template>
+  <template>
+    <div class="cell numeric">[[item.user.age]]</div>
+  </template>
+</vaadin-grid-column>
+----
+
+[[figure.vaadin-grid.styling.templates]]
+image::img/vaadin-grid-styling-templates.png[width="450"]