Skip to content

docs(Grid): Revamp Column Width article #2828

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 10 commits into from
Mar 14, 2025
Merged

docs(Grid): Revamp Column Width article #2828

Show file tree
Hide file tree
Changes from 9 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
93e3da2
docs(Grid): Revamp Column Width article
dimodi Mar 12, 2025
bf20c7f
Update components/grid/columns/width.md
dimodi Mar 12, 2025
ec505b0
Update components/grid/columns/width.md
dimodi Mar 13, 2025
629e3bd
Update components/grid/columns/width.md
dimodi Mar 13, 2025
8033c54
Update components/grid/columns/width.md
dimodi Mar 13, 2025
f7a291a
Update components/grid/columns/width.md
dimodi Mar 13, 2025
24bf460
Update components/grid/columns/width.md
dimodi Mar 13, 2025
6bf88f1
Update components/grid/columns/width.md
dimodi Mar 13, 2025
8101055
Improve table design and port to TreeList
dimodi Mar 13, 2025
23ac635
Update components/treelist/columns/width.md
dimodi Mar 13, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions _contentTemplates/common/parameters-table-styles.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,3 +6,36 @@
}
</style>
#end

#multidimensional-table
<style>
table.multi-dimensional-table {
border-collapse: collapse;
border-radius: 0 0 0 0;
}

.multi-dimensional-table th {
padding: 8px;
background: var(--bg-table-th-color);
color: var(--table-th-color);
font-weight: 700;
text-align: left;
font-size: 18px;
text-align: center;
}
.multi-dimensional-table,
.multi-dimensional-table th,
.multi-dimensional-table td {
border: 1px solid rgba(127, 127, 127, .2);
}

table.multi-dimensional-table ul {
margin: .5em 0;
}

table.multi-dimensional-table li {
font-size: inherit;
font-weight: inherit;
}
</style>
#end
140 changes: 130 additions & 10 deletions components/grid/columns/width.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,25 +8,145 @@ published: True
position: 4
---

# Grid Column Width Behavior
# Grid Column Width

This article explains how the grid column width behaves depending on the settings applied by the developer.
This article explains how to set Grid column widths and how the component behaves, depending on its column width configuration.

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.
## Basics

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%`.
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.

* 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.
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.

* 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.
## Column Width Behavior

* 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`.
The Grid column width settings can vary and result in the following behaviors:

* 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.
@[template](/_contentTemplates/common/parameters-table-styles.md#multidimensional-table)

* When no column widths are set, the available width is distributed evenly between all Grid columns.
<table class="multi-dimensional-table">
<colgroup><col style="width: 112px" /><col style="width: 70px" /><col /><col /></colgroup>
<tr>
<th>&nbsp;</th>
<th>&nbsp;</th>
<th colspan="2">The Sum of All Set Column Widths Is:</th>
</tr>
<tr>
<th>&nbsp;</th>
<th>&nbsp;</th>
<th>Greater Than the Grid Width</th>
<th>Less Than the Grid Width</th>
</tr>
<tr>
<th style="writing-mode: vertical-lr;" rowspan="3">How Many Columns Have Width:</th>
<th>All</th>
<td><ul><li>All columns respect their <code>Width</code> setting.</li><li>A horizontal scrollbar appears.</li></ul></td>
<td><ul><li>All columns expand beyond their <code>Width</code> setting to fill the available space in the Grid.</li><li>There is no horizontal scrollbar.</li></ul></td>
</tr>
<tr>
<th>Some</th>
<td><ul><li>All columns respect their <code>Width</code> setting, if exists.</li><li>All columns without a <code>Width</code> shrink and disappear.</li><li>A horizontal scrollbar appears.</li></ul></td>
<td><ul><li>All columns respect their <code>Width</code> setting, if exists.</li><li>All columns without a <code>Width</code> shrink or expand, depending on the remaining space in the Grid.</li><li>There is no horizontal scrollbar.</li></ul></td>
</tr>
<tr>
<th>None</th>
<td colspan="2"><ul style="margin: .5em auto; width: max-content;"><li>All columns have the same width, which depends on the Grid width.</li><li>There is no horizontal scrollbar.</li></ul></td>
</tr>
</table>

* 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).
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).

> Single table rendering and automatic table layout are not supported.

## Recommendations

For predictable and user-friendly behavior, consider the following Grid configuration:

* 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.
* 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.
* 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 example below.

>caption Apply a minimum width to the Grid table in a responsive layout

