Write Self Documenting React Props with TypeScript Basic Types and Inline Comments

Shawn Wang
InstructorShawn Wang

Share this video with your friends

Send Tweet
Published 4 years ago
Updated 2 years ago

TypeScript's Basic Types are worth exploring with a view toward practical usage in React Components. Furthermore, you can comment your components and your types and have them show up in your tooling, for example your IDE, or even autogenerated documentation for your design system.

Instructor: [00:00] Let's discuss how the basic types in TypeScript may be useful in various conditions in React components. Here, I have a list of props that I've passed into my Button component. We're just going to go through them one by one.

[00:15] The first one is the string type. This has all the properties of strings as you might expect. You might see some older guides tell you to type readonly for your properties, but that's not really necessary.

[00:29] When it's passed in as a generic to React.Component, it's already cast as a readonly type. If I try to assign this, it's going to tell me that it is a readonly property. You don't have to explicitly assign it readonly. You can if you want to.

[00:45] Next, we have the number type. This type behaves as you might expect. Likewise, the Boolean type doesn't allow any other properties, apart from valueOf.

[00:55] To accept arrays of types, you simply particular square brackets beside any of the existing types. Then you have access to the array methods of them. What's more, once you call map on an array type, you get access to the underlying type as well. Here, I have an array of Booleans, as defined in my new props. The underlying function is inferred to be a Boolean. That's very helpful.

[01:24] String props are often used to represent multiple states, for example, failed, success, or waiting. However, it's not very robust to typos, where this would immediately fall through to the else statement.

[01:40] It's not great for autocomplete or logic checking. What might be better is using string literals, where only exact strings are specified. Here, if I refactor this, then I immediately know that I'm trying to assign a string that is not expected.

[01:58] Furthermore, TypeScript understands conditional logic. If I'm in the else block after I've already checked for one part of the string literals, the remaining statuses are all that is available to me, even though the actual prop has three states.

[02:15] There are many ways to type objects. If you don't really care what the object's shape is and you're just passing it on to another function or component, you can just type it with the keyword object or an empty object shape and just pass it on as per normal.

[02:33] If you try to access it, it's not going to let you fill in anything because nothing's valid. Nothing is a member of that object. If you actually want to use your object inside of your component, you should specify what the object shape is. Then you'll have access to the object properties without TypeScript complaining.

[02:55] Arrays of objects also behave just like the other array methods as well, where the inner object is exposed once we perform an array method on it. Similarly, to objects, if you are just taking in a function and you don't really care what the call signature is, then you can just call it a function and pass it on or pass it or call it without arguments.

[03:19] The problem comes when you try to call it with arguments because TypeScript doesn't recognize that there are any arguments to this function. Functions that don't return anything are assumed to return void. If you want to define arguments, you define it as though you are defining the function itself. Then here, you can just call it with the appropriate type.

[03:38] The self-documenting nature of TypeScript extends beyond just type annotations. You can also comment inline to have it pop up in your tooling. For example, in VS Code, you can see the comments that are laid right next to your properties. You can use multiline comments, as well as Markdown.

[04:10] For more ideas on things you can type, head over to the TypeScript Handbook and look up documentation for tuples, enums, and many other type combinations.