Weight

Weight is a number Drupal uses to order items such as menu links, blocks and form fields: lower or negative numbers come first, larger ones later.

Learn DrupalDrupal glossary
Edited by Founder and CEO, DXPR Last updated

Weight is a number, usually a whole number, that tells Drupal in what order to show a set of items. Menu links, blocks in a region, form fields and other render elements all use it. Items with lower weights, including negative ones, come first; items with larger weights come later.

How weight works in Drupal 11

Weight is relative. A weight of 5 means nothing alone; it only decides the position against the other items in the same list. The Drupal API describes weights as integers that indicate ordering, with larger numbers later in the order.

There are two places you meet it:

  • In the admin. Menu links and blocks are listed in tables with drag handles. When you drag a row, Drupal changes the weights for you. The Show row weights link replaces the handles with weight fields, so you can set the numbers instead.
  • In code. A render array child can carry a #weight property. The helper Element::children() reads it and, when asked to sort, reorders the children. A child without #weight counts as 0, equal weights keep their original order, and Drupal handles up to three decimal places. Once an array is sorted, it is flagged with #sorted and is not sorted again.

The same idea is available as a form element. #type => 'weight' renders a field for choosing a weight. Its #delta property sets the range around zero (the default is 10, so -10 to 10), and the default value is 0. When the delta is no larger than the weight_select_max value in the system.site configuration, it shows a select list; above that, a number field.

Example

To move the Main navigation link Contact before About, open the Main navigation menu in the admin and drag the row, or click Show row weights and give Contact a lower number than About. The same method orders blocks in a region on the block layout page.

In code, a negative weight moves an element up:

$build['intro'] = [
          '#markup' => $this->t('Read this first.'),
          '#weight' => -10,
        ];
        $build['details'] = [
          '#markup' => $this->t('More details.'),
          '#weight' => 5,
        ];

Both keys sit under the same parent, so intro renders before details. See the Render API and the Form API for the structures that carry it.

Common mistakes

  • Thinking the big number wins. A weight of 10 does not come first; it comes after 0 and after -10. Think of heavy items sinking.
  • Giving every item a weight in steps of 1. Adding a new item between two neighbors then means renumbering. Leave gaps, such as 0, 10, 20.
  • Mixing up scopes. Weights only compare items in the same list. A block with weight -50 in one region says nothing about a block in another region.

For marketing and content teams

You rarely type a weight. Reordering a menu or a block is a drag and drop, and Drupal stores the number. If the order of a navigation menu looks wrong after saving, open the page again and use Show row weights to see the numbers behind the order.

Sources

Questions about weight

A lower weight comes first. Negative numbers are the lightest and rise to the top, while larger numbers sink later in the order. The Drupal User Guide says items with lower or more negative weights are shown first.

In a render array, items with equal weights keep the order in which they were added. If you need a fixed order, give each item its own number, with some gaps between them so you can insert another item later.

On pages with drag-and-drop tables, such as menu links and the block layout, click the Show row weights link above the table. The drag handles give way to weight fields. Edit the numbers, then click Save.

In a render array, a child without a #weight counts as weight 0. The Weight form element also starts at 0 unless you set a default value, and its range is -10 to 10 unless you change #delta.

Related terms

All Drupal terms from A to Z