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

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

We write API for React components, part 2: let's name the behavior, not the way of interaction

We write API for React components, part 3: the order of props is important
')
Writing an API for React components, part 4: beware of Apropacalypse!

Writing an 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 the Writing good component API , written by @Sid . When translating, in any incomprehensible situation, I will be guided by the official translation of React JS documentation into Russian

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

A good API should be understandable, so that the developer himself can guess how to work with it. This applies not only to the development of component libraries, but also to the development of applications. 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 by Sebastian Markbåge , Brent Jackson , Jenn Creighton and A. Jesse Jiryu Davis .

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

Let's start with the simple.

We have a button:

<Button>Click me</Button> 

You may also need a basic button that is needed for the main action on the page. I used to like to build an API, as if I could say “Give me the main button”:

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

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

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

 <Button primary destructive> Click me </Button> 

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 primary destructive button"?

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

For the one who decides what the API will be, it is important:

1. minimize errors
2. minimize confusion around api

So here's tip number one: don't create conflicting props.

We can fix the above code quite easily using prop which will allow us to get a list of options. Let's call its 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 options for appearance using prop-types (props 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.

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

 :   :  `prop` `appearance`   `danger`   `Button`,      : `["default", "primary", "secondary", "link", "destructive"]` 

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

From the translator - I will update the list of articles in this series (at the beginning) as they are translated and new articles are released.