When it comes to React components, props are the API that developers consume. A good API should be obvious, something the developer can guess. You want to make it easier for the developer to implement their feature and move on.

This is valid not just for developers creating component libraries, but also for developers building applications. Your team mates have to use the component API you create.

This series is inspired by the talks and articles of Sebastian Markbåge, Brent Jackson, Jenn Creighton and A. Jesse Jiryu Davis.

After consuming a bunch of articles + talks and doing an inventory of all the props we have in cosmos, I’ve come up with 7 guidelines.

Let’s start with an easy one.

We have a button here:

<Button>Click me</Button>

You probably also need a primary button to serve as your main action on a page. I used to like shaping the API just like you would say it - “Give me a primary button”

<Button>Click me</Button>
<Button primary>Click me</Button>

So pretty.

Now, as it goes with buttons, you probably need a few more. Here’s what the props table ends up looking like:

name	description	type	default
`primary`	used to indicate the main action	`boolean`	false
`secondary`	used for actions which are less important	`boolean`	false
`destructive`	indicate that the user should be cautious, example: delete	`boolean`	false
`link`	used to style button similarly to a hyperlink	`boolean`	false

There are multiple props that can be used to change the appearance of the button. What is the expected outcome if someone uses them together?

<Button primary destructive>
  Click me
</Button>

Will one of them win, which one? Is it dependent on the order?

I would always ask: Why would someone write that? Is this even a real use case - “Give me a primary destructive button”?

Most of the times, this would be by mistake. But, if the developers have to ask questions like the ones above, it’s probably not a good API.

As someone who is deciding the API, it’s your job to:

minimise mistakes
minimise confusions around the API

So here’s tip #1 for you: Don’t create conflicting props

We can fix our above code pretty easily by using one prop which allows a list of options: appearance

<Button appearance="default">Click me</Button>
<Button appearance="primary">Click me</Button>
<Button appearance="destructive">Click me</Button>

We can add a list of supported appearance using prop-types.

Button.PropTypes = {
  appearance: PropTypes.oneOf(['default', 'primary', 'secondary', 'link', 'destructive'])
}

Now, even if the developer makes a mistake, they will get a helpful warning on their developer tools.

<Button appearance="danger">Click me</Button>

Warning: Failed prop type:
Invalid prop `appearance` of value `danger` supplied to `Button`,
expected one of `["default","primary","secondary","link","destructive"]`
in Button

This tip is pretty easy to implement, but will make your API a lot easier to use (and maintain).

That was just part 1 of this series, I’ll keep sending them every once in a while along with other topics 😉

Hope this was helpful on your journey

Sid

21. Don't create conflicting props