Skip to content

Commit 93e3da2

Browse files
dimodidimodi
committed
docs(Grid): Revamp Column Width article
1 parent ec5d152 commit 93e3da2

File tree

1 file changed

+126
-10
lines changed

1 file changed

+126
-10
lines changed

‎components/grid/columns/width.md‎

Lines changed: 126 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -8,25 +8,141 @@ published: True
88
position: 4
99
---
1010

11-
# Grid Column Width Behavior
11+
# Grid Column Width
1212

13-
This article explains how the grid column width behaves depending on the settings applied by the developer.
13+
This article explains how the Grid behaves, depending on the set column widths.
1414

15-
You can set the grid column `Width` parameter in any CSS unit, such as `px`, `%`, `vw`, `em`, `rem`. You can read more on how to set sizes in Telerik components in the [Dimensions](slug:common-features/dimensions) article. You must, however, provide the unit so that the browser can understand it.
15+
## Basics
1616

17-
With regard to the widths of its columns, the scrollable (default) Grid typically behaves as any regular HTML table with a `table-layout: fixed` and `width: 100%`.
17+
The Grid renders separate HTML `<table>` elements for its header, data, and footer areas. This allows users to scroll the data area vertically, while the header and footer areas remain visible at all times. The Grid tables apply `table-layout: fixed` and `width: 100%` CSS styles to ensure column alignment between the three areas.
1818

19-
* When all column widths are explicitly set and the cumulative column width is greater than the available Grid width, a horizontal scrollbar appears and all set column widths are respected.
19+
You can set the Grid column `Width` parameter in any CSS unit, such as `px`, `%`, `vw`, `em`, `rem`. Unit-less `Width` values are not supported. You can read more on how to set sizes in Telerik components in the [Dimensions](slug:common-features/dimensions) article.
2020

21-
* When all column widths are explicitly set and the cumulative column width is less than the available Grid width, the remaining width is distributed evenly between all columns.
21+
## Column Width Behavior
2222

23-
* When only some column widths are set and the cumulative width of the columns with set widths is greater than the available Grid width, a horizontal scrollbar appears and all set column widths are respected. Columns with no set width are invisible as their width is `0`.
23+
The Grid column width settings can vary and result in the following configurations and behavior:
2424

25-
* When only some column widths are set and the cumulative width of columns with set widths is less than the available Grid width, the widths of the columns with a set width are respected and the remaining width is distributed evenly between the other columns.
25+
* All Grid columns have set widths:
26+
* The sum of the column widths exceeds the Grid component width. The Grid renders a horizontal scrollbar. All column widths match their settings.
27+
* The sum of the column widths is less than the Grid width. All columns expand evenly to take up the available space in the Grid.
28+
* Only some Grid columns have set widths:
29+
* The columns that have widths take up less than the Grid component width. The applied column widths match the component settings. The remaining width-less columns shrink or expand, depending on the remaining space. A horizontal scrollbar may appears only if the columns that have widths exceed the Grid width. In this case the remaining columns will disappear.
30+
* The columns that have widths take up more than the Grid component width. The applied column widths match the component settings. A horizontal scrollbar appears. All columns without widths shrink to zero width and disappear.
31+
* No column has a set width: all columns are equally wide. They shrink and expand, depending on the Grid width.
2632

