From 0f781d2bbd4ba98dbdd60a3f9eae53d9de2d7f15 Mon Sep 17 00:00:00 2001
From: Luke Latham <1622880+guardrex@users.noreply.github.com>
Date: Thu, 15 Dec 2022 09:29:50 -0600
Subject: [PATCH] Update custom elements guidance (#27912)

* Update custom elements guidance

* Updates

* Updates

* Updates
---
 aspnetcore/blazor/components/index.md | 70 +++++++++++++++------------
 1 file changed, 38 insertions(+), 32 deletions(-)

diff --git a/aspnetcore/blazor/components/index.md b/aspnetcore/blazor/components/index.md
index cf4d734bbc..6e558d6977 100644
--- a/aspnetcore/blazor/components/index.md
+++ b/aspnetcore/blazor/components/index.md
@@ -1521,40 +1521,11 @@ Blazor custom elements:
 
 Custom elements don't support [child content](#child-content-render-fragments) or [templated components](xref:blazor/components/templated-components).
 
-### Pass parameters
+### Package
 
-Pass parameters to your Blazor component either as HTML attributes or as JavaScript properties on the DOM element.
+Add a package reference for [`Microsoft.AspNetCore.Components.CustomElements`](https://www.nuget.org/packages/Microsoft.AspNetCore.Components.CustomElements) to the app's project file.
 
-Consider the following integer parameter declaration:
-
-```csharp
-[Parameter]
-public int IncrementAmount { get; set; }
-```
-
-Pass a value to the preceding parameter as an HTML attribute:
-
-```html
-<custom-blazor-counter increment-amount="123"></custom-blazor-counter>
-```
-
-The attribute name adopts kebab-case syntax (`increment-amount`, not `IncrementAmount`).
-
-Alternatively, you can set the parameter's value as a JavaScript property on the element object:
-
-```javascript
-const elem = document.querySelector("custom-blazor-counter");
-elem.incrementAmount = 123;
-```
-
-The property name adopts camel case syntax (`incrementAmount`, not `IncrementAmount`).
-
-You can update parameter values at any time using either attribute or property syntax.
-
-Supported parameter types:
-
-* Using JavaScript property syntax, you can pass objects of any JSON-serializable type.
-* Using HTML attributes, you are limited to passing objects of string, boolean, or numerical types.
+[!INCLUDE[](~/includes/package-reference.md)]
 
 ### Blazor Server registration
 
@@ -1593,6 +1564,41 @@ For a complete example of how to create custom elements with Blazor, see the [`C
 
 [!INCLUDE[](~/includes/aspnetcore-repo-ref-source-links.md)]
 
+### Pass parameters
+
+Pass parameters to your Blazor component either as HTML attributes or as JavaScript properties on the DOM element.
+
+Consider the following integer parameter declaration:
+
+```csharp
+[Parameter]
+public int IncrementAmount { get; set; }
+```
+
+Pass a value to the preceding parameter as an HTML attribute:
+
+```html
+<my-counter increment-amount="123"></custom-blazor-counter>
+```
+
+The attribute name adopts kebab-case syntax (`increment-amount`, not `IncrementAmount`).
+
+Alternatively, you can set the parameter's value as a JavaScript property on the element object:
+
+```javascript
+const elem = document.querySelector("my-counter");
+elem.incrementAmount = 123;
+```
+
+The property name adopts camel case syntax (`incrementAmount`, not `IncrementAmount`).
+
+You can update parameter values at any time using either attribute or property syntax.
+
+Supported parameter types:
+
+* Using JavaScript property syntax, you can pass objects of any JSON-serializable type.
+* Using HTML attributes, you are limited to passing objects of string, boolean, or numerical types.
+
 ## Generate Angular and React components
 
 Generate framework-specific JavaScript (JS) components from Razor components for web frameworks, such as Angular or React. This capability isn't included with .NET, but is enabled by the support for rendering Razor components from JS. The [JS component generation sample on GitHub](https://github.com/aspnet/samples/tree/main/samples/aspnetcore/blazor/JSComponentGeneration) demonstrates how to generate Angular and React components from Razor components. See the GitHub sample app's `README.md` file for additional information.