mirror of
https://github.com/reactjs/react.dev.git
synced 2026-02-23 20:23:08 +00:00
Initial Float docs for hoistable/semantic elements (#6486)
* Initial Float docs for hoistable/semantic elements
This commit is contained in:
David McCabe
@@ -5,7 +5,8 @@
|
||||
import cn from 'classnames';
|
||||
|
||||
interface InlineCodeProps {
|
||||
isLink: boolean;
|
||||
isLink?: boolean;
|
||||
meta?: string;
|
||||
}
|
||||
function InlineCode({
|
||||
isLink,
|
||||
|
||||
@@ -19,6 +19,7 @@ import Link from './Link';
|
||||
import {PackageImport} from './PackageImport';
|
||||
import Recap from './Recap';
|
||||
import Sandpack from './Sandpack';
|
||||
import SandpackWithHTMLOutput from './SandpackWithHTMLOutput';
|
||||
import Diagram from './Diagram';
|
||||
import DiagramGroup from './DiagramGroup';
|
||||
import SimpleCallout from './SimpleCallout';
|
||||
@@ -434,6 +435,7 @@ export const MDXComponents = {
|
||||
Recap,
|
||||
Recipes,
|
||||
Sandpack,
|
||||
SandpackWithHTMLOutput,
|
||||
TeamMember,
|
||||
TerminalBlock,
|
||||
YouWillLearn,
|
||||
|
||||
@@ -11,7 +11,10 @@ export const SUPPORTED_FILES = [AppJSPath, StylesCSSPath];
|
||||
export const createFileMap = (codeSnippets: any) => {
|
||||
return codeSnippets.reduce(
|
||||
(result: Record<string, SandpackFile>, codeSnippet: React.ReactElement) => {
|
||||
if ((codeSnippet.type as any).mdxName !== 'pre') {
|
||||
if (
|
||||
(codeSnippet.type as any).mdxName !== 'pre' &&
|
||||
codeSnippet.type !== 'pre'
|
||||
) {
|
||||
return result;
|
||||
}
|
||||
const {props} = codeSnippet.props.children;
|
||||
|
||||
85
src/components/MDX/SandpackWithHTMLOutput.tsx
Normal file
85
src/components/MDX/SandpackWithHTMLOutput.tsx
Normal file
@@ -0,0 +1,85 @@
|
||||
import {Children, memo} from 'react';
|
||||
import InlineCode from './InlineCode';
|
||||
import Sandpack from './Sandpack';
|
||||
|
||||
const ShowRenderedHTML = `
|
||||
import { renderToStaticMarkup } from 'react-dom/server';
|
||||
import formatHTML from './formatHTML.js';
|
||||
|
||||
export default function ShowRenderedHTML({children}) {
|
||||
const markup = renderToStaticMarkup(
|
||||
<html>
|
||||
<head />
|
||||
<body>{children}</body>
|
||||
</html>
|
||||
);
|
||||
return (
|
||||
<>
|
||||
<h1>Rendered HTML:</h1>
|
||||
<pre>
|
||||
{formatHTML(markup)}
|
||||
</pre>
|
||||
</>
|
||||
);
|
||||
}`;
|
||||
|
||||
const formatHTML = `
|
||||
import format from 'html-format';
|
||||
|
||||
export default function formatHTML(markup) {
|
||||
// Cheap tricks to format the HTML readably -- haven't been able to
|
||||
// find a package that runs in browser and prettifies the HTML if it
|
||||
// lacks line-breaks.
|
||||
return format(markup
|
||||
.replace('<html>', '<html>\\n')
|
||||
.replace('<head>', '<head>\\n')
|
||||
.replaceAll(/<\\/script>/g, '<\\/script>\\n')
|
||||
.replaceAll(/<style([^>]*)\\/>/g, '<style $1/>\\n\\n')
|
||||
.replaceAll(/<\\/style>/g, '\\n <\\/style>\\n')
|
||||
.replaceAll(/<link([^>]*)\\/>/g, '<link $1/>\\n')
|
||||
.replaceAll(/<meta([^/]*)\\/>/g, '<meta $1/>\\n')
|
||||
.replace('</head>', '</head>\\n')
|
||||
.replace('<body>', '<body>\\n')
|
||||
.replace('</body>', '\\n</body>\\n')
|
||||
.replace('</h1>', '</h1>\\n')
|
||||
);
|
||||
}
|
||||
`;
|
||||
|
||||
const packageJSON = `
|
||||
{
|
||||
"dependencies": {
|
||||
"react": "18.3.0-canary-6db7f4209-20231021",
|
||||
"react-dom": "18.3.0-canary-6db7f4209-20231021",
|
||||
"react-scripts": "^5.0.0",
|
||||
"html-format": "^1.1.2"
|
||||
},
|
||||
"main": "/index.js",
|
||||
"devDependencies": {}
|
||||
}
|
||||
`;
|
||||
|
||||
// Intentionally not a React component because <Sandpack> will read
|
||||
// through its childrens' props. This imitates the output of ```
|
||||
// codeblocks in MDX.
|
||||
function createFile(meta: string, source: string) {
|
||||
return (
|
||||
<pre key={meta}>
|
||||
<InlineCode meta={meta} className="language-js">
|
||||
{source}
|
||||
</InlineCode>
|
||||
</pre>
|
||||
);
|
||||
}
|
||||
|
||||
export default memo(function SandpackWithHTMLOutput(
|
||||
props: React.ComponentProps<typeof Sandpack>
|
||||
) {
|
||||
const children = [
|
||||
...Children.toArray(props.children),
|
||||
createFile('ShowRenderedHTML.js', ShowRenderedHTML),
|
||||
createFile('formatHTML.js hidden', formatHTML),
|
||||
createFile('package.json hidden', packageJSON),
|
||||
];
|
||||
return <Sandpack {...props}>{children}</Sandpack>;
|
||||
});
|
||||
@@ -32,6 +32,20 @@ They are special in React because passing the `value` prop to them makes them *[
|
||||
|
||||
---
|
||||
|
||||
## Resource and Metadata Components {/*resource-and-metadata-components*/}
|
||||
|
||||
These bulit-in browser components let you load external resources or annotate the document with metadata:
|
||||
|
||||
* [`<link>`](/reference/react-dom/components/link)
|
||||
* [`<meta>`](/reference/react-dom/components/meta)
|
||||
* [`<script>`](/reference/react-dom/components/script)
|
||||
* [`<style>`](/reference/react-dom/components/style)
|
||||
* [`<title>`](/reference/react-dom/components/title)
|
||||
|
||||
They are special in React because React can render them into the document head, suspend while resources are loading, and enact other behaviors that are described on the reference page for each specific component.
|
||||
|
||||
---
|
||||
|
||||
## All HTML components {/*all-html-components*/}
|
||||
|
||||
React supports all built-in browser HTML components. This includes:
|
||||
|
||||
228
src/content/reference/react-dom/components/link.md
Normal file
228
src/content/reference/react-dom/components/link.md
Normal file
@@ -0,0 +1,228 @@
|
||||
---
|
||||
link: "<link>"
|
||||
canary: true
|
||||
---
|
||||
|
||||
<Canary>
|
||||
|
||||
React's extensions to `<link>` are currently only available in React's canary and experimental channels. In stable releases of React `<link>` works only as a [built-in browser HTML component](https://react.dev/reference/react-dom/components#all-html-components). Learn more about [React's release channels here](/community/versioning-policy#all-release-channels).
|
||||
|
||||
</Canary>
|
||||
|
||||
<Intro>
|
||||
|
||||
The [built-in browser `<link>` component](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link) lets you use external resources such as stylesheets or annotate the document with link metadata.
|
||||
|
||||
```js
|
||||
<link rel="icon" href="favicon.ico" />
|
||||
```
|
||||
|
||||
</Intro>
|
||||
|
||||
<InlineToc />
|
||||
|
||||
---
|
||||
|
||||
## Reference {/*reference*/}
|
||||
|
||||
### `<link>` {/*link*/}
|
||||
|
||||
To link to external resources such as stylesheets, fonts, and icons, or to annotate the document with link metadata, render the [built-in browser `<link>` component](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link). You can render `<link>` from any component and React will [in most cases](#special-rendering-behavior) place the corresponding DOM element in the document head.
|
||||
|
||||
```js
|
||||
<link rel="icon" href="favicon.ico" />
|
||||
```
|
||||
|
||||
[See more examples below.](#usage)
|
||||
|
||||
#### Props {/*props*/}
|
||||
|
||||
`<link>` supports all [common element props.](/reference/react-dom/components/common#props)
|
||||
|
||||
* `rel`: a string, required. Specifies the [relationship to the resource](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel). React [treats links with `rel="stylesheet"` differently](#special-rendering-behavior) from other links.
|
||||
|
||||
These props apply when `rel="stylesheet"`:
|
||||
|
||||
* `precedence`: a string. Tells React where to rank the `<link>` DOM node relative to others in the document `<head>`, which determines which stylesheet can override the other. Its value can be (in order of precedence) `"reset"`, `"low"`, `"medium"`, `"high"`. Stylesheets with the same precedence go together whether they are `<link>` or inline `<style>` tags or loaded using the [`preload`](/reference/react-dom/preload) or [`preinit`](/reference/react-dom/preinit) functions.
|
||||
* `media`: a string. Restricts the spreadsheet to a certain [media query](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_media_queries/Using_media_queries).
|
||||
* `title`: a string. Specifies the name of an [alternative stylesheet](https://developer.mozilla.org/en-US/docs/Web/CSS/Alternative_style_sheets).
|
||||
|
||||
These props apply when `rel="stylesheet"` but disable React's [special treatment of stylesheets](#special-rendering-behavior):
|
||||
|
||||
* `disabled`: a boolean. Disables the spreadsheet.
|
||||
* `onError`: a function. Called when the stylesheet fails to load.
|
||||
* `onLoad`: a function. Called when the stylesheet finishes being loaded.
|
||||
|
||||
These props apply when `rel="preload"` or `rel="modulepreload"`:
|
||||
|
||||
* `as`: a string. The type of resource. Its possible values are `audio`, `document`, `embed`, `fetch`, `font`, `image`, `object`, `script`, `style`, `track`, `video`, `worker`.
|
||||
* `imageSrcSet`: a string. Applicable only when `as="image"`. Specifies the [source set of the image](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images).
|
||||
* `imageSizes`: a string. Applicable only when `as="image"`. Specifies the [sizes of the image](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images).
|
||||
|
||||
These props apply when `rel="icon"` or `rel="apple-touch-icon"`:
|
||||
|
||||
* `sizes`: a string. The [sizes of the icon](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images).
|
||||
|
||||
These props apply in all cases:
|
||||
|
||||
* `href`: a string. The URL of the linked resource.
|
||||
* `crossOrigin`: a string. The [CORS policy](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin) to use. Its possible values are `anonymous` and `use-credentials`. It is required when `as` is set to `"fetch"`.
|
||||
* `referrerPolicy`: a string. The [Referrer header](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link#referrerpolicy) to send when fetching. Its possible values are `no-referrer-when-downgrade` (the default), `no-referrer`, `origin`, `origin-when-cross-origin`, and `unsafe-url`.
|
||||
* `fetchPriority`: a string. Suggests a relative priority for fetching the resource. The possible values are `auto` (the default), `high`, and `low`.
|
||||
* `hrefLang`: a string. The language of the linked resource.
|
||||
* `integrity`: a string. A cryptographic hash of the resource, to [verify its authenticity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity).
|
||||
* `type`: a string. The MIME type of the linked resource.
|
||||
|
||||
Props that are **not recommended** for use with React:
|
||||
|
||||
* `blocking`: a string. If set to `"render"`, instructs the browser not to render the page until the stylesheet is loaded. React provides more fine-grained control using Suspense.
|
||||
|
||||
#### Special rendering behavior {/*special-rendering-behavior*/}
|
||||
|
||||
React will always place the DOM element corresponding to the `<link>` component within the document’s `<head>`, regardless of where in the React tree it is rendered. The `<head>` is the only valid place for `<link>` to exist within the DOM, yet it’s convenient and keeps things composable if a component representing a specific page can render `<link>` components itself.
|
||||
|
||||
There are a few exceptions to this:
|
||||
|
||||
* If the `<link>` has a `rel="stylesheet"` prop, then it has to also have a `precedence` prop to get this special behavior. This is because the order of stylesheets within the document is significant, so React needs to know how to order this stylesheet relative to others, which you specify using the `precedence` prop. If the `precedence` prop is omitted, there is no special behavior.
|
||||
* If the `<link>` has an [`itemProp`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/itemprop) prop, there is no special behavior, because in this case it doesn’t apply to the document but instead represents metadata about a specific part of the page.
|
||||
* If the `<link>` has an `onLoad` or `onError` prop, because in that case you are managing the loading of the linked resource manually within your React component.
|
||||
|
||||
#### Special behavior for stylesheets {/*special-behavior-for-stylesheets*/}
|
||||
|
||||
In addition, if the `<link>` is to a stylesheet (namely, it has `rel="stylesheet"` in its props), React treats it specially in the following ways:
|
||||
|
||||
* The component that renders `<link>` will [suspend](http://localhost:3000/reference/react/Suspense) while the stylesheet is loading.
|
||||
* If multiple components render links to the same stylesheet, React will de-duplicate them and only put a single link into the DOM. Two links are considered the same if they have the same `href` prop.
|
||||
|
||||
There are two exception to this special behavior:
|
||||
|
||||
* If the link doesn't have a `precedence` prop, there is no special behavior, because the order of stylesheets within the document is significant, so React needs to know how to order this stylesheet relative to others, which you specify using the `precedence` prop.
|
||||
* If you supply any of the `onLoad`, `onError`, or `disabled` props, there is no special behavior, because these props indicate that you are managing the loading of the stylesheet manually within your component.
|
||||
|
||||
This special treatment comes with two caveats:
|
||||
|
||||
* React will ignore changes to props after the link has been rendered. (React will issue a warning in development if this happens.)
|
||||
* React may leave the link in the DOM even after the component that rendered it has been unmounted.
|
||||
|
||||
---
|
||||
|
||||
## Usage {/*usage*/}
|
||||
|
||||
### Linking to related resources {/*linking-to-related-resources*/}
|
||||
|
||||
You can annotate the document with links to related resources such as an icon, canonical URL, or pingback. React will place this metadata within the document `<head>` regardless of where in the React tree it is rendered.
|
||||
|
||||
<SandpackWithHTMLOutput>
|
||||
|
||||
```js App.js active
|
||||
import ShowRenderedHTML from './ShowRenderedHTML.js';
|
||||
|
||||
export default function BlogPage() {
|
||||
return (
|
||||
<ShowRenderedHTML>
|
||||
<link rel="icon" href="favicon.ico" />
|
||||
<link rel="pingback" href="http://www.example.com/xmlrpc.php" />
|
||||
<h1>My Blog</h1>
|
||||
<p>...</p>
|
||||
</ShowRenderedHTML>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
</SandpackWithHTMLOutput>
|
||||
|
||||
### Linking to a stylesheet {/*linking-to-a-stylesheet*/}
|
||||
|
||||
If a component depends on a certain stylesheet in order to be displayed correctly, you can render a link to that stylesheet within the component. Your component will [suspend](http://localhost:3000/reference/react/Suspense) while the stylesheet is loading. You must supply the `precedence` prop, which tells React where to place this stylesheet relative to others — stylesheets with higher precedence can override those with lower precedence.
|
||||
|
||||
<Note>
|
||||
When you want to use a stylesheet, it can be beneficial to call the [preinit](/reference/react-dom/preinit) function. Calling this function may allow the browser to start fetching the stylesheet earlier than if you just render a `<link>` component, for example by sending an [HTTP Early Hints response](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/103).
|
||||
</Note>
|
||||
|
||||
<SandpackWithHTMLOutput>
|
||||
|
||||
```js App.js active
|
||||
import ShowRenderedHTML from './ShowRenderedHTML.js';
|
||||
|
||||
export default function SiteMapPage() {
|
||||
return (
|
||||
<ShowRenderedHTML>
|
||||
<link rel="stylesheet" href="sitemap.css" precedence="medium" />
|
||||
<p>...</p>
|
||||
</ShowRenderedHTML>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
</SandpackWithHTMLOutput>
|
||||
|
||||
### Controlling stylesheet precedence {/*controlling-stylesheet-precedence*/}
|
||||
|
||||
Stylesheets can conflict with each other, and when they do, the browser goes with the one that comes later in the document. React lets you control the order of stylesheets with the `precedence` prop. In this example, two components render stylesheets, and the one with the higher precedence goes later in the document even though the component that renders it comes earlier.
|
||||
|
||||
{/*FIXME: this doesn't appear to actually work -- I guess precedence isn't implemented yet?*/}
|
||||
|
||||
<SandpackWithHTMLOutput>
|
||||
|
||||
```js App.js active
|
||||
import ShowRenderedHTML from './ShowRenderedHTML.js';
|
||||
|
||||
export default function HomePage() {
|
||||
return (
|
||||
<ShowRenderedHTML>
|
||||
<FirstComponent />
|
||||
<SecondComponent />
|
||||
...
|
||||
</ShowRenderedHTML>
|
||||
);
|
||||
}
|
||||
|
||||
function FirstComponent() {
|
||||
return <link rel="stylesheet" href="first.css" precedence="high" />;
|
||||
}
|
||||
|
||||
function SecondComponent() {
|
||||
return <link rel="stylesheet" href="second.css" precedence="low" />;
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
</SandpackWithHTMLOutput>
|
||||
|
||||
### Deduplicated stylesheet rendering {/*deduplicated-stylesheet-rendering*/}
|
||||
|
||||
If you render the same stylesheet from multiple components, React will place only a single `<link>` in the document head.
|
||||
|
||||
<SandpackWithHTMLOutput>
|
||||
|
||||
```js App.js active
|
||||
import ShowRenderedHTML from './ShowRenderedHTML.js';
|
||||
|
||||
export default function HomePage() {
|
||||
return (
|
||||
<ShowRenderedHTML>
|
||||
<Component />
|
||||
<Component />
|
||||
...
|
||||
</ShowRenderedHTML>
|
||||
);
|
||||
}
|
||||
|
||||
function Component() {
|
||||
return <link rel="stylesheet" href="styles.css" precedence="medium" />;
|
||||
}
|
||||
```
|
||||
|
||||
</SandpackWithHTMLOutput>
|
||||
|
||||
### Annotating specific items within the document with links {/*annotating-specific-items-within-the-document-with-links*/}
|
||||
|
||||
You can use the `<link>` component with the `itemProp` prop to annotate specific items within the document with links to related resources. In this case, React will *not* place these annotations within the document `<head>` but will place them like any other React component.
|
||||
|
||||
```js
|
||||
<section itemScope>
|
||||
<h3>Annotating specific items</h3>
|
||||
<link itemProp="author" href="http://example.com/" />
|
||||
<p>...</p>
|
||||
</section>
|
||||
```
|
||||
102
src/content/reference/react-dom/components/meta.md
Normal file
102
src/content/reference/react-dom/components/meta.md
Normal file
@@ -0,0 +1,102 @@
|
||||
---
|
||||
meta: "<meta>"
|
||||
canary: true
|
||||
---
|
||||
|
||||
<Canary>
|
||||
|
||||
React's extensions to `<meta>` are currently only available in React's canary and experimental channels. In stable releases of React `<meta>` works only as a [built-in browser HTML component](https://react.dev/reference/react-dom/components#all-html-components). Learn more about [React's release channels here](/community/versioning-policy#all-release-channels).
|
||||
|
||||
</Canary>
|
||||
|
||||
|
||||
<Intro>
|
||||
|
||||
The [built-in browser `<meta>` component](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta) lets you add metadata to the document.
|
||||
|
||||
```js
|
||||
<meta name="keywords" content="React, JavaScript, semantic markup, html" />
|
||||
```
|
||||
|
||||
</Intro>
|
||||
|
||||
<InlineToc />
|
||||
|
||||
---
|
||||
|
||||
## Reference {/*reference*/}
|
||||
|
||||
### `<meta>` {/*meta*/}
|
||||
|
||||
To add document metadata, render the [built-in browser `<meta>` component](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta). You can render `<meta>` from any component and React will always place the corresponding DOM element in the document head.
|
||||
|
||||
```js
|
||||
<meta name="keywords" content="React, JavaScript, semantic markup, html" />
|
||||
```
|
||||
|
||||
[See more examples below.](#usage)
|
||||
|
||||
#### Props {/*props*/}
|
||||
|
||||
`<meta>` supports all [common element props.](/reference/react-dom/components/common#props)
|
||||
|
||||
It should have *exactly one* of the following props: `name`, `httpEquiv`, `charset`, `itemProp`. The `<meta>` component does something different depending on which of these props is specified.
|
||||
|
||||
* `name`: a string. Specifies the [kind of metadata](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta/name) to be attached to the document.
|
||||
* `charset`: a string. Specifies the character set used by the document. The only valid value is `"utf-8"`.
|
||||
* `httpEquiv`: a string. Specifies a directive for processing the document.
|
||||
* `itemProp`: a string. Specifies metadata about a particular item within the document rather than the document as a whole.
|
||||
* `content`: a string. Specifies the metadata to be attached when used with the `name` or `itemProp` props or the behavior of the directive when used with the `httpEquiv` prop.
|
||||
|
||||
#### Special rendering behavior {/*special-rendering-behavior*/}
|
||||
|
||||
React will always place the DOM element corresponding to the `<meta>` component within the document’s `<head>`, regardless of where in the React tree it is rendered. The `<head>` is the only valid place for `<meta>` to exist within the DOM, yet it’s convenient and keeps things composable if a component representing a specific page can render `<meta>` components itself.
|
||||
|
||||
There is one exception to this: if `<meta>` has an [`itemProp`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/itemprop) prop, there is no special behavior, because in this case it doesn’t represent metadata about the document but rather metadata about a specific part of the page.
|
||||
|
||||
---
|
||||
|
||||
## Usage {/*usage*/}
|
||||
|
||||
### Annotating the document with metadata {/*annotating-the-document-with-metadata*/}
|
||||
|
||||
You can annotate the document with metadata such as keywords, a summary, or the author’s name. React will place this metadata within the document `<head>` regardless of where in the React tree it is rendered.
|
||||
|
||||
```html
|
||||
<meta name="author" content="John Smith" />
|
||||
<meta name="keywords" content="React, JavaScript, semantic markup, html" />
|
||||
<meta name="description" content="API reference for the <meta> component in React DOM" />
|
||||
```
|
||||
|
||||
You can render the `<meta>` component from any component. React will put a `<meta>` DOM node in the document `<head>`.
|
||||
|
||||
<SandpackWithHTMLOutput>
|
||||
|
||||
```js App.js active
|
||||
import ShowRenderedHTML from './ShowRenderedHTML.js';
|
||||
|
||||
export default function SiteMapPage() {
|
||||
return (
|
||||
<ShowRenderedHTML>
|
||||
<meta name="keywords" content="React" />
|
||||
<meta name="description" content="A site map for the React website" />
|
||||
<h1>Site Map</h1>
|
||||
<p>...</p>
|
||||
</ShowRenderedHTML>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
</SandpackWithHTMLOutput>
|
||||
|
||||
### Annotating specific items within the document with metadata {/*annotating-specific-items-within-the-document-with-metadata*/}
|
||||
|
||||
You can use the `<meta>` component with the `itemProp` prop to annotate specific items within the document with metadata. In this case, React will *not* place these annotations within the document `<head>` but will place them like any other React component.
|
||||
|
||||
```js
|
||||
<section itemScope>
|
||||
<h3>Annotating specific items</h3>
|
||||
<meta itemProp="description" content="API reference for using <meta> with itemProp" />
|
||||
<p>...</p>
|
||||
</section>
|
||||
```
|
||||
149
src/content/reference/react-dom/components/script.md
Normal file
149
src/content/reference/react-dom/components/script.md
Normal file
@@ -0,0 +1,149 @@
|
||||
---
|
||||
script: "<script>"
|
||||
canary: true
|
||||
---
|
||||
|
||||
<Canary>
|
||||
|
||||
React's extensions to `<script>` are currently only available in React's canary and experimental channels. In stable releases of React `<script>` works only as a [built-in browser HTML component](https://react.dev/reference/react-dom/components#all-html-components). Learn more about [React's release channels here](/community/versioning-policy#all-release-channels).
|
||||
|
||||
</Canary>
|
||||
|
||||
<Intro>
|
||||
|
||||
The [built-in browser `<script>` component](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script) lets you add a script to your document.
|
||||
|
||||
```js
|
||||
<script> alert("hi!") </script>
|
||||
```
|
||||
|
||||
</Intro>
|
||||
|
||||
<InlineToc />
|
||||
|
||||
---
|
||||
|
||||
## Reference {/*reference*/}
|
||||
|
||||
### `<script>` {/*script*/}
|
||||
|
||||
To add inline or external scripts to your document, render the [built-in browser `<script>` component](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script). You can render `<script>` from any component and React will [in certain cases](#special-rendering-behavior) place the corresponding DOM element in the document head and de-duplicate identical scripts.
|
||||
|
||||
```js
|
||||
<script> alert("hi!") </script>
|
||||
<script src="script.js" />
|
||||
```
|
||||
|
||||
[See more examples below.](#usage)
|
||||
|
||||
#### Props {/*props*/}
|
||||
|
||||
`<script>` supports all [common element props.](/reference/react-dom/components/common#props)
|
||||
|
||||
It should have *either* `children` or a `src` prop.
|
||||
|
||||
* `children`: a string. The source code of an inline script.
|
||||
* `src`: a string. The URL of an external script.
|
||||
|
||||
Other supported props:
|
||||
|
||||
* `async`: a boolean. Allows the browser to defer execution of the script until the rest of the document has been processed — the preferred behavior for performance.
|
||||
* `crossOrigin`: a string. The [CORS policy](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin) to use. Its possible values are `anonymous` and `use-credentials`.
|
||||
* `fetchPriority`: a string. Lets the browser rank scripts in priority when fetching multiple scripts at the same time. Can be `"high"`, `"low"`, or `"auto"` (the default).
|
||||
* `integrity`: a string. A cryptographic hash of the script, to [verify its authenticity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity).
|
||||
* `noModule`: a boolean. Disables the script in browsers that support ES modules — allowing for a fallback script for browsers that do not.
|
||||
* `nonce`: a string. A cryptographic [nonce to allow the resource](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/nonce) when using a strict Content Security Policy.
|
||||
* `referrer`: a string. Says [what Referer header to send](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#referrerpolicy) when fetching the script and any resources that the script fetches in turn.
|
||||
* `type`: a string. Says whether the script is a [classic script, ES module, or import map](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type).
|
||||
|
||||
Props that disable React's [special treatment of scripts](#special-rendering-behavior):
|
||||
|
||||
* `onError`: a function. Called when the script fails to load.
|
||||
* `onLoad`: a function. Called when the script finishes being loaded.
|
||||
|
||||
Props that are **not recommended** for use with React:
|
||||
|
||||
* `blocking`: a string. If set to `"render"`, instructs the browser not to render the page until the scriptsheet is loaded. React provides more fine-grained control using Suspense.
|
||||
* `defer`: a string. Prevents the browser from executing the script until the document is done loading. Not compatible with streaming server-rendered components. Use the `async` prop instead.
|
||||
|
||||
#### Special rendering behavior {/*special-rendering-behavior*/}
|
||||
|
||||
React can move `<script>` components to the document's `<head>`, de-duplicate identical scripts, and [suspend](http://localhost:3000/reference/react/Suspense) while the script is loading.
|
||||
|
||||
To opt into this behavior, provide the `src` and `async={true}` props. React will de-duplicate scripts if they have the same `src`. The `async` prop must be true to allow scripts to be safely moved.
|
||||
|
||||
If you supply any of the `onLoad` or `onError` props, there is no special behavior, because these props indicate that you are managing the loading of the script manually within your component.
|
||||
|
||||
This special treatment comes with two caveats:
|
||||
|
||||
* React will ignore changes to props after the script has been rendered. (React will issue a warning in development if this happens.)
|
||||
* React may leave the script in the DOM even after the component that rendered it has been unmounted. (This has no effect as scripts just execute once when they are inserted into the DOM.)
|
||||
|
||||
---
|
||||
|
||||
## Usage {/*usage*/}
|
||||
|
||||
### Rendering an external script {/*rendering-an-external-script*/}
|
||||
|
||||
If a component depends on certain scripts in order to be displayed correctly, you can render a `<script>` within the component.
|
||||
|
||||
If you supply an `src` and `async` prop, your component will suspend while the script is loading. React will de-duplicate scripts that have the same `src`, inserting only one of them into the DOM even if multiple components render it.
|
||||
|
||||
<SandpackWithHTMLOutput>
|
||||
|
||||
```js App.js active
|
||||
import ShowRenderedHTML from './ShowRenderedHTML.js';
|
||||
|
||||
function Map({lat, long}) {
|
||||
return (
|
||||
<>
|
||||
<script async src="map-api.js" />
|
||||
<div id="map" data-lat={lat} data-long={long} />
|
||||
</>
|
||||
);
|
||||
}
|
||||
|
||||
export default function Page() {
|
||||
return (
|
||||
<ShowRenderedHTML>
|
||||
<Map />
|
||||
</ShowRenderedHTML>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
</SandpackWithHTMLOutput>
|
||||
|
||||
<Note>
|
||||
When you want to use a script, it can be beneficial to call the [preinit](/reference/react-dom/preinit) function. Calling this function may allow the browser to start fetching the script earlier than if you just render a `<script>` component, for example by sending an [HTTP Early Hints response](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/103).
|
||||
</Note>
|
||||
|
||||
### Rendering an inline script {/*rendering-an-inline-script*/}
|
||||
|
||||
To include an inline script, render the `<script>` component with the script source code as its children. Inline scripts are not de-duplicated or moved to the document `<head>`, and since they don't load any external resources, they will not cause your component to suspend.
|
||||
|
||||
<SandpackWithHTMLOutput>
|
||||
|
||||
```js App.js active
|
||||
import ShowRenderedHTML from './ShowRenderedHTML.js';
|
||||
|
||||
function Tracking() {
|
||||
return (
|
||||
<script>
|
||||
ga('send', 'pageview');
|
||||
</script>
|
||||
);
|
||||
}
|
||||
|
||||
export default function Page() {
|
||||
return (
|
||||
<ShowRenderedHTML>
|
||||
<h1>My Website</h1>
|
||||
<Tracking />
|
||||
<p>Welcome</p>
|
||||
</ShowRenderedHTML>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
</SandpackWithHTMLOutput>
|
||||
106
src/content/reference/react-dom/components/style.md
Normal file
106
src/content/reference/react-dom/components/style.md
Normal file
@@ -0,0 +1,106 @@
|
||||
---
|
||||
style: "<style>"
|
||||
canary: true
|
||||
---
|
||||
|
||||
<Canary>
|
||||
|
||||
React's extensions to `<style>` are currently only available in React's canary and experimental channels. In stable releases of React `<style>` works only as a [built-in browser HTML component](https://react.dev/reference/react-dom/components#all-html-components). Learn more about [React's release channels here](/community/versioning-policy#all-release-channels).
|
||||
|
||||
</Canary>
|
||||
|
||||
<Intro>
|
||||
|
||||
The [built-in browser `<style>` component](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/style) lets you add inline CSS stylesheets to your document.
|
||||
|
||||
```js
|
||||
<style> p { color: red; } </style>
|
||||
```
|
||||
|
||||
</Intro>
|
||||
|
||||
<InlineToc />
|
||||
|
||||
---
|
||||
|
||||
## Reference {/*reference*/}
|
||||
|
||||
### `<style>` {/*style*/}
|
||||
|
||||
To add inline styles to your document, render the [built-in browser `<style>` component](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/style). You can render `<style>` from any component and React will [in certain cases](#special-rendering-behavior) place the corresponding DOM element in the document head and de-duplicate identical styles.
|
||||
|
||||
```js
|
||||
<style> p { color: red; } </style>
|
||||
```
|
||||
|
||||
[See more examples below.](#usage)
|
||||
|
||||
#### Props {/*props*/}
|
||||
|
||||
`<style>` supports all [common element props.](/reference/react-dom/components/common#props)
|
||||
|
||||
* `children`: a string, required. The contents of the stylesheet.
|
||||
* `precedence`: a string. Tells React where to rank the `<style>` DOM node relative to others in the document `<head>`, which determines which stylesheet can override the other. Its value can be (in order of precedence) `"reset"`, `"low"`, `"medium"`, `"high"`. Stylesheets with the same precedence go together whether they are `<link>` or inline `<style>` tags or loaded using the [`preload`](/reference/react-dom/preload) or [`preinit`](/reference/react-dom/preinit) functions.
|
||||
* `href`: a string. Allows React to [de-duplicate styles](#special-rendering-behavior) that have the same `href`.
|
||||
* `media`: a string. Restricts the spreadsheet to a certain [media query](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_media_queries/Using_media_queries).
|
||||
* `nonce`: a string. A cryptographic [nonce to allow the resource](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/nonce) when using a strict Content Security Policy.
|
||||
* `title`: a string. Specifies the name of an [alternative stylesheet](https://developer.mozilla.org/en-US/docs/Web/CSS/Alternative_style_sheets).
|
||||
|
||||
Props that are **not recommended** for use with React:
|
||||
|
||||
* `blocking`: a string. If set to `"render"`, instructs the browser not to render the page until the stylesheet is loaded. React provides more fine-grained control using Suspense.
|
||||
|
||||
#### Special rendering behavior {/*special-rendering-behavior*/}
|
||||
|
||||
React can move `<style>` components to the document's `<head>`, de-duplicate identical stylesheets, and [suspend](http://localhost:3000/reference/react/Suspense) while the stylesheet is loading.
|
||||
|
||||
To opt into this behavior, provide the `href` and `precedence` props. React will de-duplicate styles if they have the same `href`. The precedence prop tells React where to rank the `<style>` DOM node relative to others in the document `<head>`, which determines which stylesheet can override the other.
|
||||
|
||||
This special treatment comes with two caveats:
|
||||
|
||||
* React will ignore changes to props after the style has been rendered. (React will issue a warning in development if this happens.)
|
||||
* React may leave the style in the DOM even after the component that rendered it has been unmounted.
|
||||
|
||||
---
|
||||
|
||||
## Usage {/*usage*/}
|
||||
|
||||
### Rendering an inline CSS stylesheet {/*rendering-an-inline-css-stylesheet*/}
|
||||
|
||||
If a component depends on certain CSS styles in order to be displayed correctly, you can render an inline stylesheet within the component.
|
||||
|
||||
If you supply an `href` and `precedence` prop, your component will suspend while the stylesheet is loading. (Even with inline stylesheets, there may be a loading time due to fonts and images that the stylesheet refers to.) The `href` prop should uniquely identify the stylesheet, because React will de-duplicate stylesheets that have the same `href`.
|
||||
|
||||
<SandpackWithHTMLOutput>
|
||||
|
||||
```js App.js active
|
||||
import ShowRenderedHTML from './ShowRenderedHTML.js';
|
||||
import { useId } from 'react';
|
||||
|
||||
function PieChart({data, colors}) {
|
||||
const id = useId();
|
||||
const stylesheet = colors.map((color, index) =>
|
||||
`#${id} .color-${index}: \{ color: "${color}"; \}`
|
||||
).join();
|
||||
return (
|
||||
<>
|
||||
<style href={"PieChart-" + JSON.stringify(colors)} precedence="medium">
|
||||
{stylesheet}
|
||||
</style>
|
||||
<svg id={id}>
|
||||
…
|
||||
</svg>
|
||||
</>
|
||||
);
|
||||
}
|
||||
|
||||
export default function App() {
|
||||
return (
|
||||
<ShowRenderedHTML>
|
||||
<PieChart data="..." colors={['red', 'green', 'blue']} />
|
||||
</ShowRenderedHTML>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
</SandpackWithHTMLOutput>
|
||||
98
src/content/reference/react-dom/components/title.md
Normal file
98
src/content/reference/react-dom/components/title.md
Normal file
@@ -0,0 +1,98 @@
|
||||
---
|
||||
title: "<title>"
|
||||
canary: true
|
||||
---
|
||||
|
||||
<Canary>
|
||||
|
||||
React's extensions to `<title>` are currently only available in React's canary and experimental channels. In stable releases of React `<title>` works only as a [built-in browser HTML component](https://react.dev/reference/react-dom/components#all-html-components). Learn more about [React's release channels here](/community/versioning-policy#all-release-channels).
|
||||
|
||||
</Canary>
|
||||
|
||||
|
||||
<Intro>
|
||||
|
||||
The [built-in browser `<title>` component](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/title) lets you specify the title of the document.
|
||||
|
||||
```js
|
||||
<title>My Blog</title>
|
||||
```
|
||||
|
||||
</Intro>
|
||||
|
||||
<InlineToc />
|
||||
|
||||
---
|
||||
|
||||
## Reference {/*reference*/}
|
||||
|
||||
### `<title>` {/*title*/}
|
||||
|
||||
To specify the title of the document, render the [built-in browser `<title>` component](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/title). You can render `<title>` from any component and React will always place the corresponding DOM element in the document head.
|
||||
|
||||
```js
|
||||
<title>My Blog</title>
|
||||
```
|
||||
|
||||
[See more examples below.](#usage)
|
||||
|
||||
#### Props {/*props*/}
|
||||
|
||||
`<title>` supports all [common element props.](/reference/react-dom/components/common#props)
|
||||
|
||||
* `children`: `<title>` accepts only text as a child. This text will become the title of the document. You can also pass your own components as long as they only render text.
|
||||
|
||||
#### Special rendering behavior {/*special-rendering-behavior*/}
|
||||
|
||||
React will always place the DOM element corresponding to the `<title>` component within the document’s `<head>`, regardless of where in the React tree it is rendered. The `<head>` is the only valid place for `<title>` to exist within the DOM, yet it’s convenient and keeps things composable if a component representing a specific page can render its `<title>` itself.
|
||||
|
||||
There are two exception to this:
|
||||
* If `<title>` is within an `<svg>` component, then there is no special behavior, because in this context it doesn’t represent the document’s title but rather is an [accessibility annotation for that SVG graphic](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/title).
|
||||
* If the `<title>` has an [`itemProp`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/itemprop) prop, there is no special behavior, because in this case it doesn’t represent the document’s title but rather metadata about a specific part of the page.
|
||||
|
||||
<Pitfall>
|
||||
|
||||
Only render a single `<title>` at a time. If more than one component renders a `<title>` tag at the same time, React will place all of those titles in the document head. When this happens, the behavior of browsers and search engines is undefined.
|
||||
|
||||
</Pitfall>
|
||||
|
||||
---
|
||||
|
||||
## Usage {/*usage*/}
|
||||
|
||||
### Set the document title {/*set-the-document-title*/}
|
||||
|
||||
Render the `<title>` component from any component with text as its children. React will put a `<title>` DOM node in the document `<head>`.
|
||||
|
||||
<SandpackWithHTMLOutput>
|
||||
|
||||
```js App.js active
|
||||
import ShowRenderedHTML from './ShowRenderedHTML.js';
|
||||
|
||||
export default function ContactUsPage() {
|
||||
return (
|
||||
<ShowRenderedHTML>
|
||||
<title>My Site: Contact Us</title>
|
||||
<h1>Contact Us</h1>
|
||||
<p>Email us at support@example.com</p>
|
||||
</ShowRenderedHTML>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
</SandpackWithHTMLOutput>
|
||||
|
||||
### Use variables in the title {/*use-variables-in-the-title*/}
|
||||
|
||||
The children of the `<title>` component must be a single string of text. (Or a single number or a single object with a `toString` method.) It might not be obvious, but using JSX curly braces like this:
|
||||
|
||||
```js
|
||||
<title>Results page {pageNumber}</title> // 🔴 Problem: This is not a single string
|
||||
```
|
||||
|
||||
... actually causes the `<title>` component to get a two-element array as its children (the string `"Results page"` and the value of `pageNumber`). This will cause an error. Instead, use string interpolation to pass `<title>` a single string:
|
||||
|
||||
```js
|
||||
<title>{`Results page ${pageNumber}`}</title>
|
||||
```
|
||||
|
||||
@@ -218,6 +218,31 @@
|
||||
{
|
||||
"title": "<textarea>",
|
||||
"path": "/reference/react-dom/components/textarea"
|
||||
},
|
||||
{
|
||||
"title": "<link>",
|
||||
"path": "/reference/react-dom/components/link",
|
||||
"canary": true
|
||||
},
|
||||
{
|
||||
"title": "<meta>",
|
||||
"path": "/reference/react-dom/components/meta",
|
||||
"canary": true
|
||||
},
|
||||
{
|
||||
"title": "<script>",
|
||||
"path": "/reference/react-dom/components/script",
|
||||
"canary": true
|
||||
},
|
||||
{
|
||||
"title": "<style>",
|
||||
"path": "/reference/react-dom/components/style",
|
||||
"canary": true
|
||||
},
|
||||
{
|
||||
"title": "<title>",
|
||||
"path": "/reference/react-dom/components/title",
|
||||
"canary": true
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
Reference in New Issue
Block a user