/*@jsxRuntime automatic @jsxImportSource react*/
const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];
function _createMdxContent(props) {
  const _components = Object.assign({
    p: "p",
    h2: "h2",
    code: "code",
    strong: "strong"
  }, props.components), {Code} = _components;
  if (!Code) _missingMdxReference("Code", true);
  return _jsxs(_Fragment, {
    children: [_jsx(_components.p, {
      children: "Through building component libraries over the years, my team at SparkPost have created React components that are both hated and loved by our engineers. We noticed patterns and conventions that work, and some that don't."
    }), "\n", _jsx(_components.p, {
      children: "The following is an attempt to document some of our opinions on these patterns, to ensure we're creating the best developer experience possible."
    }), "\n", _jsx(_components.h2, {
      children: "Composition"
    }), "\n", _jsxs(_components.p, {
      children: ["Use ", _jsx(_components.code, {
        children: "props.children"
      }), " to enable component composition. This limits the API surface area of a component and allows prop naming to become more predictable."]
    }), "\n", _jsx(Code, {
      code: `
// Dont' do
<ActionList actions={[{ content: 'Content', onClick }]} />

<Avatar size="sm" fallbackColor="blue" imageSrc={src} imageAlt="Text" />
`
    }), "\n", _jsx(Code, {
      code: `
// Do
<ActionList>
  <ActionList.Action onClick={onClick}>Content</ActionList.Action>
</ActionList>

<Avatar size="sm" color="blue">
  <Avatar.Image src={src} alt="Text" />
</Avatar>
`
    }), "\n", _jsx(_components.h2, {
      children: "Native Attributes"
    }), "\n", _jsxs(_components.p, {
      children: ["Native attributes or common props, such as ", _jsx(_components.code, {
        children: "className"
      }), ", ", _jsx(_components.code, {
        children: "id"
      }), " or ", _jsx(_components.code, {
        children: "onClick"
      }), ", should not be renamed. Don't force your engineers to learn APIs they already know."]
    }), "\n", _jsx(Code, {
      code: `
// Don't do
const Component = (props) => {
  return (
    <div
      id={props.componentId}
      onClick={props.handleClick}
    />
  )
}
`
    }), "\n", _jsx(Code, {
      code: `
// Do
const Component = (props) => {
  return <div {...props} />;
}
`
    }), "\n", _jsx(_components.h2, {
      children: "Prop Consistency"
    }), "\n", _jsx(_components.p, {
      children: "Prop names and enumerable prop values with similar functionality across different components should be consistent."
    }), "\n", _jsx(Code, {
      code: `
// Don't do
<Stack align="center" />
<Inline horizontalAlign="middle" />
`
    }), "\n", _jsx(Code, {
      code: `
// Do
<Stack align="center" />
<Inline align="center" />
`
    }), "\n", _jsx(_components.h2, {
      children: "Boolean Props"
    }), "\n", _jsxs(_components.p, {
      children: ["Boolean prop names should be chosen based on their ", _jsx(_components.strong, {
        children: "default value"
      }), ". For example, a ", _jsx(_components.code, {
        children: "disabled"
      }), " prop on an ", _jsx(_components.code, {
        children: "input"
      }), " element, or an ", _jsx(_components.code, {
        children: "open"
      }), " prop on an overlay."]
    }), "\n", _jsx(Code, {
      code: `
// Don't do
<Popover closed={false} />
<Button enabled={false} />
`
    }), "\n", _jsx(Code, {
      code: `
// Do
<Popover open />
<Button disabled />
`
    }), "\n", _jsx(_components.h2, {
      children: "Enums vs Booleans"
    }), "\n", _jsx(_components.p, {
      children: "Always default to enums over booleans, when the variants or permutations are mutually exclusive. This allows you to add variants without introducing new props."
    }), "\n", _jsx(Code, {
      code: `
// Don't do
<Text center /><Tag red />`
    }), "\n", _jsx(Code, {
      code: `
// Do
<Text align="center" />
<Tag color="red" />
`
    }), "\n", _jsx(_components.h2, {
      children: "Control"
    }), "\n", _jsxs(_components.p, {
      children: ["Stateful components, such as inputs or popovers, should always be able to be controlled through their APIs. For example, the state of a ", _jsx(_components.code, {
        children: "Textfield"
      }), " component could be controlled via ", _jsx(_components.code, {
        children: "value"
      }), " and ", _jsx(_components.code, {
        children: "onChange"
      }), " props, but should be able to function without them."]
    }), "\n", _jsx(_components.h2, {
      children: "Refs"
    }), "\n", _jsxs(_components.p, {
      children: ["Refs should always be forwarded, either to the outermost DOM element, or to the most applicable element of the component. For example form components should forward refs to ", _jsx(_components.code, {
        children: "<input/>"
      }), "."]
    }), "\n", _jsx(Code, {
      code: `
// Do
const Input = React.forwardRef(function Input(props, userRef) {
  return <input ref={userRef} />;
});
`
    }), "\n", _jsx(_components.h2, {
      children: "Other Conventions to Avoid"
    }), "\n", _jsx(_components.p, {
      children: "Avoid render props (or children functions), and higher order components. If you need to pass state to a component, create a reusable hook instead."
    }), "\n", _jsx(Code, {
      code: `
// Don't do
<Component>
  {(state) => <div />}
</Component>

<Component render={(state) => <div />} />
`
    }), "\n", _jsx(Code, {
      language: "javascript",
      code: `// Don't do
export default withState(Component);`
    })]
  });
}
function MDXContent(props = {}) {
  const {wrapper: MDXLayout} = props.components || ({});
  return MDXLayout ? _jsx(MDXLayout, Object.assign({}, props, {
    children: _jsx(_createMdxContent, props)
  })) : _createMdxContent(props);
}
return {
  default: MDXContent
};
function _missingMdxReference(id, component) {
  throw new Error("Expected " + (component ? "component" : "object") + " `" + id + "` to be defined: you likely forgot to import, pass, or provide it.");
}


A few React component API patterns, conventions, and guidelines

React Component API Standards

Contact