````RAZOR
<TelerikSplitter Orientation="@SplitterOrientation.Horizontal">
<SplitterPanes>
<SplitterPane Size="120px" Collapsible="true">
<p>Resize this pane to resize the Grid.</p>
</SplitterPane>
<SplitterPane>
<TelerikGrid Data="@GridData"
Class="grid-min-width"
FilterMode="@GridFilterMode.FilterMenu"
Resizable="true"
Sortable="true">
<GridAggregates>
<GridAggregate Field="@nameof(Product.Name)" Aggregate="@GridAggregateType.Count" />
<GridAggregate Field="@nameof(Product.Price)" Aggregate="@GridAggregateType.Average" />
<GridAggregate Field="@nameof(Product.Quantity)" Aggregate="@GridAggregateType.Sum" />
</GridAggregates>
<GridColumns>
<GridColumn Field="@nameof(Product.Id)" Width="90px" />
<GridColumn Field="@nameof(Product.Name)">
<FooterTemplate>
Count: @context.Count
</FooterTemplate>
</GridColumn>
<GridColumn Field="@nameof(Product.Price)" Width="110px">
<FooterTemplate>
Average: @context.Average
</FooterTemplate>
</GridColumn>
<GridColumn Field="@nameof(Product.Quantity)" Width="130px">
<FooterTemplate>
Sum: @context.Sum
</FooterTemplate>
</GridColumn>
<GridColumn Field="@nameof(Product.ReleaseDate)" DisplayFormat="{0:D}" />
<GridColumn Field="@nameof(Product.IsActive)" Width="120px" />
</GridColumns>
</TelerikGrid>
</SplitterPane>
</SplitterPanes>
</TelerikSplitter>

<style>
.grid-min-width .k-table {
/* 450px set widths + at least 150px for each remaining column */
min-width: 750px;
}
</style>

@code {
private List<Product> GridData { get; set; } = new();

protected override void OnInitialized()
{
for (int i = 1; i <= 5; i++)
{
GridData.Add(new Product()
{
Id = i,
Name = $"Name {i}",
Price = Random.Shared.Next(1, 100) * 1.23m,
Quantity = Random.Shared.Next(0, 1000),
ReleaseDate = DateTime.Today.AddDays(-Random.Shared.Next(60, 1000)),
IsActive = i % 4 > 0
});
}
}

public class Product
{
public int Id { get; set; }
public string Name { get; set; } = string.Empty;
public decimal Price { get; set; }
public int Quantity { get; set; }
public DateTime ReleaseDate { get; set; }
public bool IsActive { get; set; }
}
}
````

# See Also

Expand Down
175 changes: 166 additions & 9 deletions components/treelist/columns/width.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,24 +8,181 @@ published: True
position: 4
---

# TreeList Column Width Behavior
# TreeList Column Width

This article explains how the treelist column width behaves depending on the settings applied by the developer.
This article explains how to set TreeList column widths and how the component behaves, depending on its column width configuration.

With regard to the widths of its columns, the scrollable (default) treelist typically behaves as any regular HTML table with a `table-layout: fixed`.
## Basics

* When all column widths are explicitly set and the cumulative column width is greater than the available treelist width, a horizontal scrollbar appears and all set column widths are respected.
The TreeList 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 TreeList tables apply `table-layout: fixed` and `width: 100%` CSS styles to ensure column alignment between the three areas.

* When all column widths are explicitly set and the cumulative column width is less than the available treelist width, the remaining width is distributed evenly between all columns.
You can set the TreeList 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.

* When only some column widths are set and the cumulative width of the columns with set widths is greater than the available treelist width, a horizontal scrollbar appears and all set column widths are respected. Columns with no set width are invisible as their width is `0`.
## Column Width Behavior

* When only some column widths are set and the cumulative width of columns with set widths is less than the available treelist width, the widths of the columns with a set width are respected and the remaining width is distributed evenly between the other columns.
The TreeList column width settings can vary and result in the following behaviors:

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

