website/docs/react/component-syntax.md
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:
You can declare a component with Component Syntax similar to how you'd declare a function:
import * as React from 'react';
component Introduction(name: string, age: number) {
return <h1>My name is {name} and I am {age} years old</h1>
}
You can use a component directly in JSX: <Introduction age={9} name="Mr. Flow" />.
There are a few important details to notice here:
Components also allow you to rename parameters, which is useful when your parameter name is not a valid JavaScript identifier:
import * as React from 'react';
component RenamedParameter(
'required-renamed' as foo: number,
'optional-renamed' as bar?: number,
'optional-with-default-renamed' as baz?: number = 3,
) {
(foo: number); // OK
(bar: number | void); // OK
(baz: number); // OK
return <div />;
}
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:
import * as React from 'react';
component OtherComponent(foo: string, bar: number) {
return foo + bar;
}
component FancyProps(
...props: {
...React.PropsOf<OtherComponent>,
additionalProp: string,
}
) {
return <OtherComponent foo={props.foo} bar={props.bar} />;
}
You can use a rest parameter with a disjoint union type to define a component that accepts one of several prop shapes. Refine the props inside the component body using the discriminant field:
import * as React from 'react';
type TextProps = {kind: 'text', text: string};
type ImageProps = {kind: 'image', src: string, alt: string};
type Props = TextProps | ImageProps;
component MediaItem(...props: Props) {
if (props.kind === 'text') {
return <span>{props.text}</span>;
} else {
return ;
}
}
Components allow you to declare optional parameters and specify defaults:
import * as React from 'react';
component OptionalAndDefaults(
color: string = "blue",
extraMessage?: string,
) {
let message = `My favorite color is ${color}.`;
if (extraMessage != null) {
message += `\n${extraMessage}`;
}
return <p>{message}</p>
}
<OptionalAndDefaults /> // No error, all of the parameters are optional!
The as operator also allows you to destructure your parameters:
import * as React from 'react';
component Destructuring(
config as {color, height}: Readonly<{color: number, height: number}>,
) { return <div /> }
Rest parameters can be destructured without using as:
import * as React from 'react';
type Props = Readonly<{ color: string, height: number }>;
component DestructuredRest(...{color, height}: Props) { return <div /> }
To access refs in components you just need to add a ref parameter.
import * as React from 'react';
component ComponentWithARef(ref: React.RefSetter<HTMLElement>) {
return <div ref={ref} />;
}
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.
Component Syntax enforces a few restrictions in components to help ensure correctness:
The return values must be a subtype of React.Node, otherwise React may crash while rendering your component.
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.
You cannot use this in a component.
You cannot define a component inside another component or a hook. This triggers the nested-component lint, because a nested component gets a new identity on every render, causing React to unmount and remount it each time. Use a regular function instead if the inner "component" doesn't use hooks, or move the component to the top level.
So these components are invalid:
import * as React from 'react';
component InvalidReturnValue() {
return new Object(); // ERROR: Value does not match `React.Node` type
}
component ImplicitReturn(someCond: boolean) { // ERROR
if (someCond) {
return <h1>Hello World!</h1>;
}
// ERROR: No return in this branch
}
component UsesThis() {
this.foo = 3; // ERROR: Accessing `this`
return null;
}
import typeof with Generic Components {#toc-import-typeof-generics}When you use import typeof on a generic component's default export, the imported type alias exposes the generic as a required type argument. This means you cannot use the imported type without supplying the argument explicitly:
// GenericComp.js
import * as React from 'react';
component MyComp<T>(data: T, render: (item: T) => React.Node) {
return render(data);
}
export default MyComp;
// Consumer.js
import typeof MyComp from './GenericComp';
type CompType = MyComp; // Error: missing 1 type argument
To preserve the polymorphism, use a namespace import typeof and index into it:
import typeof * as GenericCompModule from './GenericComp';
type CompType = GenericCompModule['default']; // Works
In your .flowconfig, under the [options] heading, add component_syntax=true.