Skip to main content
Version: v5 (Preview)

Your First Component

In this walkthrough you'll generate a component, preview it in the dev server, and give it a prop. Run the commands from the project you created in Installation.

Generate the Component​

Stencil's generator creates the files for a new component. Give it the component's tag name:

npx stencil generate my-greeting

It asks a few questions. Choose Component, CSS, and Usage example. It then creates these files:

src/components/my-greeting/
├── my-greeting.css
├── my-greeting.tsx
└── usage/
    └── example.md

my-greeting.tsx is the component itself:

src/components/my-greeting/my-greeting.tsx
import { Component, Host } from '@stencil/core';

@Component({
  tag: 'my-greeting',
  styleUrl: 'my-greeting.css',
  encapsulation: { type: 'shadow' },
})
export class MyGreeting {
  render() {
    return (
      <Host>
        <slot></slot>
      </Host>
    );
  }
}

usage/example.md shows how to use the component in HTML. The dev server uses it to preview the component, and it's included in the documentation that Stencil generates.

Preview It​

Start the dev server:

npm run dev

Then open http://localhost:3333/src/components/my-greeting/. The dev server renders the component from its usage example (see Component Previews). It doesn't show anything yet, because the component only renders a <slot> and the example puts nothing in it.

Give It a Prop​

Add a name prop, and render a greeting with it:

src/components/my-greeting/my-greeting.tsx
import { Component, Host, Prop } from '@stencil/core';

@Component({
  tag: 'my-greeting',
  styleUrl: 'my-greeting.css',
  encapsulation: { type: 'shadow' },
})
export class MyGreeting {
  /** Who to greet */
  @Prop() name = 'Stencil';

  render() {
    return (
      <Host>
        <p>Hello, {this.name}!</p>
        <slot></slot>
      </Host>
    );
  }
}

Save the file, and the preview shows "Hello, Stencil!" without a page reload.

Now set the prop from HTML. Change the usage example:

src/components/my-greeting/usage/example.md
# Example

```html
<my-greeting name="World"></my-greeting>
```

The preview updates to "Hello, World!".

What You Just Wrote​

The @Component() decorator tells Stencil about the component:

@Prop() makes name part of the component's public API. Stencil sets it from the name attribute in HTML, or from the name property in JavaScript, and renders the component again whenever it changes. The = 'Stencil' is its default value.

render() returns what the component displays, written in JSX. <Host> is the component's own element, and <slot> is where any content placed inside the element appears.

Here's the finished component. Change name in index.html, or edit the component itself:

index.html
<script type="module" src="./components/my-greeting/my-greeting.js"></script>

<my-greeting name="World"></my-greeting>
src/components/my-greeting/my-greeting.css
:host {
  display: block;
}

The project also includes a starter component, my-component, created by stencil init. It's another example to look at, and you can delete it.

Next Steps​

You've built and rendered your first component. To see everything a component can do, from state and events to methods and lifecycle hooks, explore the component API.

When you're ready to share your components, see Publishing to NPM for packaging, publishing, and how consumers pull your components into their own projects.

If you also want consumers to get idiomatic React, Angular, or Vue components instead of raw custom elements, see Framework Integration for generating those wrapper packages on top of your published library.

Contents

Edit this page