stencil.md

   1 ---
   2 title: Stencil
   3 category: JavaScript libraries
   4 layout: 2017/sheet
   5 updated: 2019-05-08
   6 keywords:
   7   - "@Component"
   8   - "@Prop()"
   9   - "@State()"
  10   - "render()"
  11   - "componentWillLoad()"
  12   - "componentWillUpdate()"
  13   - "Templating"
  14   - "Lifecycle"
  15 intro: |
  16   [Stencil](https://github.com/ionic-team/stencil) is a compiler for web components made by the Ionic team. This guide targets Stencil v0.0.5.
  17 ---
  18
  19 ## Quick-start guide
  20 {: .-three-column}
  21
  22 ### Getting started
  23 {: .-prime}
  24
  25 #### JavaScript
  26
  27 ```js
  28 import { Component, Prop, State } from '@stencil/core'
  29
  30 @Component({
  31   tag: 'my-component',
  32   styleUrl: 'my-component.scss'
  33 })
  34 export class MyComponent {
  35   @Prop() name: string
  36   @State() isVisible: boolean = true
  37
  38   render () {
  39     return <p>I am {this.name}!</p>
  40     )
  41   }
  42 }
  43 ```
  44
  45 #### HTML
  46
  47 ```html
  48 <my-component name='Groot' />
  49 ```
  50
  51 That's the same example in the [Readme](https://github.com/ionic-team/stencil), that's as simple as you can get! Just use `<my-component>` like you would use any other HTML tag.
  52
  53 ### DOM events
  54
  55 ```js
  56 export class MyComponent {
  57   render () {
  58     return (
  59       <input
  60         onChange={(event: UIEvent) => this.inputChanged(event)}
  61       />
  62     )
  63   }
  64
  65   inputChanged (event) {
  66     console.log('input changed:', event.target.value)
  67   }
  68 }
  69 ```
  70 {: data-line="5,10,11"}
  71
  72 Stencil uses DOM events.
  73
  74 See: [Handling user input](https://stenciljs.com/docs/templating/#handling-user-input)
  75
  76 ### Multiple children
  77
  78 ```js
  79 render () {
  80   return [
  81     <h1>Hello there</h1>,
  82     <p>This component returns multiple nodes</p>
  83   ]
  84 }
  85 ```
  86 {: data-line="3,4"}
  87
  88 `render()` can return an array of elements.
  89
  90 See: [Complex template content](https://stenciljs.com/docs/templating#complex-template-content)
  91
  92 ## State
  93
  94 ### Managing state
  95
  96 ```js
  97 export class MyComponent {
  98   @State() isVisible: boolean
  99
 100   show () {
 101     this.isVisible = true
 102   }
 103 }
 104 ```
 105 {: data-line="4,5"}
 106
 107 Just do assignments. You can't do mutations though, see next section.
 108
 109 See: [Managing component state](https://stenciljs.com/docs/decorators#managing-component-state)
 110
 111 ### Updating arrays and objects
 112
 113 #### ✗ Bad
 114 ```js
 115 this.names.push('Larry')  // ⚠️
 116 this.options.show = true  // ⚠️
 117 ```
 118
 119 #### ✓ OK
 120
 121 ```js
 122 this.names = [ ...this.names, 'Larry' ]
 123 this.options = { ...this.options, show: true }
 124 ```
 125
 126 Mutable operations such as `push()` won't work. You'll need to assign a new copy.
 127
 128 See: [Updating arrays](https://stenciljs.com/docs/reactive-data/#updating-arrays)
 129
 130 ## Slots
 131
 132 ### Using slot
 133
 134 ```html
 135 <my-component>
 136   <span>Hello, friends</span>
 137 </my-component>
 138 ```
 139 {: data-line="2"}
 140
 141 #### Component
 142
 143 ```js
 144 render() {
 145   return <h1><slot /></h1>
 146 }
 147 ```
 148 {: data-line="2"}
 149
 150 You can pass JSX/HTML as child elements. Use the `slot` tag to use them inside your component.
 151
 152 See: [Slots](https://stenciljs.com/docs/templating#slots)
 153
 154 ### Multiple slots
 155
 156 ```html
 157 <my-component>
 158   <p slot='my-header'>Hello</p>
 159   <p slot='my-footer'>Thanks</p>
 160 </my-component>
 161 ```
 162 {: data-line="2,3"}
 163
 164 #### Component
 165
 166 ```js
 167 render () {
 168   return <div>
 169     <header><slot name='my-header' /></header>
 170     <footer><slot name='my-footer' /></footer>
 171   </div>
 172 }
 173 ```
 174 {: data-line="3,4"}
 175
 176 See: [Slots](https://stenciljs.com/docs/templating#slots)
 177
 178 ## Lifecycle
 179
 180 ### Lifecycle hooks
 181
 182 | Event                   | Description      |
 183 | ---                     | ---              |
 184 | `componentWillLoad()`   | Before rendering |
 185 | `componentDidLoad()`    | After rendering  |
 186 | ---                     | ---              |
 187 | `componentWillUpdate()` | Before updating  |
 188 | `componentDidUpdate()`  | After updating   |
 189 | ---                     | ---              |
 190 | `componentDidUnload()`  | After unmounting |
 191
 192 See: [Component lifecycle](https://stenciljs.com/docs/component-lifecycle)
 193
 194 ### Example
 195
 196 ```js
 197 export class MyComponent {
 198   componentWillUpdate () {
 199     console.log('updating')
 200   }
 201 }
 202 ```
 203
 204 ## References
 205
 206 - [Stencil docs](https://stenciljs.com/docs/) _(stenciljs.com)_