sort-jsx-props

Enforce sorted JSX props within JSX elements.

Ensure sorted JSX props within your elements to maintain order and readability. Navigating through numerous props can become challenging, especially as components grow in complexity. This rule enforces consistent sorting, making your code cleaner and easier to manage.

This practice enhances the readability and maintainability of the code by providing a predictable organization of properties. It also sometimes reduces possible errors caused by misplaced or unordered props.

Important

If you use the jsx-sort-props rule from the eslint-plugin-react plugin, it is highly recommended to disable it to avoid conflicts.

It’s safe. The rule considers spread elements in a props list and does not break component functionality.

Try it out

Options

This rule accepts an options object with the following properties:

type

_{default: 'alphabetical'}

Specifies the sorting method.

'alphabetical' — Sort items alphabetically (e.g., “a” < “b” < “c”) using localeCompare.
'natural' — Sort items in a natural order (e.g., “item2” < “item10”).
'line-length' — Sort items by code line length (shorter lines first).
'custom' — Sort items using the alphabet specified in the alphabet option.
'unsorted' — Do not sort items. grouping and newlines behavior are still enforced.

order

_{default: 'asc'}

Specifies whether to sort items in ascending or descending order.

'asc' — Sort items in ascending order (A to Z, 1 to 9).
'desc' — Sort items in descending order (Z to A, 9 to 1).

fallbackSort

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

Specifies fallback sort options for elements that are equal according to the primary sort type.

Example: enforce alphabetical sort between two elements with the same length.

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

alphabet

_{default: ''}

Used only when the type option is set to 'custom'. Specifies the custom alphabet for sorting.

Use the Alphabet utility class from eslint-plugin-perfectionist/alphabet to quickly generate a custom alphabet.

Example: 0123456789abcdef...

ignoreCase

_{default: true}

Specifies whether sorting should be case-sensitive.

true — Ignore case when sorting alphabetically or naturally (e.g., “A” and “a” are the same).
false — Consider case when sorting (e.g., “a” comes before “A”).

specialCharacters

_{default: keep}

Specifies whether to trim, remove, or keep special characters before sorting.

'keep' — Keep special characters when sorting (e.g., “_a” comes before “a”).
'trim' — Trim special characters when sorting alphabetically or naturally (e.g., “_a” and “a” are the same).
'remove' — Remove special characters when sorting (e.g., “/a/b” and “ab” are the same).

locales

_{default: 'en-US'}

Specifies the sorting locales. Refer To String.prototype.localeCompare() - locales.

string — A BCP 47 language tag (e.g. 'en', 'en-US', 'zh-CN').
string[] — An array of BCP 47 language tags.

[DEPRECATED] ignorePattern

_{type:
{
allNamesMatchPattern?: string | string[] | { pattern: string; flags: string } | { pattern: string; flags: string }[]
}}_{default: []}

Use the useConfigurationIf.tagMatchesPattern option alongside type: unsorted instead.

Specifies names or patterns for JSX elements that should be ignored by this rule. This can be useful if you have specific components that you do not want to sort.

You can specify their names or a regexp pattern to ignore, for example: '^Table.+' to ignore all JSX elements whose names begin with the word Table.

partitionByNewLine

_{default: false}

When true, the rule will not sort members if there is an empty line between them. This helps maintain the defined order of logically separated groups of members.

newlinesBetween

_{default: 'ignore'}

Specifies how to handle new lines between groups.

ignore — Do not report errors related to new lines.
always — Enforce one new line between each group, and forbid new lines inside a group.
never — No new lines are allowed.

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.

useConfigurationIf

_{type:
{
allNamesMatchPattern?: string | string[] | { pattern: string; flags: string } | { pattern: string; flags: string }[]
tagMatchesPattern?: string | string[] | { pattern: string; flags: string } | { pattern: string; flags: string }[]
}}_{default: {}}

Specifies filters to match a particular options configuration for a given JSX element.

The first matching options configuration will be used. If no configuration matches, the default options configuration will be used.

allNamesMatchPattern — A regexp pattern that all keys must match.

Example configuration:

{
  'perfectionist/sort-jsx-props': [
    'error',
    {
      groups: ['r', 'g', 'b'], // Sort tag with colors keys by RGB
      customGroups: {
        r: '^r$',
        g: '^g$',
        b: '^b$',
      },
      useConfigurationIf: {
        allNamesMatchPattern: '^r|g|b$',
      },
    },
    {
      type: 'alphabetical' // Fallback configuration
    }
  ],
}

