Eslint Plugin

Install the package eslint-plugin-gestalt to get lint rules encouraging the correct usage of Gestalt components

Gestalt alternatives

The following Eslint rules provide guidance on how to replace native HTML elements and attributes with available Gestalt equivalents

gestalt/prefer-box-inline-style

Prevent using <div> inline styling for attributes that are already implemented in Box.

Learn more about Box.

gestalt/prefer-box-no-disallowed

Prevent <div> tags that don't contain disallowed attributes: className and onClick. Use Gestalt Box, instead. Other attributes are disallowed as well so this Eslint rule doesn't conflict with eslint-plugin-jsx-a11y.

Read more about Box.

It also prevents <div> tags used to only contain a ref attribute. ref is supported in Box and other elements such as Button or TextField.

Read more about the ref prop in Box.

With AUTOFIX!

gestalt/prefer-box-as-tag

Prefer Box: prevent HTML tags supported in Box through the as prop.

Supported tags:

article,
aside,
details,
figcaption,
figure,
footer,
header,
main,
nav,
section,
summary.

With AUTOFIX!

Read more about the as prop in Box.

Gestalt restrictions

The following Eslint rules restrict the usage of Gestalt component props to enforce design consistency and code safety anf best practices.

gestalt/button-icon-restrictions

Require specific props when using an icon with Button. Gestalt recommends in adding icons to Buttons. Buttons using iconEnd must use:

  • icon "arrow-down"
  • color "white"
  • size "lg"

gestalt/no-box-disallowed-props

Prevent props different from

  • the officially-supported Box props

  • the following list of passthrough React / DOM props: id, key,onAnimationEnd, onAnimationIteration, onAnimationStart, onBlur, onClick, onContextMenu, onDblClick, onDoubleClick, onDrag, onDragEnd, onDragEnter, onDragExit, onDragLeave, onDragOver, onDragStart, onDrop, onFocus, onKeyDown, onKeyPress, onKeyUp, onMouseDown, onMouseEnter, onMouseLeave, onMouseMove, onMouseOut, onMouseOver, onMouseUp, onScroll, onSelect, onTouchCancel, onTouchEnd, onTouchMove, onTouchStart, onTransitionEnd, onTransitionStart, onWheel, ref, tabIndex.

gestalt/no-box-dangerous-style-duplicates

Prevent using dangerouslySetInlineStyle on Box for props that are already directly implemented.

Box supports some props already that are not widely known and instead are being implemented with dangerouslySetInlineStyle.

This linter checks for usage of already available props as dangerous styles and suggests the alternative.

With AUTOFIX!

Learn more about Box.

gestalt/no-box-useless-props

Prevent useless props combinations on Box in two categories:

  • alignContent, alignItems, direction, justifyContent, or wrap (and, if applicable, their respective responsive props) without display="flex"
  • fit and maxWidth used together, since fit sets maxWidth under the hood

gestalt/no-spread-props

Prevent spreading props in Gestalt components to enable AST codemods and usage-metrics scripts.

Instead, write the component's props out.

With AUTOFIX!

gestalt/no-medium-formfields

Disallow medium form fields. In order to have consistent form fields in production, we update all of their sizes to large and disallow medium.

Install

You'll first need to install ESLint, then install eslint-plugin-gestalt.

$ npm install eslint --save-dev
$ npm install eslint-plugin-gestalt --save-dev

or

$ yarn add --dev eslint
$ yarn add --dev eslint-plugin-gestalt

Note: If you installed ESLint globally (using the -g flag) then you must also install eslint-plugin-gestalt globally.

Usage

Add gestalt to the plugins section of your .eslintrc configuration file. You can omit the eslint-plugin- prefix:

{ "plugins": ["gestalt"] }

Then configure the rules you want to use under the rules section.

{
  "rules": {
    "gestalt/rule-name": "error"
  }
}

Development

New rules should be developed TDD-style by testing against simplified test cases first. See the *.test.js files and fixtures for examples. You can test locally by running:

yarn jest --watch eslint-plugin-gestalt/src/[name-of-test-file]

Once tests pass, you can check the rules against a project using gestalt through yarn link. For example:

cd ~/code/gestalt/packages/gestalt-eslint
yarn link
cd ~/code/project-using-gestalt
yarn link eslint-plugin-gestalt

You can now add any new rules to the project's eslint config and run eslint against the project to test your changes. Remember to unlink when you're done!

cd ~/code/project-using-gestalt
yarn unlink eslint-plugin-gestalt

Releasing

Every commit to master performs a release. See the main docs releasing information for more details.

Deprecated ESlint rules

The following Eslint rules are no longer needed.

gestalt/no-box-marginleft-marginright

Disallow marginLeft/marginRight on Box. In order to have consistent usage of marginLeft/marginRight on Box in production, we update all of them to marginStart/marginEnd.

Deprecation due to: deprecated props.

Do not allow role='link' on Button, TapArea, and IconButton in cases where an alternative with additional functionality must be used instead such as for use with a routing library.

Deprecation due to: OnLinkNavigationProvider enables external link navigation in Gestalt components.

Edit page on GitHub