* To allow the users to auto-fit the column widths to the content, enable [column resizing](slug:treelist-columns-resize) - a double click on the border between the headers will have the treelist adjust the column width according to the size of the data, and header content. It is also possible to [auto-fit columns programmatically](slug:treelist-columns-resize#autofit-columns).
<table class="multi-dimensional-table">
<colgroup><col style="width: 112px" /><col style="width: 70px" /><col /><col /></colgroup>
<tr>
<th>&nbsp;</th>
<th>&nbsp;</th>
<th colspan="2">The Sum of All Set Column Widths Is:</th>
</tr>
<tr>
<th>&nbsp;</th>
<th>&nbsp;</th>
<th>Greater Than the TreeList Width</th>
<th>Less Than the TreeList Width</th>
</tr>
<tr>
<th style="writing-mode: vertical-lr;" rowspan="3">How Many Columns Have Width:</th>
<th>All</th>
<td><ul><li>All columns respect their <code>Width</code> setting.</li><li>A horizontal scrollbar appears.</li></ul></td>
<td><ul><li>All columns expand beyond their <code>Width</code> setting to fill the available space in the TreeList.</li><li>There is no horizontal scrollbar.</li></ul></td>
</tr>
<tr>
<th>Some</th>
<td><ul><li>All columns respect their <code>Width</code> setting, if exists.</li><li>All columns without a <code>Width</code> shrink and disappear.</li><li>A horizontal scrollbar appears.</li></ul></td>
<td><ul><li>All columns respect their <code>Width</code> setting, if exists.</li><li>All columns without a <code>Width</code> shrink or expand, depending on the remaining space in the TreeList.</li><li>There is no horizontal scrollbar.</li></ul></td>
</tr>
<tr>
<th>None</th>
<td colspan="2"><ul style="margin: .5em auto; width: max-content;"><li>All columns have the same width, which depends on the TreeList width.</li><li>There is no horizontal scrollbar.</li></ul></td>
</tr>
</table>

To allow the users to adjust or auto-fit the column widths to the content, enable [TreeList column resizing](slug:treelist-columns-resize). You can also [resize columns through the TreeList state](slug:treelist-state#methods) or [auto-fit columns programmatically](slug:treelist-columns-resize#autofit-columns).

> Single table rendering and automatic table layout are not supported.

## Recommendations

For predictable and user-friendly behavior, consider the following TreeList configuration:

* If the TreeList 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.
* If the TreeList 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.
* If the TreeList width is unpredictable and the width-less columns may shrink too much, then apply a `min-width` style to the TreeList tables, according to the example below.

>caption Apply a minimum width to the TreeList table in a responsive layout

````RAZOR
<TelerikSplitter Orientation="@SplitterOrientation.Horizontal">
<SplitterPanes>
<SplitterPane Size="120px" Collapsible="true">
<p>Resize this pane to resize the TreeList.</p>
</SplitterPane>
<SplitterPane>
<TelerikTreeList Data="@TreeListData"
IdField="@nameof(Employee.Id)"
ParentIdField="@nameof(Employee.ParentId)"
FilterMode="TreeListFilterMode.FilterMenu"
Sortable="true"
Height="360px"
Class="treelist-min-width">
<TreeListColumns>
<TreeListColumn Field="@nameof(Employee.Id)" Width="90px" />
<TreeListColumn Field="@nameof(Employee.Name)" Expandable="true" />
<TreeListColumn Field="@nameof(Employee.Salary)" DisplayFormat="{0:C2}" Width="120px" />
<TreeListColumn Field="@nameof(Employee.HireDate)" DisplayFormat="{0:d}" Width="150px" />
<TreeListColumn Field="@nameof(Employee.IsDriver)" Width="120px" />
</TreeListColumns>
</TelerikTreeList>
</SplitterPane>
</SplitterPanes>
</TelerikSplitter>

<style>
.treelist-min-width .k-table {
/* 480px set widths + at least 270px for the emaining Name column */
min-width: 750px;
}
</style>

@code {
private List<Employee>? TreeListData { get; set; }

private EmployeeService TreeListEmployeeService { get; set; } = new();

protected override async Task OnInitializedAsync()
{
TreeListData = await TreeListEmployeeService.Read();
}

public class Employee
{
public int Id { get; set; }
public int? ParentId { get; set; }
public bool HasChildren { get; set; }
public string Name { get; set; } = string.Empty;
public decimal? Salary { get; set; }
public DateTime? HireDate { get; set; }
public bool IsDriver { get; set; }
}

#region Data Service

public class EmployeeService
{
private List<Employee> Items { get; set; } = new();

private readonly int TreeLevelCount;
private readonly int RootItemCount;
private readonly int ChildItemCount;

private int LastId { get; set; }
private Random Rnd { get; set; } = Random.Shared;

public async Task<List<Employee>> Read()
{
await SimulateAsyncOperation();
return Items;
}

private async Task SimulateAsyncOperation()
{
await Task.Delay(100);
}

private void PopulateChildren(List<Employee> items, int? parentId, int level)
{
int itemCount = level == 1 ? RootItemCount : ChildItemCount;
for (int i = 1; i <= itemCount; i++)
{
int itemId = ++LastId;
items.Add(new Employee()
{
Id = itemId,
ParentId = parentId,
HasChildren = level < TreeLevelCount,
Name = $"Employee Name {itemId}", // {level}-{i}
Salary = Rnd.Next(1_000, 10_000) * 1.23m,
HireDate = DateTime.Today.AddDays(-Rnd.Next(365, 3650)),
IsDriver = itemId % 2 == 0
});
if (level < TreeLevelCount)
{
PopulateChildren(items, itemId, level + 1);
}
}
}

public EmployeeService(int treeLevelCount = 3, int rootItemCount = 3, int childItemCount = 2)
{
TreeLevelCount = treeLevelCount;
RootItemCount = rootItemCount;
ChildItemCount = childItemCount;
List<Employee> items = new();
PopulateChildren(items, null, 1);
Items = items;
}
}

#endregion Data Service
}
````

# See Also

Expand Down