27-
* When no column widths are set, the available width is distributed evenly between all Grid columns.
33+
@[template](/_contentTemplates/common/parameters-table-styles.md#table-layout)
2834

29-
* To allow the users to auto-fit the column widths to the content, enable [column resizing](slug:components/grid/columns/resize) - a double click on the border between the headers will have the grid adjust the column width according to the size of the data, headers and footers content. It is also possible to [auto-fit columns programmatically](slug:components/grid/columns/resize#autofit-columns).
35+
<style>
36+
.multi-dimensonal-table th {
37+
padding: 8px;
38+
background: var(--bg-table-th-color);
39+
color: var(--table-th-color);
40+
font-weight: 700;
41+
text-align: left;
42+
font-size: 18px;
43+
}
44+
</style>
45+
46+
<table class="multi-dimensonal-table">
47+
<tr><th>Explicit&nbsp;Column&nbsp;Widths<br> \ <br> Columns&nbsp;with&nbsp;Widths</th><th>Exceed the Grid Width</th><th>Subceed the Grid Width</th></tr>
48+
<tr><th>All</th><td>The Grid renders a horizontal scrollbar. All column widths match their settings.</td><td>All columns expand evenly to take up the available space in the Grid.</td></tr>
49+
<tr><th>Some</th><td>The applied column widths match the component settings. A horizontal scrollbar appears. All columns without widths shrink to zero width and disappear.</td><td>The applied column widths match the component settings. The remaining width-less columns shrink or expand, depending on the remaining space. A horizontal scrollbar may appears only if the columns that have widths exceed the Grid width. In this case the remaining columns will disappear.</td></tr>
50+
<tr><th>None</th><td>All columns are equally wide. They shrink and expand, depending on the Grid width.</td><td>All columns are equally wide. They shrink and expand, depending on the Grid width.</td></tr>
51+
</table>
52+
53+
To allow the users to adjust or auto-fit the column widths to the content, enable [Grid column resizing](slug:components/grid/columns/resize). You can also [resize columns through the Grid state](slug:grid-state#setstateasync) or [auto-fit columns programmatically](slug:components/grid/columns/resize#autofit-columns).
54+
55+
> Single table rendering and automatic table layout are not supported.
56+
57+
## Recommendations
58+
59+
For predictable and user-friendly behavior, consider the following Grid configuration:
60+
61+
* If the Grid has a fixed width and you need horizontal scrolling, set widths to all columns. Use absolute units that do not depend on the browser viewport size.
62+
* If the Grid does not need horizontal scrolling and is not likely to shrink too much, then leave at least one column without a width. This ensures that all set column widths are respected and the width-less columns take up the remaining space.
63+
* If the Grid width is unpredictable and the width-less columns may shrink too much, then apply a `min-width` style to the Grid tables, according to the exaple below.
64+
65+
>caption Apply a minimum width to the Grid table in a responsive layout
66+
67+
````RAZOR
68+
<TelerikSplitter Orientation="@SplitterOrientation.Horizontal">
69+
<SplitterPanes>
70+
<SplitterPane Size="120px" Collapsible="true">
71+
<p>Resize this pane to resize the Grid.</p>
72+
</SplitterPane>
73+
<SplitterPane>
74+
<TelerikGrid Data="@GridData"
75+
Class="grid-min-width"
76+
FilterMode="@GridFilterMode.FilterMenu"
77+
Resizable="true"
78+
Sortable="true">
79+
<GridAggregates>
80+
<GridAggregate Field="@nameof(Product.Name)" Aggregate="@GridAggregateType.Count" />
81+
<GridAggregate Field="@nameof(Product.Price)" Aggregate="@GridAggregateType.Average" />
82+
<GridAggregate Field="@nameof(Product.Quantity)" Aggregate="@GridAggregateType.Sum" />
83+
</GridAggregates>
84+
<GridColumns>
85+
<GridColumn Field="@nameof(Product.Id)" Width="90px" />
86+
<GridColumn Field="@nameof(Product.Name)">
87+
<FooterTemplate>
88+
Count: @context.Count
89+
</FooterTemplate>
90+
</GridColumn>
91+
<GridColumn Field="@nameof(Product.Price)" Width="110px">
92+
<FooterTemplate>
93+
Average: @context.Average
94+
</FooterTemplate>
95+
</GridColumn>
96+
<GridColumn Field="@nameof(Product.Quantity)" Width="130px">
97+
<FooterTemplate>
98+
Sum: @context.Sum
99+
</FooterTemplate>
100+
</GridColumn>
101+
<GridColumn Field="@nameof(Product.ReleaseDate)" DisplayFormat="{0:D}" />
102+
<GridColumn Field="@nameof(Product.IsActive)" Width="120px" />
103+
</GridColumns>
104+
</TelerikGrid>
105+
</SplitterPane>
106+
</SplitterPanes>
107+
</TelerikSplitter>
108+
109+
<style>
110+
.grid-min-width .k-table {
111+
/* 450px set widths + at least 150px for each remaining column */
112+
min-width: 750px;
113+
}
114+
</style>
115+
116+
@code {
117+
private List<Product> GridData { get; set; } = new();
118+
119+
protected override void OnInitialized()
120+
{
121+
for (int i = 1; i <= 5; i++)
122+
{
123+
GridData.Add(new Product()
124+
{
125+
Id = i,
126+
Name = $"Name {i}",
127+
Price = Random.Shared.Next(1, 100) * 1.23m,
128+
Quantity = Random.Shared.Next(0, 1000),
129+
ReleaseDate = DateTime.Today.AddDays(-Random.Shared.Next(60, 1000)),
130+
IsActive = i % 4 > 0
131+
});
132+
}
133+
}
134+
135+
public class Product
136+
{
137+
public int Id { get; set; }
138+
public string Name { get; set; } = string.Empty;
139+
public decimal Price { get; set; }
140+
public int Quantity { get; set; }
141+
public DateTime ReleaseDate { get; set; }
142+
public bool IsActive { get; set; }
143+
}
144+
}
145+
````
30146

31147
# See Also
32148

0 commit comments

Comments
 (0)