tagMatchesPattern — A regexp pattern that the JSX tag must match.

Example configuration:

{
  'perfectionist/sort-jsx-props': [
    'error',
    {
      type: 'unsorted', // Do not sort Component elements
      useConfigurationIf: {
        tagMatchesPattern: '*Component$',
      },
    },
    {
      type: 'alphabetical' // Fallback configuration
    }
  ],
}

groups

_{type: Array<string | string[]>}_{default: []}

Specifies a list of JSX props groups for sorting. Groups help organize props into categories, making your components more readable and maintainable.

Each element will be assigned a single group specified in the groups option (or the unknown group if no match is found). The order of items in the groups option determines how groups are ordered.

Within a given group, members will be sorted according to the type, order, ignoreCase, etc. options.

Individual groups can be combined together by placing them in an array. The order of groups in that array does not matter. All members of the groups in the array will be sorted together as if they were part of a single group.

Predefined groups are characterized by a single selector and potentially multiple modifiers. You may enter modifiers in any order, but the selector must always come at the end.

List of selectors

The only selector possible for this rule is prop.

Modifiers

multiline — Matches multiline props.
shorthand — Matches shorthand props, which are used without a value, typically for boolean props.

Example: shorthand-prop.

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: 'always',
  groups: [
    'a',
    { newlinesBetween: 'never' }, // Overrides the global newlinesBetween option
    'b',
  ]
}

customGroups

Migrating from the old API

Support for the object-based customGroups option is deprecated.

Migrating from the old to the current API is easy:

Old API:

{
  "key1": "value1",
  "key2": "value2"
}

Current API:

[
  {
    "groupName": "key1",
    "elementNamePattern": "value1"
  },
  {
    "groupName": "key2",
    "elementNamePattern": "value2"
  }
]

_{type: Array<CustomGroupDefinition | CustomGroupAnyOfDefinition>}_{default: []}

Defines custom groups to match specific JSX prop.

A custom group definition may follow one of the two following interfaces:

interface CustomGroupDefinition {
  groupName: string
  type?: 'alphabetical' | 'natural' | 'line-length' | 'unsorted'
  order?: 'asc' | 'desc'
  fallbackSort?: { type: string; order?: 'asc' | 'desc'; sortBy?: 'name' | 'value' }
  newlinesInside?: 'always' | 'never'
  selector?: string
  modifiers?: string[]
  elementNamePattern?: string | string[] | { pattern: string; flags?: string } | { pattern: string; flags?: string }[]
  elementValuePattern?: string | string[] | { pattern: string; flags?: string } | { pattern: string; flags?: string }[]
}

A JSX prop will match a CustomGroupDefinition group if it matches all the filters of the custom group’s definition.

or:

interface CustomGroupAnyOfDefinition {
  groupName: string
  type?: 'alphabetical' | 'natural' | 'line-length' | 'unsorted'
  order?: 'asc' | 'desc'
  fallbackSort?: { type: string; order?: 'asc' | 'desc'; sortBy?: 'name' | 'value' }
  newlinesInside?: 'always' | 'never'
  anyOf: Array<{
      selector?: string
      modifiers?: string[]
      elementNamePattern?: string | string[] | { pattern: string; flags?: string } | { pattern: string; flags?: string }[]
      elementValuePattern?: string | string[] | { pattern: string; flags?: string } | { pattern: string; flags?: string }[]
  }>
}

A JSX prop will match a CustomGroupAnyOfDefinition group if it matches all the filters of at least one of the anyOf items.

Attributes

groupName — The group’s name, which needs to be put in the groups option.
selector — Filter on the selector of the element.
modifiers — Filter on the modifiers of the element. (All the modifiers of the element must be present in that list)
elementNamePattern — If entered, will check that the name of the element matches the pattern entered.
elementValuePattern — If entered, will check that the value of the element matches the pattern entered.
type — Overrides the type option for that custom group. unsorted will not sort the group.
order — Overrides the order option for that custom group.
fallbackSort — Overrides the fallbackSort option for that custom group.
newlinesInside — Enforces a specific newline behavior between elements of the group.

Match importance

The customGroups list is ordered: The first custom group definition that matches an element will be used.

Custom groups have a higher priority than any predefined group.

Example

 {
   groups: [
     'multiline-prop',
     'unknown',
     'shorthand-prop',
+    'callback',
   ],
+  customGroups: [     
+    {                 
+      groupName: 'callback',
+      elementNamePattern: '^on.+'
+    }                 
+  ]                   
 }

Usage

Version

This rule was introduced in v0.2.0.