Component Syntax

Components are the foundation for building UIs in React. While components are typically expressed using JavaScript functions, Component Syntax provides component primitive values that provide several advantages over function components, like:

1. More elegant syntax with significantly less verbosity and boilerplate than functions
2. Type system support tailored specifically for writing React
3. Better support for React refs

Basic Usage

You can declare a component with Component Syntax similar to how you'd declare a function:

1import * as React from 'react';2
3component Introduction(name: string, age: number) {4  return <h1>My name is {name} and I am {age} years old</h1>5}

You can use a component directly in JSX: <Introduction age={9} name="Mr. Flow" />.

There are a few important details to notice here:

1. the prop parameter names declared in the Introduction component are the same as the prop names passed to Introduction in JSX
2. the order of the parameters in the declaration does not need to match the order that they are provided in JSX

Parameters

String Parameters/Renaming Parameters

Components also allow you to rename parameters, which is useful when your parameter name is not a valid JavaScript identifier:

1import * as React from 'react';2
3component RenamedParameter(4  'required-renamed' as foo: number,5  'optional-renamed' as bar?: number,6  'optional-with-default-renamed' as baz?: number = 3,7) {8  (foo: number); // OK9  (bar: number | void); // OK10  (baz: number); // OK11
12  return <div />;13}

Rest Parameters

Sometimes you do not want to list out every prop explicitly because you do not intend to reference them individually in your component. This is common when you are writing a component that wraps another and need to pass props from your component to the inner one:

import * as React from 'react';

import type {Props as StarProps} from './Star';
import Star from './Star';

component BlueStar(...props: StarProps) {
  return <Star {...props} color="blue" />;
}

Rest parameters use an object type as an annotation, which means you can use existing type utilities like object spreads and Pick to annotate more complex prop patterns:

1import * as React from 'react';2
3component OtherComponent(foo: string, bar: number) {4  return foo + bar;5}6
7component FancyProps(8  ...props: {9    ...React.PropsOf<OtherComponent>,10    additionalProp: string,11  }12) {13  return <OtherComponent foo={props.foo} bar={props.bar} />;14}

Optional Parameters and Defaults

Components allow you to declare optional parameters and specify defaults:

1import * as React from 'react';2
3component OptionalAndDefaults(4  color: string = "blue",5  extraMessage?: string,6) {7  let message = `My favorite color is ${color}.`;8  if (extraMessage != null) {9    message += `\n${extraMessage}`;10  }11  return <p>{message}</p>12}13
14<OptionalAndDefaults /> // No error, all of the parameters are optional!

Destructuring Parameters

The as operator also allows you to destructure your parameters:

1import * as React from 'react';2
3component Destructuring(4  config as {color, height}: $ReadOnly<{color: number, height: number}>,5) { return <div /> }

Rest parameters can be destructured without using as:

1import * as React from 'react';2
3type Props = $ReadOnly<{ color: string, height: number }>;4
5component DestructuredRest(...{color, height}: Props) { return <div /> }

Ref Parameters

To access refs in components you just need to add a ref parameter.

1import * as React from 'react';2
3component ComponentWithARef(ref: React.RefSetter<HTMLElement>) {4  return <div ref={ref} />;5}

Behind the scenes Component Syntax will wrap the component in the required React.forwardRef call to ensure the component works as expected at runtime. The one restriction for refs is they must be defined as an inline parameter, refs within rest params are not supported. This is due to the need to compile in the forwardRef call, for this to work correctly we need to be able to statically determine the ref from the component definition.

Elements of Components

For components declared in Component Syntax, you can use ComponentName to reference the type of an element of that component. For components not using Component Syntax you have to write React.Element<typeof ComponentName>.

1import * as React from 'react';2
3declare component Foo();4declare component Bar();5
6const foo: Foo = <Foo />;7const bar: Bar = <Foo />; // ERROR
                     

7:19-7:21: Cannot assign `<Foo />` to `bar` because component Foo [1] is incompatible with component Bar [2] in type argument `ElementType` [3]. [incompatible-type-arg]

The syntax also works for generic components:

1import * as React from 'react';2
3declare component Foo<T>(prop: T);4
5const foo1: Foo<string> = <Foo prop="" />;6const foo2: Foo<number> = <Foo prop="" />; // Invalid generic type argument
                                         7const foo3: Foo = <Foo prop="" />; // Missing generic type argument
               

6:27-6:41: Cannot assign `<Foo />` to `foo2` because string [1] is incompatible with number [2] in property `prop` of type argument `P` [3]. [incompatible-type-arg]
7:13-7:15: Cannot use component Foo [1] without 1 type argument. [missing-type-arg]

We do not recommend requiring very specific type of elements. It will make your parent and children components more coupled. Instead, this feature is designed to make expressing render types easier.

Rules for Components

Component Syntax enforces a few restrictions in components to help ensure correctness:

1. The return values must be a subtype of React.Node, otherwise React may crash while rendering your component.
2. All branches of a component must end in an explicit return. Even though undefined is a valid return value, we've seen many instances where an explicit return would have prevented bugs in production.
3. You cannot use this in a component.

So these components are invalid:

1import * as React from 'react';2
3component InvalidReturnValue() {4  return new Object(); // ERROR: Value does not match `React.Node` type
                     5}6
7component ImplicitReturn(someCond: boolean) {
                                           8  if (someCond) {9    return <h1>Hello World!</h1>;10  }11  // ERROR: No return in this branch12}13
14component UsesThis() {15  this.foo = 3; // ERROR: Accessing `this`
      
          16  return null;17}

4:10-4:21: Cannot return `new Object()` because: [incompatible-return] Either `Object` [1] is incompatible with `React.Element` [2]. Or `Object` [1] is incompatible with `React.Portal` [3]. Or property `@@iterator` is missing in `Object` [1] but exists in `$Iterable` [4].
7:1-7:43: Cannot declare component because component ImplicitReturn [1] is not guaranteed to reach a return statement. An explicit return statement must be included for all possible branches. [component-missing-return]
15:3-15:6: Cannot reference `this` from within component declaration [1] [component-this-reference]
15:8-15:10: Cannot assign `3` to `this.foo` because property `foo` is missing in global object [1]. [prop-missing]