Add docs for defaultValue

Author: Steve Orvell

packages/lit-dev-content/samples/properties/attributereflect/my-element.ts

@@ -1,24 +1,40 @@
-import {LitElement, html, css} from 'lit';
+import {LitElement, html, css, PropertyDeclaration} from 'lit';
 import {customElement, property} from 'lit/decorators.js';
 
 @customElement('my-element')
 class MyElement extends LitElement {
   @property({type: Boolean, reflect: true})
   active: boolean = false;
 
+  @property({type: String, reflect: true, defaultValue: 'normal'} as PropertyDeclaration)
+  variant!: string|null;
+
   static styles = css`
     :host {
-      display: inline-block;
+      display: inline-block; padding: 4px;
     }
-
     :host([active]) {
-      border: 1px solid red;
+      font-weight: 800;
+    }
+    :host([variant]) {
+      outline: 4px solid green;
+    }
+    :host([variant="special"]) {
+      border-radius: 8px; border: 4px solid red;
     }`;
 
   render() {
     return html`
-      <span>Active: ${this.active}</span>
-      <button @click="${() => this.active = !this.active}">Toggle active</button>
+      <div><label>active: <input type="checkbox"
+        .value="${this.active}"
+        @change="${(e: Event) => this.active = (e.target! as HTMLInputElement).checked}">
+        ${this.active}
+      </label></div>
+      <div><label>variant: <input type="checkbox"
+        .value="${this.variant === 'special'}"
+        @change="${(e: Event) => this.variant = (e.target! as HTMLInputElement).checked ? 'special' : 'normal'}">
+        ${this.variant}
+      </label></div>
     `;
   }
 }

packages/lit-dev-content/site/docs/v3/components/properties.md

@@ -129,10 +129,13 @@ class MyElement extends LitElement {
 }
 ```
 
-In **JavaScript**, you **must not use class fields** when declaring reactive properties. Instead, properties must be initialized in the element constructor:
+In **JavaScript**, you **must not use class fields** when declaring reactive properties. Instead, properties must be either initialized in the element constructor or set with the `defaultValue` option:
 ```js
 class MyElement extends LitElement {
-  static properties = {foo: {type: String}}
+  static properties = {
+    foo: {type: String},
+    bar: {type: String, defaultValue: 'Default'}
+  }
   constructor() {
     super();
     this.foo = 'Default';
@@ -219,6 +222,18 @@ A [custom converter](#conversion-converter) for converting between properties an
 </dd>
 <dt>
 
+`defaultValue`
+
+</dt>
+<dd>
+
+When set, the property is initialized to this value and if the `reflect` option is `true`, the initial default value does *not* reflect. Subsequent changes to the property will reflect, even if they are equal to the default value.
+
+Avoid setting both a default value and defining a field initializer or setting the property in the constructor or connectedCallback.
+
+</dd>
+<dt>
+
 `hasChanged`
 
 </dt>
@@ -553,11 +568,16 @@ If this behavior doesn't fit your use case, there are a couple of options:
 
 You can configure a property so that whenever it changes, its value is reflected to its [corresponding attribute](#observed-attributes). Reflected attributes are useful because attributes are visible to CSS, and to DOM APIs like `querySelector`.
 
+Note, if you set a `defaultValue` for the property, this value will *not* be initially reflected to the corresponding attribute. All subsequent changes will be reflected. This matches web platform behavior for attributes like `id`. For example, the default value of an element's `id` property is `''` (an empty string) and initially it does not have an `id` attribute, but if the `id` property is set (even to an empty string), the appropirate `id` attribute is reflected.
+
 For example:
 
 ```js
 // Value of property "active" will reflect to attribute "active"
 active: {reflect: true}
+// Value of property "variant" will reflect except that it will not
+// be initialized to the default value of `normal`.
+variant: {reflect: true, defaultValue: 'normal'}
 ```
 
 When the property changes, Lit sets the corresponding attribute value as described in [Using the default converter](#conversion-type) or [Providing a custom converter](#conversion-converter).