> For the complete documentation index, see [llms.txt](https://docs.aurelia.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.aurelia.io/~/revisions/NShYVVc01DvYc5bgBiwq/templates/overview/template-references.md).

# Template references

Template references in Aurelia 2 provide a powerful and flexible way to connect your HTML templates with your JavaScript or TypeScript view models. Using the ref attribute, you can easily identify and interact with specific parts of your template, making it more efficient to manipulate the DOM or access template data.

## Declaring Template References

### Basic Usage

Add the ref attribute to an HTML element within your template to create a template reference. This marks the element as a reference, allowing you to access it directly in your view model.

```html
<input type="text" ref="myInput" placeholder="First name">
```

In this example, `myInput` references the input element, which can be used both in the template and the corresponding view model.

### Accessing Reference in Template

Template references are immediately available within the template. For instance, you can display the value of the input field as follows:

```html
<p>${myInput.value}</p>
```

This binding displays the current value of the input field dynamically.

### Accessing Reference in View Model

To access the referenced element in the view model, declare a property with the same name as the reference. For TypeScript users, it's important to define the type of this property for type safety.

```typescript
export class MyApp {
  private myInput: HTMLInputElement;

  // Additional view model logic here
}
```

## Advanced Usage

### Working with Custom Elements and Attributes

Aurelia's `ref` attribute is not limited to standard HTML elements. It can also be used with custom elements and attributes to reference their component instances (view-models) or controllers.

**Custom Element Instance** Use `component.ref="expression"` to create a reference to a custom element's component instance (view-model). This was known as `view-model.ref` in Aurelia v1.

```html
<my-custom-element component.ref="customElementVm"></my-custom-element>
```

**Custom Attribute Instance** Similarly, `custom-attribute.ref="expression"` can reference a custom attribute's component instance (view-model).

```html
<div my-custom-attribute custom-attribute.ref="customAttrVm"></div>
```

**Controller Instance** For more advanced scenarios, `controller.ref="expression"` creates a reference to a custom element's controller instance.

```html
<my-custom-element controller.ref="customElementController"></my-custom-element>
```

## Practical Applications

Template references are incredibly useful for integrating with third-party libraries or when direct DOM manipulation is necessary. Instead of using traditional JavaScript queries to find elements, template references provide a more straightforward, framework-integrated approach.

{% hint style="info" %}
Leveraging template references can greatly simplify interactions with elements, particularly when integrating with libraries that require direct DOM element references. This approach promotes cleaner and more maintainable code by reducing reliance on direct DOM queries.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.aurelia.io/~/revisions/NShYVVc01DvYc5bgBiwq/templates/overview/template-references.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.