docs(guide): update properties section and add virtual note to api

ionic-team · brandyscarney · Sep 24, 2025 · Aug 1, 2025 · Aug 6, 2025 · Aug 8, 2025
commit 6c48d366acf80cfea9ddfbe811662e22df2cd8f3
@@ -54,20 +54,26 @@ Developers can use standard events such as `click` as they normally would. Howev
 
 ## Properties
 
-[Properties (`@Prop`)](https://stenciljs.com/docs/properties) are custom attributes exposed publically on an HTML element. They allow developers to pass data to a component to render or otherwise use.
+Properties are JavaScript properties that can be set on Ionic components to configure their behavior and appearance. Properties are defined in each component's [API documentation](/docs/api) page.
 
-### Virtual Properties
+### Reactive Properties
+
+Reactive properties automatically update the component when their values change. These are the most common type of property in Ionic components.
 
-In Ionic components, virutal properties are a special category of properties that are used to define inputs to a component without the reactivity that typically comes with `@Prop` decorated properties in Stencil.
+```html
+<ion-button color="primary">Primary Button</ion-button>
+```
 
-Unlike `@Prop` inputs:
+The `color` property is a reactive property that configures how the button appears. If you change the `color` value after the initial render, the button will update to reflect the new value.
+
+### Virtual Properties
 
-- Virtual properties do not trigger a re-render when updated.
-- They cannot be mutated to produce side effects in the component lifecycle.
-- They are not tracked for changes and do not participate in Stencil's reactive data flow.
+Virtual properties are designed for one-time configuration during component initialization. They do not trigger re-renders when updated.
 
-#### When to Use Virtual Properties
+```html
+<ion-button mode="ios">iOS Style Button</ion-button> <ion-button mode="md">Material Design Button</ion-button>
+```
 
-Virtual properties are intended for use cases where you need to pass static or read-only data into a component, like configuration options or values that won't change during the component's lifecycle. They offer a lightweight alternative when you don't need Stencil's change detection or DOM updates.
+The `mode` property is a virtual property that determines which platform styles to use for a component. It can be set at the component level or globally through the app configuration. In both cases, it's set once during initialization and doesn't change during the component's lifecycle.
 
-Because they are not reactive, updates to virtual properties after initial load will not affect the rendered output of the component.
+For more information on Ionic modes, read the [Platform Styles documentation](/docs/theming/platform-styles).
@@ -134,18 +134,41 @@ function formatType(attr, type) {
   return type.replace(/\|/g, '\uff5c');
 }
 
-function renderProperties({ props: properties }) {
+function renderProperties({ props: properties, docsTags }) {
   if (properties.length === 0) {
     return 'No properties available for this component.';
   }
 
+  // Extract virtual property names from component-level docsTags
+  const virtualPropNames = [];
+  if (docsTags) {
+    docsTags.forEach((tag) => {
+      if (tag.name === 'virtualProp') {
+        // Check if any property name exists in the virtualProp tag text
+        // and add it to the virtualPropNames array
+        properties.forEach((prop) => {
+          if (tag.text.includes(prop.name)) {
+            virtualPropNames.push(prop.name);
+          }
+        });
+      }
+    });
+  }
+
   // NOTE: replaces | with U+FF5C since MDX renders \| in tables incorrectly
   return `
 ${properties
   .map((prop) => {
     const isDeprecated = prop.deprecation !== undefined;
+    const isVirtual = virtualPropNames.includes(prop.name);
 
-    const docs = isDeprecated ? `${prop.docs}\n\n**_Deprecated_** — ${prop.deprecation}` : prop.docs;
+    let docs = prop.docs;
+    if (isVirtual) {
+      docs = `${docs}\n\nThis is a [virtual property](/docs/core-concepts/fundamentals#virtual-properties) that is set once during initialization and will not update if you change its value after the initial render.`;
+    }
+    if (isDeprecated) {
+      docs = `${docs}\n\n**_Deprecated_** — ${prop.deprecation}`;
+    }
 
     return `
 ### ${prop.name} ${isDeprecated ? '(deprecated)' : ''}

@@ -38,3 +38,35 @@ Projects such as <a href="https://capacitorjs.com/" target="_blank">Capacitor</a
 ## Theming
 
 At the core, Ionic Framework is built using <a href="https://developer.mozilla.org/en-US/docs/Web/CSS" target="_blank">CSS</a> which allows us to take advantage of the flexibility that <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_variables" target="_blank">CSS properties (variables)</a> provide. This makes it incredibly easy to design an app that looks great while following the web standard. We provide a set of colors so developers can have some great defaults, but we encourage overriding them to create designs that match a brand, company or a desired color palette. Everything from the background color of an application to the text color is fully customizable. More information on app theming can be found in [Theming](../theming/basics.md).
+
+## Events
+
+Many Ionic components use [CustomEvent](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent) to inform developers of important state changes in the components. For example, an `ion-datetime` component will emit `ionChange` whenever the selected date has changed.
+
+Developers can use standard events such as `click` as they normally would. However, many events emitted within a component's [shadow root](../reference/glossary.md#shadow) will be [retargeted](https://dom.spec.whatwg.org/#retarget) to the host element. This may result in multiple `click` handlers executing even if the user only clicked once. As a result, developers should rely on Ionic's events to be properly informed of state changes on Ionic components. Ionic's events are prefixed with `ion` to avoid collisions with standard events. Each component's documentation page has a list of available events that developers can listen for in their applications.
+
+## Properties
+
+Properties are JavaScript properties that can be set on Ionic components to configure their behavior and appearance. Properties are defined in each component's [API documentation](/docs/api) page.
+
+### Reactive Properties
+
+Reactive properties automatically update the component when their values change. These are the most common type of property in Ionic components.
+
+```html
+<ion-button color="primary">Primary Button</ion-button>
+```
+
+The `color` property is a reactive property that configures how the button appears. If you change the `color` value after the initial render, the button will update to reflect the new value.
+
+### Virtual Properties
+
+Virtual properties are designed for one-time configuration during component initialization. They do not trigger re-renders when updated.
+
+```html
+<ion-button mode="ios">iOS Style Button</ion-button> <ion-button mode="md">Material Design Button</ion-button>
+```
+
+The `mode` property is a virtual property that determines which platform styles to use for a component. It can be set at the component level or globally through the app configuration. In both cases, it's set once during initialization and doesn't change during the component's lifecycle.
+
+For more information on Ionic modes, read the [Platform Styles documentation](/docs/theming/platform-styles).
@@ -45,3 +45,35 @@ Projects such as <a href="https://capacitorjs.com/" target="_blank">Capacitor</a
 ## Theming
 
 At the core, Ionic Framework is built using <a href="https://developer.mozilla.org/en-US/docs/Web/CSS" target="_blank">CSS</a> which allows us to take advantage of the flexibility that <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_variables" target="_blank">CSS properties (variables)</a> provide. This makes it incredibly easy to design an app that looks great while following the web standard. We provide a set of colors so developers can have some great defaults, but we encourage overriding them to create designs that match a brand, company or a desired color palette. Everything from the background color of an application to the text color is fully customizable. More information on app theming can be found in [Theming](../theming/basics.md).
+
+## Events
+
+Many Ionic components use [CustomEvent](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent) to inform developers of important state changes in the components. For example, an `ion-datetime` component will emit `ionChange` whenever the selected date has changed.
+
+Developers can use standard events such as `click` as they normally would. However, many events emitted within a component's [shadow root](../reference/glossary.md#shadow) will be [retargeted](https://dom.spec.whatwg.org/#retarget) to the host element. This may result in multiple `click` handlers executing even if the user only clicked once. As a result, developers should rely on Ionic's events to be properly informed of state changes on Ionic components. Ionic's events are prefixed with `ion` to avoid collisions with standard events. Each component's documentation page has a list of available events that developers can listen for in their applications.
+
+## Properties
+
+Properties are JavaScript properties that can be set on Ionic components to configure their behavior and appearance. Properties are defined in each component's [API documentation](/docs/api) page.
+
+### Reactive Properties
+
+Reactive properties automatically update the component when their values change. These are the most common type of property in Ionic components.
+
+```html
+<ion-button color="primary">Primary Button</ion-button>
+```
+
+The `color` property is a reactive property that configures how the button appears. If you change the `color` value after the initial render, the button will update to reflect the new value.
+
+### Virtual Properties
+
+Virtual properties are designed for one-time configuration during component initialization. They do not trigger re-renders when updated.
+
+```html
+<ion-button mode="ios">iOS Style Button</ion-button> <ion-button mode="md">Material Design Button</ion-button>
+```
+
+The `mode` property is a virtual property that determines which platform styles to use for a component. It can be set at the component level or globally through the app configuration. In both cases, it's set once during initialization and doesn't change during the component's lifecycle.
+
+For more information on Ionic modes, read the [Platform Styles documentation](/docs/theming/platform-styles).
@@ -51,3 +51,29 @@ At the core, Ionic Framework is built using <a href="https://developer.mozilla.o
 Many Ionic components use [CustomEvent](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent) to inform developers of important state changes in the components. For example, an `ion-datetime` component will emit `ionChange` whenever the selected date has changed.
 
 Developers can use standard events such as `click` as they normally would. However, many events emitted within a component's [shadow root](../reference/glossary.md#shadow) will be [retargeted](https://dom.spec.whatwg.org/#retarget) to the host element. This may result in multiple `click` handlers executing even if the user only clicked once. As a result, developers should rely on Ionic's events to be properly informed of state changes on Ionic components. Ionic's events are prefixed with `ion` to avoid collisions with standard events. Each component's documentation page has a list of available events that developers can listen for in their applications.
+
+## Properties
+
+Properties are JavaScript properties that can be set on Ionic components to configure their behavior and appearance. Properties are defined in each component's [API documentation](/docs/api) page.
+
+### Reactive Properties
+
+Reactive properties automatically update the component when their values change. These are the most common type of property in Ionic components.
+
+```html
+<ion-button color="primary">Primary Button</ion-button>
+```
+
+The `color` property is a reactive property that configures how the button appears. If you change the `color` value after the initial render, the button will update to reflect the new value.
+
+### Virtual Properties
+
+Virtual properties are designed for one-time configuration during component initialization. They do not trigger re-renders when updated.
+
+```html
+<ion-button mode="ios">iOS Style Button</ion-button> <ion-button mode="md">Material Design Button</ion-button>
+```
+
+The `mode` property is a virtual property that determines which platform styles to use for a component. It can be set at the component level or globally through the app configuration. In both cases, it's set once during initialization and doesn't change during the component's lifecycle.
+
+For more information on Ionic modes, read the [Platform Styles documentation](/docs/theming/platform-styles).