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/only-valid-tokens
Prevent the consumption of Gestalt tokens via hard-coded strings p.e. "var(--color-border-error)". Instead import constant from 'gestalt-design-tokens' p.e. import { TOKEN_COLOR_BORDER_ERROR } from "gestalt-design-tokens".
gestalt/prefer-box-inline-style
Prevent using <div> inline styling for attributes that are already implemented in Box.
gestalt/prefer-box-no-disallowed
Prevent <div> tags that don't contain disallowed attributes in Box: className, onClick, and any attribute not included in Box's allowed-attribute
list. Use Gestalt Box, instead. Other attributes are disallowed as well so this ESLint rule doesn't conflict with
eslint-plugin-jsx-a11y.
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,caption,details,figcaption,figure,footer,header,main,nav,section,summary.
With AUTOFIX!
gestalt/prefer-link
Prevent anchor tags that only contain attributes matching supported props in Gestalt Link.
With AUTOFIX!
gestalt/prefer-list
Prevent ul or ol list tags for basic use cases. Suggests using Gestalt List instead.
gestalt/prefer-heading
Prevent heading tags (h1 ... h6) using Gestalt Heading with the corresponding accessibilityLevel, instead.
With AUTOFIX!
Gestalt restrictions
The following ESLint rules restrict the usage of Gestalt component props to enforce design consistency, code safety and best practices.
Require a specific value when using an icon with
Button. Gestalt is more permissive than we recommend internally for adding icons to Buttons, so Buttons using iconEnd must use the "arrow-down" icon and Buttons with link role using iconEnd must use the "visit" icon.
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!
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-workflow-status-icon
Prevent the usage of 'workflow-status-[...]' icons on Icon component when the style matches one of the Status types.
gestalt/prefer-flex
Prevent Box usages in those cases where they can be replaced with Flex.
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.
gestalt/no-role-link-components
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: GlobalEventsHandlerProvider enables external link navigation in Gestalt components.