{"id":26407,"date":"2024-03-12T15:44:28","date_gmt":"2024-03-12T14:44:28","guid":{"rendered":"https:\/\/www.codemotion.com\/magazine\/?p=26407"},"modified":"2024-03-12T15:47:25","modified_gmt":"2024-03-12T14:47:25","slug":"angular-signal-queries-simplifying-dom-querying","status":"publish","type":"post","link":"https:\/\/www.codemotion.com\/magazine\/frontend\/angular-signal-queries-simplifying-dom-querying\/","title":{"rendered":"Angular Signal Queries: simplifying DOM querying"},"content":{"rendered":"\n
\n\n\n\n

<\/p>\n\n\n\n

Following Signal Inputs<\/a><\/strong> and Model Inputs<\/a><\/strong>, another Signal<\/strong> API has landed in the Angular ecosystem with the release of v17.2.0: Signal Queries<\/strong>.<\/p>\n\n\n\n

Signal Queries<\/strong> offer an alternative approach to the decorator-based queries, namely @ViewChild<\/strong><\/code>, @ViewChildren<\/strong><\/code>, @ContentChild<\/strong><\/code> and @ContentChildren<\/strong><\/code>, <\/strong>supplying query results as a Signal<\/strong>.<\/p>\n\n\n\n

With queries you can retrieve references to components, directives, DOM elements, and more. Let\u2019s see what has changed with Signal Queries.<\/strong><\/p>\n\n\n\n

\n

\u26a0\ufe0f ALERT:<\/strong> new Signal Queries <\/strong>are still in developer preview \u26a0\ufe0f<\/p>\n<\/blockquote>\n\n\n\n

\n\n\n\n

View queries<\/h2>\n\n\n\n

View queries allow you to retrieve and interact directly with elements in a component\u2019s own template, also known as view<\/strong>.<\/p>\n\n\n\n

Both @ViewChild<\/strong><\/code> and @ViewChildren<\/strong><\/code> now have a Signal<\/strong> counterpart.<\/p>\n\n\n

\n
\"\"<\/figure><\/div>\n\n\n

viewChild<\/h3>\n\n\n\n

Using the new viewChild<\/strong><\/code> function you can retrieve a single element:<\/p>\n\n\n\n

import<\/span> { Component, ElementRef, Signal, viewChild } from<\/span> '@angular\/core'<\/span>;\n<\/span><\/span>\n<\/span><\/span>@Component<\/span>({\n<\/span><\/span>  selector: 'my-component'<\/span>,\n<\/span><\/span>  standalone: true<\/span>,\n<\/span><\/span>  template: '<input #inputEl \/>'<\/span>,\n<\/span><\/mark>})\n<\/span><\/span>export<\/span> class<\/span> MyComponent {\n<\/span><\/span>  inputElement: Signal<ElementRef | undefined<\/span>> = viewChild('inputEl'<\/span>);\n<\/span><\/mark>}\n<\/span><\/span><\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre><\/div><\/div>\n\n\n\n
This function accepts every parameter that @ViewChild<\/strong><\/code> supports and offers the same functionalities, providing you deliver the query result as a Signal<\/strong>.<\/p>\n\n\n\n
If you are sure about the presence of at least one matching result, you can use the dedicated viewChild.required()<\/strong><\/code> function and get rid of undefined<\/strong><\/code>:<\/p>\n\n\n
import<\/span> { Component, ElementRef, Signal, viewChild } from<\/span> '@angular\/core'<\/span>;\n<\/span><\/span>\n<\/span><\/span>@Component<\/span>({\n<\/span><\/span>  selector: 'my-component'<\/span>,\n<\/span><\/span>  standalone: true<\/span>,\n<\/span><\/span>  template: '<input #inputEl \/>'<\/span>,\n<\/span><\/mark>})\n<\/span><\/span>export<\/span> class<\/span> MyComponent {\n<\/span><\/span>  inputElement: Signal<ElementRef> = viewChild.required('inputEl'<\/span>);\n<\/span><\/mark>}\n<\/span><\/span><\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
But be careful, when a required<\/strong> query fails to find any results, Angular<\/strong> throws a dedicated error:<\/strong><\/p>\n\n\n
\n
\"\"<\/figure><\/div>\n\n\n
viewChildren<\/h3>\n\n\n\n
Using the new viewChildren<\/strong><\/code> function you can retrieve multiple elements:<\/p>\n\n\n
import<\/span> { Component, ElementRef, Signal, viewChildren } from<\/span> '@angular\/core'<\/span>;\n<\/span><\/span>\n<\/span><\/span>@Component<\/span>({\n<\/span><\/span>  selector: 'my-component'<\/span>,\n<\/span><\/span>  standalone: true<\/span>,\n<\/span><\/span>  template: `<\/span>\n<\/span><\/span>    <input #inputEl \/><\/span>\n<\/span><\/mark><\/span>\n<\/span><\/span>    @if (showSecondInput) {<\/span>\n<\/span><\/span>      <input #inputEl \/><\/span>\n<\/span><\/mark>    }<\/span>\n<\/span><\/span>  `<\/span>,\n<\/span><\/span>})\n<\/span><\/span>export<\/span> class<\/span> MyComponent {\n<\/span><\/span>  showSecondInput = true<\/span>;\n<\/span><\/span>\n<\/span><\/span>  inputElementList: Signal<readonly ElementRef[]> = viewChildren('inputEl'<\/span>);\n<\/span><\/mark>}\n<\/span><\/span><\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
Similarly to viewChild<\/strong><\/code> API, the viewChildren<\/strong><\/code> function accepts every parameter that @ViewChildren<\/strong><\/code> supports and offers the same functionalities, providing you the query result as a Signal<\/strong>.<\/p>\n\n\n\n
When a viewChildren<\/strong><\/code> <\/strong>query does not find any result, its value is an empty array<\/strong>, this guarantees the results array to be always initialized.<\/p>\n\n\n\n
\n\n\n\n
Content queries<\/h2>\n\n\n\n
Content queries allow you to retrieve and interact directly with elements in a component\u2019s content.<\/p>\n\n\n\n
A component\u2019s content is represented by the elements provided through content projection<\/strong>, nesting elements inside the component tag in the template where it is used. For example:<\/p>\n\n\n
<my-component<\/span>><\/span>\n<\/span><\/span>  <span<\/span>><\/span> Hello ;) <\/span<\/span>><\/span>\n<\/span><\/mark>\n<\/span><\/mark>  <input<\/span> #inputEl<\/span> \/><\/span>\n<\/span><\/mark><\/my-component<\/span>><\/span>\n<\/span><\/span><\/code><\/span>Code language:<\/span> HTML, XML<\/span> (<\/span>xml<\/span>)<\/span><\/small><\/pre>\n\n\n
\n
<\/p>\n\n\n\n
Note: <\/strong>apart for the target template where the queries are performed, content queries<\/strong> APIs and view queries<\/strong> APIs work identically.
Because of that the next section of the article totally relies on the previous one.<\/p>\n\n\n\n
<\/p>\n<\/blockquote>\n\n\n\n
Similarily to our previous discussion on view queries, both @ContentChild<\/strong><\/code> and @ContentChildren<\/strong><\/code> now have as well a Signal<\/strong> counterpart.<\/p>\n\n\n
\n
\"\"<\/figure><\/div>\n\n\n
contentChild<\/h3>\n\n\n\n
Using the new contentChild<\/strong><\/code> and contentChild.required()<\/strong><\/code> functions you can retrieve a single element:<\/p>\n\n\n
import<\/span> { Component, contentChild, ElementRef, Signal } from<\/span> '@angular\/core'<\/span>;\n<\/span><\/span>\n<\/span><\/span>@Component<\/span>({\n<\/span><\/span>  selector: 'my-component'<\/span>,\n<\/span><\/span>  standalone: true<\/span>,\n<\/span><\/span>  template: `<\/span>\n<\/span><\/span>    <div><\/span>\n<\/span><\/span>      <ng-content \/><\/span>\n<\/span><\/mark>    <\/div><\/span>\n<\/span><\/span>  `<\/span>,\n<\/span><\/span>})\n<\/span><\/span>export<\/span> class<\/span> MyComponent {\n<\/span><\/span>  inputElement: Signal<ElementRef | undefined<\/span>> = contentChild('inputEl'<\/span>);\n<\/span><\/mark>\n<\/span><\/span>  inputElementReq: Signal<ElementRef> = contentChild.required('inputEl'<\/span>);\n<\/span><\/mark>}\n<\/span><\/span><\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
Identically to the viewChild<\/strong><\/code> function, when a required<\/strong> contentChild<\/strong><\/code> function query fails to find any results, Angular<\/strong> throws a dedicated error:<\/strong><\/p>\n\n\n
\n
\"\"<\/figure><\/div>\n\n\n
contentChildren<\/h3>\n\n\n\n
Using the contentChildren<\/strong><\/code> function you can retrieve multiple elements:<\/p>\n\n\n
import<\/span> { Component, contentChildren, ElementRef, Signal } from<\/span> '@angular\/core'<\/span>;\n<\/span><\/span>\n<\/span><\/span>@Component<\/span>({\n<\/span><\/span>  selector: 'my-component'<\/span>,\n<\/span><\/span>  standalone: true<\/span>,\n<\/span><\/span>  template: `<\/span>\n<\/span><\/span>    <div><\/span>\n<\/span><\/span>      <ng-content \/><\/span>\n<\/span><\/mark>    <\/div><\/span>\n<\/span><\/span>  `<\/span>,\n<\/span><\/span>})\n<\/span><\/span>export<\/span> class<\/span> MyComponent {\n<\/span><\/span>  inputElementList: Signal<readonly ElementRef[]> = contentChildren('inputEl'<\/span>);\n<\/span><\/mark>}\n<\/span><\/span><\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
Identically to the viewChildren<\/strong><\/code> function, when a contentChildren<\/strong><\/code> <\/strong>query does not find any result, its value is an empty array<\/strong>.<\/p>\n\n\n\n
\n\n\n\n
Some rules you need to be careful<\/h2>\n\n\n\n
These new functions, viewChild<\/strong><\/code>, viewChildren<\/strong><\/code>, contentChild<\/strong><\/code> and contentChildren<\/strong><\/code>, only work if used to declare queries by initializing a component or a directive property.<\/p>\n\n\n\n
Calling them outside of component and directive property initialization will produce no error, but the query will not find any result:<\/p>\n\n\n
import<\/span> { Component, ElementRef, Signal, viewChild } from<\/span> '@angular\/core'<\/span>;\n<\/span><\/span>\n<\/span><\/span>@Component<\/span>({\n<\/span><\/span>  selector: 'my-component'<\/span>,\n<\/span><\/span>  standalone: true<\/span>,\n<\/span><\/span>  template: `<\/span>\n<\/span><\/span>    <div #el><\/div><\/span>\n<\/span><\/mark>  `<\/span>,\n<\/span><\/span>})\n<\/span><\/span>export<\/span> class<\/span> MyComponent {\n<\/span><\/span>  el = viewChild('el'<\/span>); \/\/ It works!<\/span>\n<\/span><\/mark>\n<\/span><\/span>  constructor<\/span>(<\/span>) {\n<\/span><\/span>    const<\/span> myEl: Signal<undefined<\/span>> = viewChild('el'<\/span>); \/\/ No error<\/span>\n<\/span><\/mark>    console<\/span>.log(myEl()); \/\/ undefined<\/span>\n<\/span><\/mark>  }\n<\/span><\/span>}\n<\/span><\/span><\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
\n\n\n\n
Signal Queries vs Decorator Queries<\/h2>\n\n\n\n
Having the query results as Signals<\/strong> means that we can compose them with other Signals<\/strong>, using computed<\/strong><\/code> and effect<\/strong><\/code> functions.<\/p>\n\n\n\n
This is a significant advantage, as it enhances the flexibility and functionality of our codebase, leading the way to all the improvements in change detection that Signals<\/strong> brought to the framework.<\/p>\n\n\n\n
In addition to that, Signal Queries<\/strong> offer other benefits:<\/p>\n\n\n\n
When a query does not find any result its value is undefined<\/strong><\/code>, this happens commonly using Control Flow<\/a><\/strong> statement like @if<\/strong><\/code> and @for<\/strong><\/code>. 
Because of this, a viewChild<\/strong><\/code> Signal<\/strong> value type is ElementRef | undefined<\/strong><\/code>.<\/p>\n\n\n\n