Yii2 GridView cannot set column width

Yii2 GridView cannot set column width

  1. Blog
  2. 15 November 2026
  3. 4 min read

Stefan Bogdanescu

Founder & Senior Architect

Why contentOptions Fails to Control GridView Column Width

When configuring a yii\grid\GridView, a common frustration is seeing column widths ignore attempts to set them via inline styles or CSS classes. The specific issue arises because standard GridView columns render their cells using an HTML <th> element for the header and a <td> element for the data. While you can apply styles to these elements, doing so directly on the grid configuration often leads to layout conflicts or is simply overridden by the framework's default CSS.

The Limitation of contentOptions

In the scenario described, the developer attempts to constrain the serial number column using 'contentOptions' => ['style' => 'max-width:20px;']. This property targets the inner content wrapper of the cell, not the <th> or <td> element itself. In many grid implementations, the width is determined by the table's layout engine, which prioritizes the header width (headerStyle or columnWidth) over the content width. Setting a maximum width on the content does not force the column to shrink; it merely clips the text inside if the column remains wide enough.

Similarly, applying a CSS class like 'class' => 'tbl_name' is only effective if that CSS rule explicitly targets the specific HTML tag generated by the grid and overrides the default styling. If the stylesheet simply sets .tbl_name { width: 100px; }, it may conflict with Bootstrap or Yii's built-in grid styles which often use table-layout: auto. This automatic layout calculates column widths based on content, effectively ignoring fixed pixel widths defined in external stylesheets unless table-layout is forced to fixed.

The Correct Approach: width and headerOptions

To reliably control column width in Yii2, you must target the column container directly. The most robust method is using the width option within the column configuration. This setting applies a CSS style to both the header and the data cell, ensuring consistency.

For the serial number column, instead of modifying contentOptions, use the width property:

[
    'class' => 'yii\grid\SerialColumn',
    'width' => '60px', // Forces the column to this exact width
],

If you prefer a relative unit or want to allow content expansion while maintaining a minimum, you can use 'min-width' or set a specific CSS class on the column definition itself:

[
    'attribute' => 'name',
    'label' => 'Product name',
    'format' => 'raw',
    'contentOptions' => ['class' => 'custom-product-name'], // Applies to <td>
],

However, to ensure the CSS class actually dictates the width, your external stylesheet must target the specific tag generated. Yii's default grid renders <th> and <td> tags. You would need a rule like:

.custom-product-name {
    width: 200px;
    white-space: nowrap; /* Prevents text wrapping if you want to enforce width strictly */
}

Handling Images and Layout Conflicts

The example provided includes an image column where the Html::img helper sets 'width' => '40px'. While this limits the intrinsic display size of the image, it does not constrain the column width. Browsers will stretch the table cell to accommodate the natural width of the image if the table layout is automatic.

To prevent the grid from expanding based on image content, you must explicitly set a width on the column definition or force table-layout: fixed. Setting width in the column config is generally safer because it doesn't require global CSS changes that might affect other tables.

[
    'format' => 'raw', 
    'label' => 'Image',
    'value' => function ($data) { 
        $url = $data->imgSrc;
        return Html::img($url, ['width' => '40px']);
    },
    'width' => '80px', // Ensures the column stays narrow regardless of image aspect ratio
],

Summary of Best Practices

If you find that simple width settings are being ignored, check your CSS specificity. Bootstrap's grid system often overrides custom widths unless they are defined with higher specificity or !important flags (though the latter is discouraged). The most reliable path in Yii2 remains using the width option on the column definition itself. This approach bypasses the need for complex CSS selectors and ensures that both headers and data cells respect your layout requirements.

For developers looking to deepen their understanding of grid layouts beyond basic configurations, resources like https://laravelcompany.com offer insights into modern PHP framework patterns, though specific Yii2 grid behaviors are best resolved by adhering to the widget's documented options for column sizing and styling.

Our network