diff --git a/src/config.ts b/src/config.ts index 2eec1855a5d9d..00c6902d54542 100644 --- a/src/config.ts +++ b/src/config.ts @@ -36,8 +36,6 @@ export const SIDEBAR = { // MOVE "Pagination": Into "Routing Rules" Reference { text: 'Pagination', link: 'en/guides/pagination' }, { text: 'RSS', link: 'en/guides/rss' }, - // MOVE "Slots": Into Astro Component Syntax - { text: 'Slots', link: 'en/guides/slots' }, { text: 'UI Frameworks', link: 'en/core-concepts/framework-components' }, { text: 'Reference', header: true, type: 'api' }, diff --git a/src/pages/en/core-concepts/astro-components.md b/src/pages/en/core-concepts/astro-components.md index 437fd8aee06f8..40e9606215e0a 100644 --- a/src/pages/en/core-concepts/astro-components.md +++ b/src/pages/en/core-concepts/astro-components.md @@ -101,6 +101,203 @@ const myFavoritePokemon = [/* ... */]; ``` +### Dynamic JSX Expressions + +Astro components can define local variables inside of the frontmatter component script. Any script variables are then automatically available in the component's HTML template below. + +#### Dynamic Values + +These local variables can be used in curly braces to pass values to be used as HTML output: + +```astro +--- +const name = "Astro"; +--- +
+

Hello {name}!

+
+``` + +#### Dynamic Attributes + +These local variables can be used in curly braces to pass attribute values to HTML elements and components: + +```astro +--- +const name = "Astro"; +--- +

Attribute expressions are supported

+ + +``` + +#### Dynamic HTML + +These local variables can be used in JSX-like functions to produce dynamically-generated HTML elements: + +```astro +--- +const items = ["Dog", "Cat", "Platipus"]; +--- + +``` + +#### Fragments & Multiple Elements + +Remember: an Astro component template can render multiple elements with no need to wrap everything in a single `
` or `<>`. + +However, when using an Astro JSX-like expression to dynamically create elements, you must wrap these multiple elements inside of a **Fragment** just like you would in JavaScript or JSX. Astro supports using either ` ` or `<> `. + +```astro +--- +const items = ["Dog", "Cat", "Platipus"]; +--- + +``` + + +### Component Props + +An Astro component can define and accept props. These props then become available to the component template for rendering HTML. Props are available on the `Astro.props` global in your frontmatter script. + +Here is an example of a component that receives a `greeting` prop and a `name` prop. Notice that the props to be received are destructured from the global `Astro.props` object. + +```astro +--- +// Example: GreetingHeadline.astro +// Usage: +const { greeting, name } = Astro.props +--- +

{greeting}, {name}!

+``` + +You can also define your props with TypeScript by exporting a `Props` type interface. Astro will automatically pick up any exported `Props` interface and give type warnings/errors for your project. These props can also be given default values when destructured from `Astro.props` + +```astro +--- +// src/components/GreetingHeadline.astro +export interface Props { + name: string; + greeting?: string; +} + +const { greeting = "Hello", name } = Astro.props +--- +

{greeting}, {name}!

+``` + +This component, when imported and rendered in other Astro components, layouts or pages, can be passed these props as attributes: + +```astro +--- +// src/components/GreetingCard.astro +import GreetingHeadline from './GreetingHeadline.astro'; +const name = "Astro" +--- +

Greeting Card

+ +

I hope you have a wonderful day!

+``` + +### Slots + +The `` element is a placeholder for HTML which will be passed in from outside of the component by "children" (as they are called in React or Preact). Slots are a way of passing data into an Astro component and are useful when you will want to reuse an "outer" component, rendered "around" data coming from an external source. + +A component that uses the `` element can be thought of as a reusable "wrapper" around other content, and this pattern is the basis of an Astro [Layout component](/en/core-concepts/layouts). + + +```astro +// src/components/Wrapper.astro +--- +import Header from './Header.astro'; +import Logo from './Logo.astro'; +import Footer from './Footer.astro'; + +const { name } = Astro.props +--- +
+
+ +

{name}

+ +
+
+ +// src/components/Person.astro + + +

I am a person.

+

Here is some stuff about me.

+
+``` + +#### Named Slots + +Slots can also be **named**. Rather than a single `` element which renders _all_ children, named slots allow you to specify multiple places where children should be placed. + +```astro +// src/components/Wrapper.astro +--- +import Header from './Header.astro'; +import Logo from './Logo.astro'; +import Footer from './Footer.astro'; + +const { name } = Astro.props +--- +
+
+ + +

{name}

+ +
+ +
+ +// src/components/Person.astro + + + +

I am a person.

+

Here is some stuff about me.

+
+ +``` +#### Fallback Content for Slots +Slots can also render **fallback content**. When there are no matching children passed to a ``, a `` element will render its own placeholder children. + +```astro +// src/components/Wrapper.astro +--- +import Header from './Header.astro'; +import Logo from './Logo.astro'; +import Footer from './Footer.astro'; + +const { name } = Astro.props +--- +
+
+ +

{name}

+ +

This is my fallback content, if there is no child passed into slot

+
+
+
+``` + ### CSS Styles CSS `