Sorting

Examples

<script>
export default {
  data() {
    return {
      sortOptions: [
        { value: 'first', text: 'First item' },
        { value: 'second', text: 'Second item' },
        { value: 'third', text: 'Third item' },
      ],
      localSortBy: 'first',
      localIsAscending: false,
    };
  },
};
</script>

<template>
  <gl-sorting
    :sort-options="sortOptions"
    :sort-by="localSortBy"
    :is-ascending="localIsAscending"
    @sortByChange="localSortBy = $event"
    @sortDirectionChange="localIsAscending = $event"
  />
</template>

View in Pajamas UI Kit →

Structure

Guidelines

When to use

• Use the sorting component when the list has pagination and spans multiple pages, as it can make it easier for users to digest and find relevant content.
• A user's sort selections are meant to be persisted. If they make a sort selection and then leave the page, when they return to the page, their previous sort selections will be preserved.
• Sorting can occur in tables and in lists. While sorting in lists relies on the sorting component described on this page, sorting within a table happens in the table header. See table sorting guidelines.

When not to use

• When using the sorting component, make sure the list in the dropdown doesn't contain more than 10 items, otherwise it will create usability problems. See combobox guidelines.
• If a list is static, easy to search/scan, or where the data set won't grow, the sorting component is unnecessary.

Appearance

• The sorting component is comprised of two parts: a dropdown, and a sort direction icon button.

Behavior

• The dropdown allows users to choose their sorting criteria, whether it be by label, date, or popularity.
• As soon as an item in the dropdown is selected, the list content re-sorts automatically.
• The sort dropdown allows for sorting by a single selected item.
• The sort direction icon button allows users to change the direction of the sort, from ascending to descending or vice-versa.
• Avoid using invisible attributes for sorting because it lacks visual reinforcement of the user's action, which can be confusing.
• The default sort order on a list is determined by the designer on a page-by-page basis.

Accessibility

Code reference

GlSorting

The sorting component allows the user to select the field on which they would like to sort a list and whether to sort in ascending or descending order.

Provide a list of sort options via the sortOptions prop with this structure:

type sortOptionsProp = Array<{
  value: string;
  text: string;
  directionToggleDisabled?: boolean;
}>;

The value should be a unique primitive value, and text is the user-facing string for that option.

Set the currently selected sort option by passing a value to the sortBy prop. This should equal one of the sortOptions values. The selected sort option is rendered with a check mark next to it in the dropdown menu.

When the user changes the selected sort option, a sortByChange event is emitted, with the value of the option as the only payload.

The text of the dropdown trigger button is the text of the selected sort option. Pass a string to the text prop to override this behavior.

When the user clicks on the sort direction button, a sortDirectionChange event is emitted, with a boolean value as its only payload. If the payload is true, the new order is ascending; otherwise it's descending.

Some sort options have no ascending/descending meaning, such as a "Most relevant" sort. To disable the sort direction button for these, set directionToggleDisabled: true on the relevant sortOptions entries; the button is then automatically disabled whenever such an option is selected.

When disabled, the button stays visible to avoid layout shifts and focus loss when switching sort options, but it is marked aria-disabled, keeps an accessible name explaining why it is unavailable, and no longer emits sortDirectionChange.

A complete implementation example might look like:

<script>
export default {
  data() {
    const sortOptions = [
      {
        value: 'name',
        text: 'Name',
      },
      {
        value: 'date',
        text: 'Date',
      },
      {
        value: 'relevant',
        text: 'Most relevant',
        directionToggleDisabled: true,
      },
    ];

    return {
      isAscending: false,
      sortBy: sortOptions[0].value,
      sortOptions,
    };
  },
  methods: {
    onSortByChange(value) {
      this.sortBy = value;
      this.sortMyData(this.sortBy, this.isAscending);
    },
    onDirectionChange(isAscending) {
      this.isAscending = isAscending;
      this.sortMyData(this.sortBy, this.isAscending);
    },
    sortMyData(sortBy, isAscending) {
      // Use sortBy and direction to sort your data
    },
  },
};
</script>

<template>
  <gl-sorting
    :sort-options="sortOptions"
    :sort-by="sortBy"
    :is-ascending="isAscending"
    @sortByChange="onSortByChange"
    @sortDirectionChange="onDirectionChange"
  />
</template>

import { GlSorting } from '@gitlab/ui';