sort-import-attributes

Enforce sorted import attributes.

This rule keeps attributes inside import ... with { ... } consistently ordered. It improves readability, makes diffs smaller, and keeps attribute groups tidy in larger files.

Try it out

import data from 'lib' with {
  mode: 'no-cors',
  type: 'json',
  integrity: 'sha256-...',
}

Options

This rule accepts an options object with the following properties:

type

_{default: 'alphabetical'}

Specifies the sorting method.

'alphabetical' — Sort attributes alphabetically using localeCompare.
'natural' — Sort by natural order (e.g., link2 < link10).
'line-length' — Sort by attribute name length (shorter first by default).
'custom' — Sort using a custom alphabet specified in alphabet.
'unsorted' — Do not sort items. grouping and newlines behavior are still enforced.

order

_{default: 'asc'}

Sort direction.

'asc' — Ascending (A→Z, short→long).
'desc' — Descending (Z→A, long→short).

fallbackSort

_{type:
{
type: 'alphabetical' | 'natural' | 'line-length' | 'custom' | 'unsorted'
order?: 'asc' | 'desc'
}}_{default: { type: 'unsorted' }}

Fallback sorting used when the primary comparison results are equal.

Example: ensure alphabetical tiebreak for equal name lengths.

{
  type: 'line-length',
  order: 'desc',
  fallbackSort: { type: 'alphabetical', order: 'asc' }
}

alphabet

_{default: ''}

Used only when type is 'custom'. Defines the custom character order.

ignoreCase

_{default: true}

Whether to perform case-insensitive comparison for string-based sorts.

specialCharacters

_{default: 'keep'}

How to handle special characters before comparison.

'keep' — Keep as-is.
'trim' — Trim leading special characters.
'remove' — Remove all special characters.

locales

_{default: 'en-US'}

Locales passed to localeCompare for alphabetical/natural sorts.

partitionByComment

_{default: false}

Use comments to split attributes into independent partitions that are sorted separately.

true — Any non-ESLint comment creates a partition.
false — Ignore comments for partitioning.
RegExpPattern = string | { pattern: string; flags?: string } — Pattern for matching comments.
RegExpPattern[] — List of patterns.
{ block: boolean | RegExpPattern | RegExpPattern[]; line: boolean | RegExpPattern | RegExpPattern[] } — Separate settings for block/line comments.

partitionByNewLine

_{default: false}

When true, an empty line between attributes creates a partition. Each partition is sorted independently.

newlinesBetween

_{type: number | 'ignore'}_{default: 'ignore'}

Specifies how to handle newlines between groups.

'ignore' — Do not report errors related to newlines.
0 — No newlines are allowed.
Any other number — Enforce this number of newlines between each group, and forbid newlines inside groups.

You can also enforce the newline behavior between two specific groups through the groups options.

See the groups option.

This option is only applicable when partitionByNewLine is false.

groups

_{type:
Array<
| string
| string[]
| { newlinesBetween: number }
| {
group: string | string[];
type?: 'alphabetical' | 'natural' | 'line-length' | 'custom' | 'unsorted';
order?: 'asc' | 'desc';
newlinesInside?: number;
}
>}_{default: []}

Defines the order of attribute groups. Unknown attributes are placed after the last group.

You can mix predefined (none for this rule) and custom groups. Typical usage is with custom groups declared via elementNamePattern.

Example: put any attribute starting with type before others, and require a newline between groups.

{
  groups: ['type-attrs', 'unknown'],
  customGroups: [
    { groupName: 'type-attrs', elementNamePattern: '^type' },
  ],
  newlinesBetween: 1
}

Group with overridden settings

You may directly override options for a specific group by using an object with the group property and other option overrides.

type — Overrides the type option for that group.
order — Overrides the order option for that group.
newlinesInside — Enforces a specific newline behavior between elements of the group.

{
  groups: [
    'myCustomGroup1',
    { group: 'myCustomGroup2', type: 'unsorted' }, // Elements from this group will not be sorted
  ]
}

Newlines between groups

You may place newlinesBetween objects between your groups to enforce the newline behavior between two specific groups.

See the newlinesBetween option.

This feature is only applicable when partitionByNewLine is false.

{
  newlinesBetween: 1,
  groups: [
    'a',
    { newlinesBetween: 0 }, // Overrides the global newlinesBetween option
    'b',
  ]
}

customGroups

Define custom attribute groups with optional per-group sort overrides.

type CustomGroup = {
  groupName: string
  // Match by attribute name
  elementNamePattern?: string | string[] | { pattern: string; flags?: string } | { pattern: string; flags?: string }[]

  // Optional per-group overrides:
  type?: 'alphabetical' | 'natural' | 'line-length' | 'custom' | 'unsorted'
  order?: 'asc' | 'desc'
  fallbackSort?: { type: string; order?: 'asc' | 'desc' }
  newlinesInside?: number
}[]

An attribute matches a custom group when its name satisfies elementNamePattern. The first matching definition wins.

Usage

// .eslintrc.js
module.exports = {
  plugins: ['perfectionist'],
  rules: {
    'perfectionist/sort-import-attributes': [
      'error',
      {
        type: 'alphabetical',
        order: 'asc',
        fallbackSort: { type: 'unsorted' },
        ignoreCase: true,
        specialCharacters: 'keep',
        locales: 'en-US',
        alphabet: '',
        partitionByComment: false,
        partitionByNewLine: false,
        newlinesBetween: 'ignore',
        groups: [],
        customGroups: [],
      },
    ],
  },
}

Version

This rule was introduced in v5.0.0.