> For the complete documentation index, see [llms.txt](https://docs.umbraco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-types/collections/collection-view/reference.md).

# Reference View

When you want to display entities as a list of references within a collection, use the Reference Collection View Kind. This will render a basic list layout. Each item renders a default layout with the entity's name and icon. You can further customize the item layout by registering a custom Ref Collection Item when needed.

The Reference Collection View renders items produced by a [Collection](/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-types/collections/collection.md). The collection is responsible for fetching items through its [Collection Repository](/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-types/collections/collection.md#collection-repository).

Each item renders fields from your collection item model. For details on defining and extending the item model, see [Collection](/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-types/collections/collection.md#item-model).

Register the Reference Collection View in the extension registry with the kind set to "ref":

## Manifest

{% code title="umbraco-package.json" %}

```json
{
  "type": "collectionView",
  "kind": "ref",
  "alias": "My.CollectionView.Ref",
  "name": "My Ref Collection View",
  "conditions": [
    {
      "alias": "Umb.Condition.CollectionAlias",
      "match": "My.Collection" // Collection alias to display this collection view for
    }
  ]
}
```

{% endcode %}

## Custom Reference Collection Item

If you want to customize how each item is rendered, you can create and register a custom Ref Collection Item.

### Manifest

{% code title="umbraco-package.json" %}

```json
{
  "type": "entityCollectionItemRef",
  "alias": "My.EntityCollectionItemRef.EntityType",
  "name": "My Entity Type Collection Item Ref",
  "element": "/App_Plugins/my-collection/ref/my-entity-type-collection-item-ref.element.js",
  "forEntityTypes": ["my-entity-type"]
}
```

{% endcode %}

### Implementation

Implement your custom Ref Collection Item as a Lit element that extends `UmbLitElement`. This defines how an individual item is rendered in the collection.

Get more information on Reference elements and base element starting points at the [UI Library documentation](https://uui.umbraco.com/?path=/docs/displays-references-ref--docs)

```typescript
export interface MyCollectionItemModel extends UmbCollectionItemModel {
  // Add custom properties here
}
```

{% code title="my-entity-type-collection-item-ref.element.ts" %}

```typescript
import type { MyCollectionItemModel } from './types.ts';
import type { UmbEntityCollectionItemElement } from '@umbraco-cms/backoffice/collection'
import { UmbDeselectedEvent, UmbSelectedEvent } from '@umbraco-cms/backoffice/event';
import { customElement, html, property } from '@umbraco-cms/backoffice/external/lit';
import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';

@customElement('my-entity-type-collection-item-ref')
export class MyEntityTypeCollectionItemRefElement extends UmbLitElement implements UmbEntityCollectionItemElement {
	@property({ type: Object })
	item?: MyCollectionItemModel;

	@property({ type: Boolean })
	selectable = false;

	@property({ type: Boolean })
	selected = false;

	@property({ type: Boolean })
	selectOnly = false;

	@property({ type: Boolean })
	disabled = false;

	@property({ type: String })
	href?: string;

	#onSelected(event: CustomEvent) {
		if (!this.item) return;
		event.stopPropagation();
		this.dispatchEvent(new UmbSelectedEvent(this.item.unique));
	}

	#onDeselected(event: CustomEvent) {
		if (!this.item) return;
		event.stopPropagation();
		this.dispatchEvent(new UmbDeselectedEvent(this.item.unique));
	}

	override render() {
		if (!this.item) return nothing;
		return html`<div>My Custom Ref for ${this.item.entityType}:${this.item.unique}</div>`;
	}
}

declare global {
	interface HTMLElementTagNameMap {
		'my-entity-type-collection-item-ref': MyEntityTypeCollectionItemRefElement;
	}
}
```

{% endcode %}


---

# 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.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-types/collections/collection-view/reference.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.