Writing an API for React components, part 1: do not create conflicting props

We write an API for React components, part 1: do not create conflicting props

We write an API for React components, part 2: give names to the behavior, and not how to interact

We write an API for React components, part 3: the order of props is important

We write an API for React components, part 4 : beware of the Apropacalypse!

We write API for React components, part 5: just use composition

We write API for React components, part 6: we create communication between components

This post is a translation of the first article in a series of articles by the Writing good component API , authored by @Sid . When translating, in any incomprehensible situation, I will be guided by the official translation of the React JS documentation into Russian

When it comes to React components, your props are your API.

A good API should be understandable so that the developer himself can figure out how to work with it. This applies not only to the development of component libraries, but also to application development. It is important that you and your team are comfortable using components and their APIs.

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

After reading many articles + lectures, and after more than a year of designing the cosmos system design , I came to these development principles.

Let's start with a simple one.

We have a button:

Click me

You may also need the main button, which is needed for the main action on the page. I used to like to build the API, as if I could say - "Give me the main button":

Click meClick me

Now, as is usually the case with buttons, you will need a few more options. Here is a table of several props for buttons:

There are several props that you can use to change the appearance of a button. What happens if someone uses them together?

  Click me

Will any of them win? What does it depend on? From the order?

Why would anyone write this? Is there a real case when you need to say "Give me a primarydestructivebutton"?

In most cases this is a mistake. But if developers at all have to ask such questions (like the ones above), this is probably not a very good API.

For those who decide what the API will be, it’s important:

1. minimize errors
2. minimize confusion around the API

So here is tip # 1: don't create conflicting props.

We can quite easily fix the above code using prop which allows you to get a list of options. Let's call it appearance(appearance)

Click meClick meClick me

We can add a list of supported options for appearanceusing prop-types .

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

Now, even if the developer makes a mistake, he will receive a warning about this in his development tool.

Click me

Внимание: неправильный тип пропа:
Недействительный `prop` `appearance` в значении `danger` присвоен в `Button`,
возможно только одно из этих значений: `["default", "primary", "secondary", "link", "destructive"]`

This tip is pretty easy to implement, but it will make your API much easier to use (and support).

From a translator - I will update the list of articles in this series (at the beginning) as more articles are translated and new ones become available.