# Angular Primitives Documentation

> Angular Primitives is a collection of unstyled, accessible Angular components and utilities for building design systems and web applications. Built with Angular, TypeScript, and a focus on accessibility, customization, and developer experience. It provides headless UI primitives that can be styled with any CSS framework or design system.

Generated on: 2026-01-20T10:15:01.614Z

---

## Getting-started

### Get Started

File: getting-started/get-started.md
URL: https://angularprimitives.com/getting-started/get-started

# Get Started

## Installation

Angular Primitives is distributed as a single package with entrypoints for each primitive.
This makes it easy to install and update, while keeping the bundle size as small as possible.

<tab-group>
  <tab-item label="Angular CLI">
    To install Angular Primitives using the Angular CLI, run the following command:

```bash npm
ng add ng-primitives
```

This command will install Angular Primitives and add the necessary dependencies to your project.

  </tab-item>

  <tab-item label="Nx">
    To install Angular Primitives using Nx, run the following command:

```bash npm
nx add ng-primitives
```

This command will install Angular Primitives and add the necessary dependencies to your project.

  </tab-item>

  <tab-item label="Manual Installation">
    
To manually install Angular Primitives, run the following command:

```bash npm
npm i ng-primitives
```

## Peer Dependencies

Angular Primitives relies on a few peer dependencies that need to be installed. If you are using NPM version 7 or higher, these dependencies will be installed automatically. If you are using an older version of NPM, or a different package manager, you may need to install them manually.

| Package          | Version  |
| ---------------- | -------- |
| @angular/cdk     | >=20.0.0 |
| @floating-ui/dom | >=1.6.0  |

To install these dependencies, run the following command:

```bash
npm i @angular/cdk@^21.0.0 @floating-ui/dom@^1.6.0
```

  </tab-item>
</tab-group>

## Usage

Once Angular Primitives is installed, you can start using the primitives in your Angular application.
It is best to create a reusable component that encapsulates the primitives, so that you can easily reuse it throughout your application.

Primitives can be used both within a template or as a host directive on a component giving you the flexibility to choose the best approach for your use case.

Primitives add `data-` attributes to the elements they are applied to based on their current state. This allows you to easily style the primitives using CSS without having to rely on JavaScript.


---

### Introduction

File: getting-started/introduction.md
URL: https://angularprimitives.com/getting-started/introduction

# Introduction

Angular Primitives is a low-level headless UI component library with a focus on accessibility, customization, and developer experience. Whether you're building a robust design system from scratch or looking to enhance your existing one, our primitives are here to support you every step of the way.

## Key Features

1. **Accessibility First:** We believe that all users should have equal access to information and functionality. Our primitives are crafted with accessibility best practices, ensuring that your applications are inclusive and usable by everyone.

2. **Customization Made Easy:** We understand the importance of maintaining a consistent look and feel across your applications. With Angular Primitives, we don't provide any styles, you provide your own to seamlessly blend with your brand's identity and visual guidelines.

3. **Developer Experience:** We know developers value simplicity and efficiency. Our library is designed to be intuitive and straightforward, making it a breeze for you to integrate and work with our primitives in your Angular projects. We follow the best practices and standards to ensure the highest quality code and documentation and support SSR (Server-Side Rendering) and Zoneless out of the box.

## Versioning

Angular Primitives follow [Semantic Versioning](https://semver.org/). As a result you can expect the following:

- **Patch releases** contain bug fixes and minor improvements.
- **Minor releases** contain new features and improvements.
- **Major releases** contain breaking changes.

We release a new major version each time Angular releases a new major version.
This ensures that Angular Primitives is always up-to-date with the latest Angular features and best practices.

## Compatibility

Angular Primitives versions are compatible with the following Angular versions:

| Angular Primitives | Angular        |
| ------------------ | -------------- |
| 0.1.0 - 0.18.0     | 18.x.x         |
| 0.19.0+            | 19.x.x, 20.x.x |
| 0.90.0+            | 20.x.x, 21.x.x |

### Version Support Policy

Starting from v1.0.0, Angular Primitives will support the two latest major Angular versions. For example, when Angular 21 is released, Angular Primitives will support Angular 20 and 21. New major versions will be supported upon release (typically every six months), ensuring compatibility with the latest Angular features while allowing you to upgrade independently.

## Community

If you would like to stay up-to-date with the latest news and updates, or have any questions, feedback, or suggestions, we invite you to join our community on [Discord](https://discord.gg/NTdjc5r3gC).

## Acknowledgements

Angular Primitives would not have been possible without inspiration from many of the great libraries that came before it.
We would like to thank the following projects for their contributions to the open-source community:

- [Angular CDK](https://material.angular.io/cdk)
- [Radix UI](https://radix-ui.com/)
- [Headless UI](https://headlessui.com/)
- [React Aria](https://react-spectrum.adobe.com/react-aria/)

## Support

If you have any questions, feedback, or need help, feel free to reach out to us on [GitHub](https://github.com/ng-primitives/ng-primitives). We're always happy to help and improve our library based on your feedback.

If you're interested in contributing to Angular Primitives, please check out our [Contributing Guide](https://github.com/ng-primitives/ng-primitives/blob/main/CONTRIBUTING.md).

If you would like to support Angular Primitives to help us maintain and improve the library, please consider [sponsoring us](https://github.com/sponsors/ng-primitives). Your support is greatly appreciated!


---

### llms.txt

File: getting-started/llms.md
URL: https://angularprimitives.com/getting-started/llms

# llms.txt

Angular Primitives provides comprehensive documentation files optimized for Large Language Models (LLMs) and AI assistants. These files enable AI tools to understand the component library and provide better assistance with code generation, documentation, and implementation guidance.

## Available Files

### llms.txt

A structured index file that provides an overview of all components, organized by category. This file follows industry standards and includes direct links to the live documentation.

- **File Size:** ~8KB
- **Purpose:** Quick reference and component discovery
- **Best For:** Initial exploration and finding specific components

<a href="./assets/llms/llms.txt" download="llms.txt" class="download-button">
  Download llms.txt
</a>

### llms-full.txt

A comprehensive documentation file containing the complete content of all documentation pages, including:

- Full component documentation
- Complete TypeScript source code for reusable components
- API reference tables with inputs, outputs, and properties
- Usage examples and implementation details

The llms-full.txt file is ideal for in-depth understanding and reference when working with Angular Primitives, however, due to its size, it may consume more of your AI tool's context window.

- **File Size:** ~500KB
- **Purpose:** Complete reference with all implementation details
- **Best For:** In-depth analysis and code generation, offline use or use in environments with limited internet access

<a href="./assets/llms/llms-full.txt" download="llms-full.txt" class="download-button">
  Download llms-full.txt
</a>

## Usage with AI Tools

### Cursor

Enhance your Angular Primitives development with Cursor's `@Docs` feature:

1. Type `@Docs` in your chat prompt
2. Reference the Angular Primitives documentation: `https://angularprimitives.com/assets/llms/llms.txt`
3. Ask questions about specific primitives, implementation patterns, or accessibility features

Example: _"@Docs How do I implement a custom button using Angular Primitives button primitive?"_

### Windsurf

Integrate Angular Primitives documentation in Windsurf:

- Use `https://angularprimitives.com/assets/llms/llms.txt` in your prompts for direct reference
- Add the documentation URL to your `.windsurfrules` file for persistent access across sessions
- Leverage the comprehensive API documentation for accurate code generation

### ChatGPT & Claude

Maximize AI assistance when working with Angular Primitives:

- Specify that you're building with **Angular Primitives** (headless UI library)
- Include the documentation URL: `https://angularprimitives.com/assets/llms/llms.txt` in your conversations
- The AI can then provide context-aware suggestions for primitive usage, accessibility patterns, and Angular-specific implementations

### GitHub Copilot

Copilot doesn't currently support external documentation, but you can still enhance its suggestions by:

- Mentioning that you're using **Angular Primitives** in your code comments
- Providing snippets of relevant documentation in your comments for context


---

### MCP

File: getting-started/mcp.md
URL: https://angularprimitives.com/getting-started/mcp

# Model Context Protocol (MCP)

The Angular Primitives MCP Server allows AI assistants to interact with our headless UI primitives. You can browse available components, search for specific ones, and get implementation help using natural language.

For example, you can ask an AI assistant to _"Show me all form primitives"_ or _"Add a dialog component to my Angular app"_ or _"Get the API details for the button primitive"_.

## Configuration

### Automatic Setup

```bash
npx ng g ng-primitives:mcp-setup
```

Select your AI tools and the schematic will create the necessary configuration files.

### Manual Setup

First, install the `@ng-primitives/mcp` package:

```bash
npm install @ng-primitives/mcp
```

Then, create the configuration file for your AI tool:

<tab-group>
  <tab-item label="Claude Code">
    Create `.mcp.json` in your project root:

```json
{
  "mcpServers": {
    "ngp-mcp": {
      "command": "npx",
      "args": ["-y", "@ng-primitives/mcp"]
    }
  }
}
```

  </tab-item>

  <tab-item label="Cursor">
    Create `.cursor/mcp.json` in your project root:

```json
{
  "mcpServers": {
    "ngp-mcp": {
      "command": "npx",
      "args": ["-y", "@ng-primitives/mcp"]
    }
  }
}
```

  </tab-item>

  <tab-item label="VS Code">
    Create `.vscode/mcp.json` in your project root:

```json
{
  "servers": {
    "ngp-mcp": {
      "command": "npx",
      "args": ["-y", "@ng-primitives/mcp"]
    }
  }
}
```

  </tab-item>

  <tab-item label="Codex">
    Create `.codex/config.toml` in your project root:

```toml
[mcp_servers.ngp-mcp]
command = "npx"
args = ["-y", "@ng-primitives/mcp"]
```

  </tab-item>
</tab-group>

## Example Usage

- _"Show me all form primitives"_
- _"Add a dialog to my Angular app"_
- _"What are the button primitive's inputs?"_
- _"Generate the command to create a reusable button component"_
- _"Show me reusable component implementations"_

## Troubleshooting

**MCP not responding?**

- Restart your AI tool after configuration changes
- Verify your configuration file is valid JSON/TOML


---

### Styling

File: getting-started/styling.md
URL: https://angularprimitives.com/getting-started/styling

# Styling

Unlike traditional component libraries, Angular Primitives doesn't come with any built-in styles. This is because no matter how flexible a component library's theming system is, it can never meet the needs of every project or design system.

Angular Primitives gives you a set of basic building blocks that you can structure however you want, letting you style them exactly as you like.

Sure, this means you'll need to put in more effort than you would with an off the shelf component library. If you're just looking to quickly build something without worrying much about its appearance, Angular Primitives might not be the best fit. But if you want a way to quickly create custom components that look and behave exactly the way you want, Angular Primitives is a great choice.

## Approach

Angular Primitives has an opinionated way of handling styling. Each primitive uses `data-*` attributes to reflect its important state. This lets you style the primitives based on their state using CSS, so you don't have to manually toggle classes.

This works with any styling system, whether you're using plain CSS, SCSS, or a utility-first CSS framework like Tailwind CSS.

## Example

If you are using CSS or SCSS, you can style the primitives like this:

```scss
button[data-selected] {
  background-color: blue;
  color: white;
}

button[data-disabled] {
  opacity: 0.5;
  cursor: not-allowed;
}
```

If you are using Tailwind CSS, you can style the primitives like this:

```html
<button
  class="data-disabled:cursor-not-allowed data-disabled:opacity-50 data-selected:bg-blue-500 data-selected:text-white"
  ngpToggle
>
  Toggle
</button>
```


---

### Usage

File: getting-started/usage.md
URL: https://angularprimitives.com/getting-started/usage

# Usage

Angular Primitives are built entirely using Angular directives, offering a flexible and composable way to enhance your components.

There are two main ways to use them:

- Apply the directives directly in your component templates.
- Use the directives as **host directives** in your own components.

Let’s explore both approaches, along with some limitations and the solutions we provide.

---

## Using Directives in Templates

To use a directive in a template, simply apply it to the element you want to enhance. For example, here’s how you might use the `ngpSwitch` directive:

```html
<button
  ngpSwitch
  [ngpSwitchChecked]="isChecked()"
  (ngpSwitchCheckedChange)="onSwitchChange($event)"
>
  <span ngpSwitchThumb></span>
</button>
```

This applies the `ngpSwitch` directive to the button, enabling correct behavior and accessibility. You have full control over the inputs and outputs, making this approach ideal for many use cases.

However, this method has a few limitations. Some directives — like `ngpButton` — are intended to be used on specific elements (e.g. `button`). Wrapping such elements in your own component can make it difficult for consumers to add attributes like `type`, since you'd need to expose every possible attribute as an input manually.

To solve this, you can use **host directives**.

## Using Directives as Host Directives

Host directives let you enhance your components by attaching existing directives at the class level. Here's how you can use `ngpButton` as a host directive:

```typescript
import { Component } from '@angular/core';
import { NgpButton } from 'ng-primitives/button';

@Component({
  selector: 'button[my-button]',
  template: `
    <ng-content />
  `,
  hostDirectives: [NgpButton],
})
export class MyButtonComponent {
  // You can add any additional inputs or outputs you want here
}
```

This approach allows consumers to apply attributes directly to the `button` element while still benefiting from the functionality provided by the directive.

You can also expose specific inputs and outputs from the directive to your component. For example:

```typescript
import { Component, Input } from '@angular/core';
import { NgpButton } from 'ng-primitives/button';

@Component({
  selector: 'button[my-button]',
  template: `
    <ng-content />
  `,
  hostDirectives: [{ directive: NgpButton, inputs: ['disabled'] }],
})
export class MyButtonComponent {}
```

This lets consumers bind to the `disabled` input just as if they were using `ngpButton` directly.

## Limitations & Solutions

### Programmatically setting inputs

A key limitation of host directives in Angular is that their inputs can't be set programmatically within the component. To address this, we provide two main solutions:

#### Config Providers

Some directives support configuration providers that let you set default values. For example, to configure the default expansion type for `ngpAccordion`:

```typescript
@Component({
  selector: 'my-accordion',
  template: `
    <ng-content />
  `,
  hostDirectives: [{ directive: NgpAccordion, inputs: ['type'] }],
  providers: [provideAccordionConfig({ type: 'multiple' })],
})
export class MyAccordionComponent {}
```

Consumers can still override this default by explicitly binding to the `type` input.

#### State Providers

Other directives provide a **state provider**, allowing you to programmatically control their inputs. For example:

```typescript
import { Component } from '@angular/core';
import { NgpSwitch, injectSwitchState } from 'ng-primitives/switch';

@Component({
  selector: 'my-switch',
  template: `
    <ng-content />
  `,
  hostDirectives: [NgpSwitch],
})
export class MySwitchComponent {
  private readonly state = injectSwitchState();

  constructor() {
    this.state.checked.set(true);
  }
}
```

Internally, all directive inputs are converted into **linked signals**, enabling both binding and programmatic updates.

### Splitting into Multiple Components

Some features are best implemented as multiple components. Take an accordion, for example:

```html
<my-accordion>
  <my-accordion-item label="Item 1">
    <p>Content for item 1</p>
  </my-accordion-item>

  <my-accordion-item label="Item 2">
    <p>Content for item 2</p>
  </my-accordion-item>
</my-accordion>
```

If you're using `ngpAccordion` as a directive in the `my-accordion` template, the child `my-accordion-item` components won’t be able to locate it in the dependency injection tree. This is a known Angular limitation.

To solve this, Angular Primitives supports **state hoisting**, which allows you to share directive state between components.

#### State Hoisting Example

To hoist the state of `ngpAccordion` from the `my-accordion` component:

```typescript
import { Component } from '@angular/core';
import { NgpAccordion, provideAccordionState } from 'ng-primitives/accordion';

@Component({
  selector: 'my-accordion',
  template: `
    <div ngpAccordion>
      <ng-content />
    </div>
  `,
  providers: [provideAccordionState()],
})
export class MyAccordionComponent {}
```

Now, child directives like `ngpAccordionItem` can correctly locate and interact with the hoisted `ngpAccordion` state.


---

## Interactions

### Focus Visible

File: interactions/focus-visible.md
URL: https://angularprimitives.com/interactions/focus-visible

# Focus Visible

Determine whether an element should display a visible focus indicator and exposes the origin of that focus (keyboard, mouse, touch, program).
This is useful for accessibility and user experience, as it allows you to provides accessible visual feedback aligned with the `:focus-visible` standard.

## Example

```typescript
import { Component } from '@angular/core';
import { NgpFocusVisible } from 'ng-primitives/interactions';

@Component({
  selector: 'app-focus-visible',
  imports: [NgpFocusVisible],
  template: `
    <button ngpFocusVisible>Try focusing me!</button>
  `,
  styles: `
    button {
      padding-left: 1rem;
      padding-right: 1rem;
      border-radius: 0.5rem;
      color: var(--ngp-text-primary);
      outline: none;
      height: 2.5rem;
      font-weight: 500;
      background-color: var(--ngp-background);
      border: 1px solid var(--ngp-border);
      transition: background-color 300ms cubic-bezier(0.4, 0, 0.2, 1);
      box-shadow: var(--ngp-shadow);
    }

    button[data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 2px;
    }
  `,
})
export default class FocusVisibleExample {}

```

## Import

Import the Focus Visible primitives from `ng-primitives/interactions`.

```ts
import { NgpFocusVisible } from 'ng-primitives/interactions';
```

## Usage

Assemble the focus-visible directives in your template.

```html
<div (ngpFocusVisible)="onFocusVisible($event)"></div>
```

## API Reference

The following directives are available to import from the `ng-primitives/interactions` package:

### NgpFocusVisible

## API Reference

### NgpFocusVisible

Apply the `ngpFocusVisible` directive to an element that should be visually focused. This is similar to `ngpFocus`
but it will only apply the focus visible styles when the element is focused via keyboard navigation.

**Selector:** `[ngpFocusVisible]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpFocusVisibleDisabled` | `boolean` | `-` | Whether focus events are listened to. |

#### Outputs

| Event | Type | Description |
|-------|------|-------------|
| `ngpFocusVisible` | `boolean` | Emit when the element is visually focused. |

#### Export As

`ngpFocusVisible`



#### Data Attributes

The following data attributes are applied to the `ngpFocusVisible` directive:

| Attribute            | Description                                                        | Value                                   |
| -------------------- | ------------------------------------------------------------------ | --------------------------------------- |
| `data-focus-visible` | Applied when the element should display a visible focus indicator. | `keyboard \| mouse \| touch \| program` |

### Disabling Focus Visible Interaction

Many primitives automatically add focus handling to components. If you want to disable focus handling, either globally or on a per-component/per-directive basis, you can do so by registering the `provideInteractionConfig` provider and setting the `focusVisible` option to `false`.

```ts
import { provideInteractionConfig } from 'ng-primitives/interactions';

providers: [
  provideInteractionConfig({
    focusVisible: false,
  }),
],
```


---

### Focus

File: interactions/focus.md
URL: https://angularprimitives.com/interactions/focus

# Focus

Normalizes the focus event across different browsers and devices.

## Example

```typescript
import { Component, signal } from '@angular/core';
import { NgpFocus } from 'ng-primitives/interactions';

@Component({
  selector: 'app-focus',
  imports: [NgpFocus],
  template: `
    <input (ngpFocus)="isFocused.set($event)" placeholder="Try focusing me!" />
    <p>Input is {{ isFocused() ? 'focused' : 'blurred' }}.</p>
  `,
  styles: `
    :host {
      display: flex;
      flex-direction: column;
    }

    input {
      height: 36px;
      padding: 0 12px;
      border: 1px solid var(--ngp-border);
      border-radius: 0.5rem;
      box-shadow: var(--ngp-shadow);
      outline: none;
    }

    input[data-focus] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 2px;
    }

    p {
      font-size: 0.75rem;
      color: var(--ngp-text-secondary);
      margin-top: 0.25rem;
    }
  `,
})
export default class FocusExample {
  /**
   * Whether the input is currently focused.
   */
  readonly isFocused = signal<boolean>(false);
}

```

## Import

Import the Focus primitives from `ng-primitives/interactions`.

```ts
import { NgpFocus } from 'ng-primitives/interactions';
```

## Usage

Assemble the focus directives in your template.

```html
<div (ngpFocus)="onFocusChange($event)"></div>
```

## API Reference

The following directives are available to import from the `ng-primitives/interactions` package:

### NgpFocus

## API Reference

### NgpFocus

This was inspired by the React Aria useFocus hook.
https://github.com/adobe/react-spectrum/blob/main/packages/%40react-aria/interactions/src/useFocus.ts#L20

**Selector:** `[ngpFocus]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpFocusDisabled` | `boolean` | `-` | Whether listening for focus events is disabled. |

#### Outputs

| Event | Type | Description |
|-------|------|-------------|
| `ngpFocus` | `boolean` | Emit when the focus state changes. |

#### Export As

`ngpFocus`



#### Data Attributes

The following data attributes are applied to the `ngpFocus` directive:

| Attribute    | Description                          |
| ------------ | ------------------------------------ |
| `data-focus` | Applied when the element is focused. |

### Disabling Focus Interaction

Many primitives automatically add focus handling to components. If you want to disable focus handling, either globally or on a per-component/per-directive basis, you can do so by registering the `provideInteractionConfig` provider and setting the `focus` option to `false`.

```ts
import { provideInteractionConfig } from 'ng-primitives/interactions';

providers: [
  provideInteractionConfig({
    focus: false,
  }),
],
```


---

### Hover

File: interactions/hover.md
URL: https://angularprimitives.com/interactions/hover

# Hover

Normalizes the hover event across different browsers and devices.

## Example

```typescript
import { Component, signal } from '@angular/core';
import { NgpHover } from 'ng-primitives/interactions';

@Component({
  selector: 'app-hover',
  imports: [NgpHover],
  styles: `
    div {
      display: flex;
      width: 10rem;
      height: 6rem;
      background-color: var(--ngp-background);
      border: 1px solid var(--ngp-border);
      align-items: center;
      justify-content: center;
      border-radius: 0.5rem;
      box-shadow: var(--ngp-shadow);
      transition: all 0.2s;
      cursor: pointer;
    }

    div[data-hover] {
      background-color: var(--ngp-background-blue);
      border-color: var(--ngp-border-blue);
    }
  `,
  template: `
    <div (ngpHover)="isHovering.set($event)">
      {{ isHovering() ? 'Hovering' : 'Not Hovering' }}
    </div>
  `,
})
export default class HoverExample {
  isHovering = signal(false);
}

```

## Import

Import the Hover primitive from `ng-primitives/interactions`.

```ts
import { NgpHover } from 'ng-primitives/interactions';
```

## Usage

Assemble the hover directives in your template.

```html
<div
  (ngpHover)="onHoverChange($event)"
  (ngpHoverStart)="onHoverStart()"
  (ngpHoverEnd)="onHoverEnd()"
></div>
```

## API Reference

The following directives are available to import from the `ng-primitives/interactions` package:

### NgpHover

## API Reference

### NgpHover

Apply the `ngpHover` directive to an element that you want to listen for hover events. T
his is particulaly useful for supporting hover events on touch devices, where hover events are not handled consistently.
On iOS relying on the `:hover` pseudo-class can result in the hover state being stuck until the user taps elsewhere on the screen.

**Selector:** `[ngpHover]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpHoverDisabled` | `boolean` | `-` | Whether hoving should be disabled. |

#### Outputs

| Event | Type | Description |
|-------|------|-------------|
| `ngpHoverStart` | `void` | Emit an event when hovering starts. |
| `ngpHoverEnd` | `void` | Emit an event when hovering ends. |
| `ngpHover` | `boolean` | Emit an event when the hover state changes. |

#### Export As

`ngpHover`



#### Data Attributes

| Attribute    | Description                                |
| ------------ | ------------------------------------------ |
| `data-hover` | Added to the element when hovering occurs. |

### Disabling Hover Interaction

Many primitives automatically add hover handling to components. If you want to disable hover handling, either globally or on a per-component/per-directive basis, you can do so by registering the `provideInteractionConfig` provider and setting the `hover` option to `false`.

```ts
import { provideInteractionConfig } from 'ng-primitives/interactions';

providers: [
  provideInteractionConfig({
    hover: false,
  }),
],
```


---

### Move

File: interactions/move.md
URL: https://angularprimitives.com/interactions/move

# Move

The Move primitives enable pointer and keyboard move interactions on an element.

## Example

```typescript
import { Component, signal } from '@angular/core';
import { NgpMove, NgpMoveEvent } from 'ng-primitives/interactions';

@Component({
  selector: 'app-move',
  imports: [NgpMove],
  template: `
    <div [style.left.px]="x()" [style.top.px]="y()" (ngpMove)="onMove($event)" tabindex="0">
      Move me!
    </div>
  `,
  styles: `
    div {
      padding: 1rem;
      border-radius: 0.5rem;
      color: var(--ngp-text-primary);
      border: 1px solid var(--ngp-border);
      font-weight: 500;
      background-color: var(--ngp-background);
      box-shadow: none;
      cursor: move;
      user-select: none;
      touch-action: none;
      position: absolute;
      width: 100px;
      height: 100px;
      display: flex;
      justify-content: center;
      align-items: center;
      outline: none;
    }

    div:focus-visible {
      outline: 2px solid var(--ngp-focus-ring);
    }

    div[data-move] {
      box-shadow: var(--ngp-button-shadow);
    }
  `,
})
export default class MoveExample {
  readonly x = signal<number>(60);
  readonly y = signal<number>(60);

  onMove(event: NgpMoveEvent) {
    this.x.update(x => x + event.deltaX);
    this.y.update(y => y + event.deltaY);
  }
}

```

## Import

Import the Move primitives from `ng-primitives/interactions`.

```ts
import { NgpMove } from 'ng-primitives/interactions';
```

## Usage

Assemble the move directives in your template.

```html
<div (ngpMove)="onMove($event)"></div>
```

## API Reference

The following directives are available to import from the `ng-primitives/interactions` package:

### NgpMove

## API Reference

### NgpMove

The `NgpMove` directive is used to enable the pointer and keyboard move interactions on an element.

**Selector:** `[ngpMove]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpMoveDisabled` | `boolean` | `-` | Whether movement is disabled. |

#### Outputs

| Event | Type | Description |
|-------|------|-------------|
| `ngpMoveStart` | `NgpMoveBaseEvent` | Emit when the move event begins. |
| `ngpMove` | `NgpMoveEvent` | Emit when the element is moved. |
| `ngpMoveEnd` | `NgpMoveBaseEvent` | Emit when the move event ends. |

#### Export As

`ngpMove`



#### Data Attributes

The following data attributes are available to use with the `NgpMove` directive:

| Attribute   | Description                              |
| ----------- | ---------------------------------------- |
| `data-move` | Applied when the element is being moved. |


---

### Press

File: interactions/press.md
URL: https://angularprimitives.com/interactions/press

# Press

Normalizes the press event across different browsers and devices.

## Example

```typescript
import { Component, signal } from '@angular/core';
import { NgpPress } from 'ng-primitives/interactions';

@Component({
  selector: 'app-press',
  imports: [NgpPress],
  styles: `
    div {
      display: flex;
      width: 10rem;
      height: 6rem;
      background-color: var(--ngp-background);
      align-items: center;
      justify-content: center;
      border-radius: 0.5rem;
      box-shadow: none;
      transition: all 0.2s;
      cursor: pointer;
      user-select: none;
      border: 1px solid var(--ngp-border);
    }

    div[data-press] {
      background-color: var(--ngp-background-active);
      box-shadow: var(--ngp-button-shadow);
    }
  `,
  template: `
    <div (ngpPress)="isPressed.set($event)">
      {{ isPressed() ? 'Pressed' : 'Not Pressed' }}
    </div>
  `,
})
export default class PressExample {
  isPressed = signal(false);
}

```

## Import

Import the Press primitives from `ng-primitives/interactions`.

```ts
import { NgpPress } from 'ng-primitives/interactions';
```

## Usage

Assemble the press directives in your template.

```html
<div
  ngpPress
  (ngpPressStart)="onPressStart()"
  (ngpPressEnd)="onPressEnd()"
  (ngpPressChange)="onPressChange($event)"
></div>
```

## API Reference

The following directives are available to import from the `ng-primitives/interactions` package:

### NgpPress

## API Reference

### NgpPress

The `ngpPress` directive listens for press events on an element. This is particularly useful for supporting press events on touch devices, where press events are not handled consistently.

**Selector:** `[ngpPress]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpPressDisabled` | `boolean` | `-` | Whether listening for press events is disabled. |

#### Outputs

| Event | Type | Description |
|-------|------|-------------|
| `ngpPressStart` | `void` | Emit when the press begins. |
| `ngpPressEnd` | `void` | Emit when the press ends. |
| `ngpPress` | `boolean` | Emit when the press changes. |

#### Export As

`ngpPress`



#### Data Attributes

| Attribute    | Description                                |
| ------------ | ------------------------------------------ |
| `data-press` | Applied when the element is being pressed. |

### Disabling Press Interaction

Many primitives automatically add press handling to components. If you want to disable press handling, either globally or on a per-component/per-directive basis, you can do so by registering the `provideInteractionConfig` provider and setting the `press` option to `false`.

```ts
import { provideInteractionConfig } from 'ng-primitives/interactions';

providers: [
  provideInteractionConfig({
    press: false,
  }),
],
```


---

## Primitives

### Accordion

File: primitives/accordion.md
URL: https://angularprimitives.com/primitives/accordion

# Accordion

Display a series of panels that can be expanded or collapsed.

## Example

```typescript
import { Component } from '@angular/core';
import { NgIcon, provideIcons } from '@ng-icons/core';
import { heroChevronDownMini } from '@ng-icons/heroicons/mini';
import {
  NgpAccordion,
  NgpAccordionContent,
  NgpAccordionItem,
  NgpAccordionTrigger,
} from 'ng-primitives/accordion';
import { NgpButton } from 'ng-primitives/button';

@Component({
  selector: 'app-accordion',
  imports: [
    NgpButton,
    NgIcon,
    NgpAccordion,
    NgpAccordionItem,
    NgpAccordionContent,
    NgpAccordionTrigger,
  ],
  providers: [provideIcons({ heroChevronDownMini })],
  styles: `
    :host {
      display: flex;
      justify-content: center;
      width: 100%;
    }

    [ngpAccordion] {
      width: 100%;
      max-width: 24rem;
      border-radius: 0.75rem;
      border: 1px solid var(--ngp-border);
      background-color: var(--ngp-background);
      box-shadow: var(--ngp-shadow);
    }

    [ngpAccordionItem]:has(+ [ngpAccordionItem]) {
      border-bottom: 1px solid var(--ngp-border);
    }

    /* Reset default heading margins inside accordion items to avoid layout shifts */
    [ngpAccordionItem] h3 {
      margin: 0;
    }

    [ngpAccordionTrigger] {
      display: flex;
      padding-left: 1rem;
      padding-right: 1rem;
      font-size: 0.875rem;
      line-height: 1.25rem;
      font-weight: 500;
      justify-content: space-between;
      align-items: center;
      width: 100%;
      height: 2.75rem;
      border-radius: 0.75rem;
      outline: none;
      color: var(--ngp-text-primary);
      background-color: var(--ngp-background);
      border: none;
    }

    [ngpAccordionTrigger][data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
    }

    [ngpAccordionContent] {
      font-size: 0.875rem;
      color: var(--ngp-text-secondary);
      overflow: hidden;
    }

    [ngpAccordionContent][data-open] {
      animation: slideDown 0.2s ease-in-out forwards;
    }

    [ngpAccordionContent][data-closed] {
      animation: slideUp 0.2s ease-in-out forwards;
    }

    .accordion-content {
      padding: 0 16px 16px;
    }

    ng-icon {
      font-size: 1.25rem;
      color: var(--ngp-text-secondary);
    }

    [ngpAccordionTrigger][data-open] ng-icon {
      transform: rotate(180deg);
    }

    @keyframes slideDown {
      from {
        height: 0;
      }
      to {
        height: var(--ngp-accordion-content-height);
      }
    }

    @keyframes slideUp {
      from {
        height: var(--ngp-accordion-content-height);
      }
      to {
        height: 0;
      }
    }
  `,
  template: `
    <div ngpAccordion ngpAccordionType="single" ngpAccordionCollapsible>
      <div #panel1="ngpAccordionItem" ngpAccordionItem ngpAccordionItemValue="item-1">
        <h3>
          <button ngpAccordionTrigger ngpButton>
            Would you like to learn more?

            <ng-icon [attr.data-open]="panel1.open()" name="heroChevronDownMini" />
          </button>
        </h3>
        <div ngpAccordionContent>
          <div class="accordion-content">
            If you would like to learn more please reach out to us on GitHub.
          </div>
        </div>
      </div>

      <div #panel2="ngpAccordionItem" ngpAccordionItem ngpAccordionItemValue="item-2">
        <h3>
          <button ngpAccordionTrigger ngpButton>
            Can I use this in my project?

            <ng-icon [attr.data-open]="panel2.open()" name="heroChevronDownMini" />
          </button>
        </h3>
        <div ngpAccordionContent>
          <div class="accordion-content">
            Yes, this is open source and you can use it in your project.
          </div>
        </div>
      </div>
    </div>
  `,
})
export default class AccordionExample {}

```

## Import

Import the Accordion primitives from `ng-primitives/accordion`.

```ts
import {
  NgpAccordion,
  NgpAccordionItem,
  NgpAccordionTrigger,
  NgpAccordionContent,
} from 'ng-primitives/accordion';
```

## Usage

Assemble the accordion directives in your template.

```html
<div ngpAccordion ngpAccordionType="single" ngpAccordionCollapsible>
  <div ngpAccordionItem ngpAccordionItemValue="item-1">
    <h3>
      <button ngpAccordionTrigger ngpButton>Would you like to learn more?</button>
    </h3>
    <div ngpAccordionContent>If you would like to learn more please reach out to us on GitHub.</div>
  </div>

  <div ngpAccordionItem ngpAccordionItemValue="item-2">
    <h3>
      <button ngpAccordionTrigger ngpButton>Can I use this in my project?</button>
    </h3>
    <div ngpAccordionContent>Yes, this is open source and you can use it in your project.</div>
  </div>
</div>
```

## Reusable Component

Create reusable components that uses the `NgpAccordion` and `NgpAccordionItem` directives.

## Reusable Component

```typescript
import { Component } from '@angular/core';
import { NgpAccordion } from 'ng-primitives/accordion';

@Component({
  selector: 'app-accordion',
  hostDirectives: [
    {
      directive: NgpAccordion,
      inputs: [
        'ngpAccordionValue:value',
        'ngpAccordionType:type',
        'ngpAccordionCollapsible:collapsible',
        'ngpAccordionDisabled:disabled',
        'ngpAccordionOrientation:orientation',
      ],
    },
  ],
  template: `
    <ng-content />
  `,
  styles: `
    :host {
      display: block;
      width: 100%;
      max-width: 24rem;
      border-radius: 0.75rem;
      border: 1px solid var(--ngp-border);
      background-color: var(--ngp-background);
      box-shadow: var(--ngp-shadow);
    }
  `,
})
export class Accordion {}

```

## Schematics

Generate a reusable accordion component using the Angular CLI.

```bash npm
ng g ng-primitives:primitive accordion
```

### Options

- `path`: The path at which to create the component file.
- `prefix`: The prefix to apply to the generated component selector.
- `componentSuffix`: The suffix to apply to the generated component class name.
- `fileSuffix`: The suffix to apply to the generated component file name. Defaults to `component`.
- `exampleStyles`: Whether to include example styles in the generated component file. Defaults to `true`.

## API Reference

The following directives are available to import from the `ng-primitives/accordion` package:

### NgpAccordion

## API Reference

### NgpAccordion

Apply the `ngpAccordion` directive to an element that represents the group of accordion items.

**Selector:** `[ngpAccordion]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpAccordionType` | `NgpAccordionType` | `-` | The type of the accordion. |
| `ngpAccordionCollapsible` | `boolean` | `-` | Whether the accordion is collapsible. |
| `ngpAccordionValue` | `T | T[] | null` | `-` | The value of the accordion. |
| `ngpAccordionDisabled` | `boolean` | `-` | Whether the accordion is disabled. |
| `ngpAccordionOrientation` | `NgpOrientation` | `-` | The accordion orientation. |

#### Outputs

| Event | Type | Description |
|-------|------|-------------|
| `ngpAccordionValueChange` | `T | T[] | null` | Event emitted when the accordion value changes. |

#### Export As

`ngpAccordion`



#### Data Attributes

The following data attributes are applied to the `ngpAccordion` directive:

| Attribute          | Description                           | Value                      |
| ------------------ | ------------------------------------- | -------------------------- |
| `data-orientation` | The orientation of the accordion.     | `horizontal` \| `vertical` |
| `data-disabled`    | Applied when the element is disabled. | `-`                        |

### NgpAccordionItem

## API Reference

### NgpAccordionItem

Apply the `ngpAccordionItem` directive to an element that represents an accordion item.

**Selector:** `[ngpAccordionItem]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpAccordionItemValue` | `T` | `-` | The value of the accordion item. |
| `ngpAccordionItemDisabled` | `boolean` | `-` | Whether the accordion item is disabled. |

#### Export As

`ngpAccordionItem`



#### Data Attributes

The following data attributes are applied to the `ngpAccordionItem` directive:

| Attribute          | Description                                  | Value                      |
| ------------------ | -------------------------------------------- | -------------------------- |
| `data-orientation` | The orientation of the accordion.            | `horizontal` \| `vertical` |
| `data-open`        | Applied when the accordion item is open.     | `-`                        |
| `data-disabled`    | Applied when the accordion item is disabled. | `-`                        |

### NgpAccordionTrigger

## API Reference

### NgpAccordionTrigger

Apply the `ngpAccordionTrigger` directive to an element that represents the trigger for an accordion item, such as a button.

**Selector:** `[ngpAccordionTrigger]`

#### Export As

`ngpAccordionTrigger`



#### Data Attributes

The following data attributes are applied to the `ngpAccordionTrigger` directive:

| Attribute          | Description                                  | Value                      |
| ------------------ | -------------------------------------------- | -------------------------- |
| `data-orientation` | The orientation of the accordion.            | `horizontal` \| `vertical` |
| `data-open`        | Applied when the accordion item is open.     | `-`                        |
| `data-disabled`    | Applied when the accordion item is disabled. | `-`                        |

### NgpAccordionContent

## API Reference

### NgpAccordionContent

Apply the `ngpAccordionContent` directive to an element that represents the content of an accordion item.

**Selector:** `[ngpAccordionContent]`

#### Export As

`ngpAccordionContent`



#### Data Attributes

The following data attributes are applied to the `ngpAccordionContent` directive:

| Attribute          | Description                              | Value                      |
| ------------------ | ---------------------------------------- | -------------------------- |
| `data-orientation` | The orientation of the accordion.        | `horizontal` \| `vertical` |
| `data-open`        | Applied when the accordion item is open. | `-`                        |

The following CSS custom properties are applied to the `ngpAccordionContent` directive:

| Property                         | Description                          |
| -------------------------------- | ------------------------------------ |
| `--ngp-accordion-content-width`  | The width of the accordion content.  |
| `--ngp-accordion-content-height` | The height of the accordion content. |

## Animations

The `ngpAccordionContent` primitive adds several CSS custom properties `--ngp-accordion-content-width` and `--ngp-accordion-content-height` to the element that can be used to animate the accordion content on open and close.

## Global Configuration

You can configure the default options for all accordions in your application by using the `provideAccordionConfig` function in a providers array.

```ts
import { provideAccordionConfig } from 'ng-primitives/accordion';

bootstrapApplication(AppComponent, {
  providers: [
    provideAccordionConfig({
      type: 'multiple',
      collapsible: true,
      orientation: 'horizontal',
    }),
  ],
});
```

### NgpAccordionConfig

<prop-details name="type" type="single | multiple">
  Define whether only one or multiple accordion items can be open at a time.
</prop-details>

<prop-details name="collapsible" type="boolean">
  Define an accordion can be collapsed. This is only applicable when `type` is set to `single`.
</prop-details>

<prop-details name="orientation" type="horizontal | vertical">
  Define the orientation of the accordion.
</prop-details>

## Accessibility

Adheres to the [Accordion WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/accordion).

Tip: Per APG, wrap each trigger button in a heading element (e.g., `h3`) or an element with `role="heading"` and an appropriate `aria-level`. Ensure the button is the only child of the heading.

### Keyboard Interactions

- <kbd>Space</kbd> - Toggle the expanded state of the accordion item when the trigger is focused.
- <kbd>Enter</kbd> - Toggle the expanded state of the accordion item when the trigger is focused.

### Hidden Until Found

The `ngpAccordionContent` primitive uses the `until-found` attribute to allow the browser to search text within the hidden region and reveal the section if a match is found. If the browser does not support this functionality, the attribute is ignored.

More information about the `until-found` attribute can be found on [Can I use](https://caniuse.com/?search=hidden%20until-found).


---

### AI Assistant

File: primitives/ai-assistant.md
URL: https://angularprimitives.com/primitives/ai-assistant

# AI Assistant

Build a customizable AI chat assistant by composing multiple primitives. These primitives provide accessible, flexible building blocks for chat threads, message display, prompt input, dictation, and submission—allowing you to create rich conversational interfaces tailored to your application's needs.

**Note:** The AI Assistant primitives are currently experimental. The API may change in future releases.

## Example

```typescript
import { Component, computed, signal } from '@angular/core';
import { NgIcon, provideIcons } from '@ng-icons/core';
import { lucideArrowUp, lucideMic, lucidePlus, lucideX } from '@ng-icons/lucide';
import {
  NgpPromptComposer,
  NgpPromptComposerDictation,
  NgpPromptComposerInput,
  NgpPromptComposerSubmit,
  NgpThread,
  NgpThreadMessage,
  NgpThreadSuggestion,
  NgpThreadViewport,
} from 'ng-primitives/ai';
import { NgpButton } from 'ng-primitives/button';
import { NgpFileUpload } from 'ng-primitives/file-upload';

interface Attachment {
  id: string;
  file: File;
  preview: string; // Data URL for image preview
  type: 'image' | 'file';
}

interface Message {
  id: string;
  role: 'user' | 'assistant' | 'system';
  content: string;
  attachments?: Attachment[];
  isStreaming?: boolean;
}

@Component({
  selector: 'app-ai',
  imports: [
    NgpThread,
    NgpThreadViewport,
    NgpThreadMessage,
    NgpThreadSuggestion,
    NgpPromptComposer,
    NgpPromptComposerInput,
    NgpPromptComposerSubmit,
    NgpPromptComposerDictation,
    NgpFileUpload,
    NgIcon,
    NgpButton,
  ],
  providers: [provideIcons({ lucideArrowUp, lucideMic, lucidePlus, lucideX })],
  template: `
    <div class="ai-container" ngpThread>
      <div class="ai-chat-wrapper">
        <div class="ai-chat-content">
          <div class="ai-viewport" ngpThreadViewport>
            @if (!hasMessages()) {
              <!-- Welcome Message and Suggestions -->
              <div class="ai-welcome-container">
                <div class="ai-welcome-content">
                  <h1 class="ai-welcome-title">{{ welcomeMessage }}</h1>
                  <p class="ai-welcome-subtitle">
                    Choose a suggestion below or type your own message to get started.
                  </p>
                </div>

                <!-- Suggestions -->
                <div class="ai-suggestions-grid">
                  @for (suggestion of suggestions; track suggestion) {
                    <button
                      class="ai-suggestion-button"
                      (click)="sendMessage(suggestion)"
                      ngpThreadSuggestion
                      ngpButton
                      type="button"
                    >
                      {{ suggestion }}
                    </button>
                  }
                </div>
              </div>
            } @else {
              <!-- Messages -->
              @for (message of messages(); track message.id) {
                @if (message.role !== 'system') {
                  <div
                    class="ai-message"
                    [class.ai-message-user]="message.role === 'user'"
                    [class.ai-message-assistant]="message.role !== 'user'"
                    ngpThreadMessage
                  >
                    <!-- Message Attachments -->
                    @if (message.attachments && message.attachments.length > 0) {
                      <div class="ai-attachments">
                        @for (attachment of message.attachments; track attachment.id) {
                          @if (attachment.type === 'image') {
                            <img
                              class="ai-attachment-image"
                              [src]="attachment.preview"
                              [alt]="attachment.file.name"
                            />
                          } @else {
                            <div class="ai-attachment-file">
                              <span>{{ attachment.file.name }}</span>
                            </div>
                          }
                        }
                      </div>
                    }

                    <div
                      class="ai-message-bubble"
                      [class.ai-message-bubble-user]="message.role === 'user'"
                      [class.ai-message-bubble-assistant]="message.role !== 'user'"
                    >
                      <p>
                        {{ message.content }}

                        @if (message.isStreaming) {
                          <span class="ai-streaming-wrapper">
                            <div class="streaming-indicator"></div>
                          </span>
                        }
                      </p>
                    </div>
                  </div>
                }
              }
            }
          </div>
        </div>

        <!-- Attachment Previews -->
        @if (attachments().length > 0) {
          <div class="ai-attachment-previews-container">
            <div class="ai-attachment-previews">
              @for (attachment of attachments(); track attachment.id) {
                <div class="ai-attachment-preview-item">
                  @if (attachment.type === 'image') {
                    <img
                      class="ai-attachment-preview-image"
                      [src]="attachment.preview"
                      [alt]="attachment.file.name"
                    />
                  } @else {
                    <div class="ai-attachment-preview-file">
                      <span class="ai-attachment-extension">
                        {{ attachment.file.name.split('.').pop()?.toUpperCase() }}
                      </span>
                    </div>
                  }
                  <button
                    class="ai-attachment-remove"
                    (click)="removeAttachment(attachment.id)"
                    type="button"
                  >
                    <ng-icon name="lucideX" />
                  </button>
                </div>
              }
            </div>
          </div>
        }

        <div class="ai-composer" (ngpPromptComposerSubmit)="sendMessage($event)" ngpPromptComposer>
          <button
            class="ai-composer-button ai-file-button"
            (ngpFileUploadSelected)="addAttachment($event)"
            ngpButton
            type="button"
            ngpFileUpload
            ngpFileUploadMultiple="true"
            ngpFileUploadFileTypes="image/*"
            aria-label="Add Attachment"
          >
            <ng-icon class="ai-icon" name="lucidePlus" />
          </button>

          <textarea
            class="ai-textarea"
            ngpPromptComposerInput
            style="field-sizing: content;"
            name="input"
            placeholder="Message ChatNGP"
            rows="1"
          ></textarea>

          <button
            class="ai-composer-button ai-dictation-button"
            #dictation="ngpPromptComposerDictation"
            type="button"
            ngpPromptComposerDictation
            aria-label="Dictation"
          >
            <ng-icon class="ai-icon" [name]="dictation.isDictating() ? 'lucideX' : 'lucideMic'" />
          </button>

          <button
            class="ai-composer-button ai-send-button"
            type="button"
            ngpPromptComposerSubmit
            aria-label="Send Message"
          >
            <ng-icon class="ai-icon" name="lucideArrowUp" />
          </button>
        </div>

        <p class="ai-disclaimer">ChatNGP can make mistakes. Check important info.</p>
      </div>
    </div>
  `,
  styles: `
    :host {
      display: contents;
    }

    /* Container */
    .ai-container {
      height: 700px;
      width: 100%;
    }

    .ai-chat-wrapper {
      display: flex;
      height: 100%;
      flex-direction: column;
      align-items: stretch;
      border-radius: 1rem;
      background-color: var(--ngp-background);
      padding: 0 1rem;
      box-shadow: var(--ngp-shadow-border);
    }

    .ai-chat-content {
      display: flex;
      flex-grow: 1;
      flex-direction: column;
      gap: 1rem;
      overflow: hidden;
      padding-top: 1rem;
    }

    .ai-viewport {
      display: flex;
      flex-grow: 1;
      flex-direction: column;
      gap: 1rem;
      overflow-y: auto;
      padding: 0 0.5rem 1rem;
    }

    /* Welcome State */
    .ai-welcome-container {
      display: flex;
      flex-grow: 1;
      flex-direction: column;
      align-items: center;
      justify-content: center;
      gap: 2rem;
      text-align: center;
    }

    .ai-welcome-content {
      max-width: 28rem;
    }

    .ai-welcome-title {
      margin-bottom: 0.5rem;
      font-size: 1.5rem;
      font-weight: 600;
      color: var(--ngp-text-emphasis);
      line-height: 32px;
    }

    .ai-welcome-subtitle {
      font-size: 0.875rem;
      color: var(--ngp-text-secondary);
      line-height: 24px;
    }

    .ai-suggestions-grid {
      display: grid;
      width: 100%;
      max-width: 32rem;
      grid-template-columns: 1fr;
      gap: 0.75rem;
    }

    @media (min-width: 768px) {
      .ai-suggestions-grid {
        grid-template-columns: 1fr 1fr;
      }
    }

    .ai-suggestion-button {
      border-radius: 0.5rem;
      box-shadow: var(--ngp-shadow-border);
      padding: 10px 0.75rem;
      text-align: left;
      font-size: 0.875rem;
      background-color: var(--ngp-background);
      color: var(--ngp-text-secondary);
      transition: all 0.2s ease;
      cursor: pointer;
    }

    .ai-suggestion-button:hover,
    .ai-suggestion-button[data-hover] {
      border-color: var(--ngp-border);
      background-color: var(--ngp-background-hover);
    }

    /* Messages */
    .ai-message {
      display: flex;
      flex-direction: column;
      gap: 0.5rem;
    }

    .ai-message-user {
      align-items: flex-end;
    }

    .ai-message-assistant {
      align-items: flex-start;
    }

    .ai-attachments {
      display: flex;
      max-width: 80%;
      flex-wrap: wrap;
      gap: 0.5rem;
    }

    .ai-attachment-image {
      max-height: 8rem;
      max-width: 20rem;
      border-radius: 0.5rem;
      border: 1px solid var(--ngp-border-secondary);
      object-fit: cover;
    }

    .ai-attachment-file {
      display: flex;
      align-items: center;
      gap: 0.5rem;
      border-radius: 0.5rem;
      border: 1px solid var(--ngp-border-secondary);
      background-color: var(--ngp-background-hover);
      padding: 0.5rem;
      font-size: 0.75rem;
      color: var(--ngp-text-secondary);
    }

    .ai-message-bubble {
      max-width: 80%;
      border-radius: 1rem;
      padding: 0.75rem 1rem;
      font-size: 0.875rem;
    }

    .ai-message-bubble-user {
      background-color: var(--ngp-background-inverse);
      color: var(--ngp-text-inverse);
    }

    .ai-message-bubble-assistant {
      background-color: var(--ngp-background-active);
      color: var(--ngp-text-primary);
    }

    .ai-streaming-wrapper {
      margin-left: 0.25rem;
      display: inline-flex;
    }

    .streaming-indicator {
      height: 0.5rem;
      width: 0.5rem;
      border-radius: 50%;
      background-color: var(--ngp-text-tertiary);
      animation: pulse 1.5s ease-in-out infinite;
    }

    /* Attachment Previews */
    .ai-attachment-previews-container {
      margin: 0 auto;
      width: 100%;
      max-width: 768px;
      padding: 0 1rem 0.5rem;
    }

    .ai-attachment-previews {
      display: flex;
      flex-wrap: wrap;
      gap: 0.5rem;
    }

    .ai-attachment-preview-item {
      position: relative;
    }

    .ai-attachment-preview-item:hover .ai-attachment-remove {
      opacity: 1;
    }

    .ai-attachment-preview-image {
      height: 4rem;
      width: 4rem;
      cursor: pointer;
      border-radius: 0.5rem;
      border: 1px solid var(--ngp-border-secondary);
      object-fit: cover;
      transition: opacity 0.2s ease;
    }

    .ai-attachment-preview-image:hover {
      opacity: 0.8;
    }

    .ai-attachment-preview-file {
      display: flex;
      height: 4rem;
      width: 4rem;
      align-items: center;
      justify-content: center;
      border-radius: 0.5rem;
      border: 1px solid var(--ngp-border-secondary);
      background-color: var(--ngp-background-hover);
    }

    .ai-attachment-extension {
      font-size: 0.75rem;
      color: var(--ngp-text-secondary);
    }

    .ai-attachment-remove {
      position: absolute;
      right: -0.25rem;
      top: -0.25rem;
      display: flex;
      height: 1.25rem;
      width: 1.25rem;
      align-items: center;
      justify-content: center;
      border-radius: 50%;
      background-color: var(--ngp-text-red);
      color: var(--ngp-text-inverse);
      opacity: 0;
      transition: opacity 0.2s ease;
      border: none;
      cursor: pointer;
      font-size: 0.75rem;
    }

    /* Composer */
    .ai-composer {
      margin: 0 auto;
      display: flex;
      width: 100%;
      max-width: 768px;
      align-items: flex-end;
      border-radius: 1.5rem;
      background-color: rgba(255, 255, 255, 0.05);
      box-shadow: var(--ngp-shadow-border);
    }

    .ai-composer-button {
      margin: 0.5rem;
      display: flex;
      height: 2rem;
      width: 2rem;
      align-items: center;
      justify-content: center;
      border-radius: 50%;
      transition: background-color 0.2s ease;
      border: none;
      cursor: pointer;
      background-color: transparent;
    }

    .ai-file-button:hover {
      background-color: rgba(0, 0, 0, 0.05);
    }

    .ai-dictation-button {
      display: none;
    }

    .ai-dictation-button[data-dictation-supported]:not([data-prompt]) {
      display: flex;
    }

    .ai-dictation-button[data-prompt]:not([data-dictating]) {
      display: none;
    }

    .ai-dictation-button:hover {
      background-color: rgba(0, 0, 0, 0.05);
    }

    .ai-dictation-button[data-dictating] {
      background-color: rgba(0, 0, 0, 0.05);
    }

    .ai-dictation-button[data-dictating]:hover {
      background-color: rgba(0, 0, 0, 0.1);
    }

    .ai-send-button {
      display: none;
      background-color: var(--ngp-background-inverse);
      color: var(--ngp-text-inverse);
    }

    .ai-send-button[data-prompt] {
      display: flex;
    }

    .ai-textarea {
      max-height: 10rem;
      min-height: 3rem;
      grow: 1;
      resize: none;
      background-color: transparent;
      padding: 0.75rem 0;
      font-size: 0.875rem;
      outline: none;
      border: none;
      color: var(--ngp-text-primary);
    }

    .ai-textarea::placeholder {
      color: var(--ngp-text-placeholder);
    }

    .ai-icon {
      font-size: 14px;
      color: var(--ngp-text-secondary);
    }

    .ai-send-button .ai-icon {
      color: var(--ngp-text-inverse);
    }

    /* Disclaimer */
    .ai-disclaimer {
      margin: 0.25rem 0;
      padding: 0.5rem;
      text-align: center;
      font-size: 0.75rem;
      color: var(--ngp-text-placeholder);
    }

    /* Animations */
    @keyframes pulse {
      0%,
      100% {
        opacity: 0.4;
        transform: scale(1);
      }
      50% {
        opacity: 1;
        transform: scale(1.1);
      }
    }
  `,
})
export default class AiExample {
  readonly messages = signal<Message[]>([]);

  readonly attachments = signal<Attachment[]>([]);

  // Check if there are any non-system messages to show welcome/suggestions
  readonly hasMessages = computed(() => this.messages().some(message => message.role !== 'system'));

  // Welcome message and suggestions
  readonly welcomeMessage = "Hello! I'm ChatNGP, your AI assistant. How can I help you today?";

  readonly suggestions = [
    'Explain Angular components',
    'Help with TypeScript types',
    'Best practices for testing',
    'Web development concepts',
    'Angular routing guide',
    'State management patterns',
  ];

  // Simulated chat scenarios
  private readonly chatScenarios = [
    {
      keywords: ['angular', 'component', 'directive'],
      responses: [
        'Angular is a powerful framework! I can help you with components, services, routing, and more.',
        'Components are the building blocks of Angular applications. They control views and handle user interactions.',
        'Directives are classes that add additional behavior to elements in your Angular applications.',
        'Angular provides great tools for building scalable applications with TypeScript.',
      ],
    },
    {
      keywords: ['help', 'assist', 'support'],
      responses: [
        'I am here to help! You can ask me about web development, Angular, or any other programming topics.',
        'Feel free to ask me anything! I can assist with coding questions, best practices, or debugging.',
        'How can I assist you today? I am knowledgeable about many programming topics.',
      ],
    },
    {
      keywords: ['typescript', 'ts', 'type'],
      responses: [
        'TypeScript is a great language that adds static typing to JavaScript!',
        'TypeScript helps catch errors at compile time and improves developer experience.',
        'With TypeScript, you get better IntelliSense, refactoring, and code navigation.',
      ],
    },
    {
      keywords: ['web', 'frontend', 'ui', 'interface'],
      responses: [
        'Modern web development offers many exciting possibilities for creating great user interfaces.',
        'Frontend development has evolved significantly with frameworks like Angular, React, and Vue.',
        'User interface design is crucial for creating engaging web applications.',
      ],
    },
    {
      keywords: ['test', 'testing', 'unit', 'e2e'],
      responses: [
        'Testing is essential for maintaining code quality. Angular provides great testing utilities.',
        'Unit tests help ensure individual components work correctly in isolation.',
        'End-to-end testing validates that your application works as expected from the user perspective.',
      ],
    },
  ];

  private readonly fallbackResponses = [
    'That is an interesting question! Could you tell me more about what you are trying to achieve?',
    'I would love to help you with that. Can you provide some more context?',
    'That is a great topic to explore. What specific aspect interests you most?',
    'Interesting! I am curious to learn more about your use case.',
    'That sounds like something worth discussing further. What is your current approach?',
  ];

  sendMessage(prompt: string): void {
    // Add user message with attachments if any
    const userMessage: Message = {
      id: Date.now().toString(),
      content: prompt,
      role: 'user',
      attachments: this.attachments().length > 0 ? [...this.attachments()] : undefined,
    };

    this.messages.update(messages => [...messages, userMessage]);

    // Clear attachments after sending
    this.attachments.set([]);

    // Generate AI response
    this.generateAiResponse(prompt);
  }

  private async generateAiResponse(userMessage: string): Promise<void> {
    const aiMessageId = (Date.now() + 1).toString();

    // Create initial AI message
    const aiMessage: Message = {
      id: aiMessageId,
      content: '',
      role: 'assistant',
      isStreaming: true,
    };

    this.messages.update(messages => [...messages, aiMessage]);

    try {
      // Simulate streaming response
      await this.streamSimulatedResponse(userMessage, aiMessageId);
    } catch (error) {
      console.error('Error generating response:', error);
      // Update with error message
      this.messages.update(messages =>
        messages.map(msg =>
          msg.id === aiMessageId
            ? {
                ...msg,
                content: 'Sorry, I encountered an error. Please try again.',
                isStreaming: false,
              }
            : msg,
        ),
      );
    }
  }

  private async streamSimulatedResponse(userMessage: string, messageId: string): Promise<void> {
    // Add a small delay to simulate thinking
    await new Promise(resolve => setTimeout(resolve, 500));

    // Generate response based on user message
    const response = this.getSimulatedResponse(userMessage);

    // Simulate streaming by adding characters with delay
    let currentContent = '';

    for (let i = 0; i < response.length; i++) {
      await new Promise(resolve => setTimeout(resolve, 10)); // 10ms delay between characters
      currentContent += response[i];

      this.messages.update(messages =>
        messages.map(msg =>
          msg.id === messageId ? { ...msg, content: currentContent, isStreaming: true } : msg,
        ),
      );
    }

    // Mark streaming as complete
    this.messages.update(messages =>
      messages.map(msg => (msg.id === messageId ? { ...msg, isStreaming: false } : msg)),
    );
  }

  private getSimulatedResponse(userMessage: string): string {
    const lowerMessage = userMessage.toLowerCase();

    // Check for matching scenario based on keywords
    for (const scenario of this.chatScenarios) {
      for (const keyword of scenario.keywords) {
        if (lowerMessage.includes(keyword)) {
          // Return a random response from the matching scenario
          const randomIndex = Math.floor(Math.random() * scenario.responses.length);
          return scenario.responses[randomIndex];
        }
      }
    }

    // If no keywords match, return a random fallback response
    const randomIndex = Math.floor(Math.random() * this.fallbackResponses.length);
    return this.fallbackResponses[randomIndex];
  }

  addAttachment(files: FileList | null): void {
    if (!files || files.length === 0) return;

    Array.from(files).forEach(file => {
      const attachment: Attachment = {
        id: Date.now().toString() + Math.random().toString(36).substr(2, 9),
        file,
        preview: '',
        type: file.type.startsWith('image/') ? 'image' : 'file',
      };

      // Create preview for images
      if (attachment.type === 'image') {
        const reader = new FileReader();
        reader.onload = e => {
          attachment.preview = e.target?.result as string;
          this.attachments.update(attachments => [...attachments, attachment]);
        };
        reader.readAsDataURL(file);
      } else {
        this.attachments.update(attachments => [...attachments, attachment]);
      }
    });
  }

  removeAttachment(attachmentId: string): void {
    this.attachments.update(attachments =>
      attachments.filter(attachment => attachment.id !== attachmentId),
    );
  }
}

```

## Import

Import the AI primitives from `ng-primitives/ai`.

```ts
import {
  NgpThread,
  NgpThreadViewport,
  NgpThreadMessage,
  NgpThreadSuggestion,
  NgpPromptComposer,
  NgpPromptComposerInput,
  NgpPromptComposerSubmit,
  NgpPromptComposerDictation,
} from 'ng-primitives/ai';
```

## Usage

Assemble the AI directives in your template.

```html
<div ngpThread>
  <div ngpThreadViewport>
    <div ngpThreadMessage>
      <div>Message content</div>
    </div>
  </div>

  <div ngpThreadSuggestion>...</div>

  <div ngpPromptComposer>
    <textarea ngpPromptComposerInput></textarea>
    <button ngpPromptComposerDictation>Mic</button>
    <button ngpPromptComposerSubmit>Send</button>
  </div>
</div>
```

## API Reference

The following directives are available to import from the `ng-primitives/ai` package:

### NgpThread

The `NgpThread` directive is wrapper around the thread viewport, messages and composer in the AI assistant chat.

## API Reference

### NgpThread



**Selector:** `[ngpThread]`

#### Export As

`ngpThread`



### NgpThreadViewport

The `NgpThreadViewport` directive creates a scrollable container for displaying the messages in the AI assistant chat thread.

## API Reference

### NgpThreadViewport



**Selector:** `[ngpThreadViewport]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpThreadViewportThreshold` | `number` | `70` | The distance in pixels from the bottom of the scrollable container that is considered "at the bottom".
When the user scrolls within this threshold, the thread is treated as being at the bottom.
This value is used to determine whether automatic scrolling to the bottom should occur,
for example when new content is added or the container is resized. |
| `ngpThreadViewportAutoScroll` | `boolean` | `-` | Whether the thread should automatically scroll to the bottom when new content is added. |

#### Export As

`ngpThreadViewport`



### NgpThreadMessage

The `NgpThreadMessage` directive represents an individual message within a thread in the AI assistant chat.

## API Reference

### NgpThreadMessage



**Selector:** `[ngpThreadMessage]`

#### Export As

`ngpThreadMessage`



### NgpThreadSuggestion

The `NgpThreadSuggestion` directive displays suggested text that the user can click to populate the prompt input field.

## API Reference

### NgpThreadSuggestion



**Selector:** `button[ngpThreadSuggestion]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpThreadSuggestion` | `string` | `-` | The suggested text to display in the input field. |
| `ngpThreadSuggestionSetPromptOnClick` | `boolean` | `-` | Whether the suggestion should populate the prompt when clicked. |

#### Export As

`ngpThreadSuggestion`



### NgpPromptComposer

The `NgpPromptComposer` directive creates a container for composing and submitting prompts to the AI assistant.

## API Reference

### NgpPromptComposer



**Selector:** `[ngpPromptComposer]`

#### Outputs

| Event | Type | Description |
|-------|------|-------------|
| `ngpPromptComposerSubmit` | `string` | Emits whenever the user submits the prompt. |

#### Export As

`ngpPromptComposer`



#### Data Attributes

| Attribute                  | Description                                              |
| -------------------------- | -------------------------------------------------------- |
| `data-prompt`              | Added when there is text content in the prompt.          |
| `data-dictating`           | Added when speech dictation is active.                   |
| `data-dictation-supported` | Added when speech dictation is supported by the browser. |

### NgpPromptComposerInput

The `NgpPromptComposerInput` directive is used for the text input field where users type their messages.

## API Reference

### NgpPromptComposerInput



**Selector:** `input[ngpPromptComposerInput], textarea[ngpPromptComposerInput]`

#### Export As

`ngpPromptComposerInput`



### NgpPromptComposerSubmit

The `NgpPromptComposerSubmit` directive handles the submission of composed prompts to the AI assistant.

## API Reference

### NgpPromptComposerSubmit



**Selector:** `button[ngpPromptComposerSubmit]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `disabled` | `boolean` | `-` | Whether the submit button should be disabled |

#### Export As

`ngpPromptComposerSubmit`



#### Data Attributes

| Attribute                  | Description                                              |
| -------------------------- | -------------------------------------------------------- |
| `data-prompt`              | Added when there is text content in the prompt.          |
| `data-dictating`           | Added when speech dictation is active.                   |
| `data-dictation-supported` | Added when speech dictation is supported by the browser. |

### NgpPromptComposerDictation

The `NgpPromptComposerDictation` directive enables voice input functionality for composing prompts using speech-to-text.

## API Reference

### NgpPromptComposerDictation



**Selector:** `button[ngpPromptComposerDictation]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `disabled` | `boolean` | `-` | Whether the submit button should be disabled. |

#### Export As

`ngpPromptComposerDictation`



#### Data Attributes

| Attribute                  | Description                                              |
| -------------------------- | -------------------------------------------------------- |
| `data-dictating`           | Added when speech dictation is active.                   |
| `data-dictation-supported` | Added when speech dictation is supported by the browser. |
| `data-prompt`              | Added when there is text content in the prompt.          |

## Accessibility

### Keyboard Interactions

- <kbd>Enter</kbd> - Submits the prompt when focused on the input field.
- <kbd>Shift+Enter</kbd> - Inserts a newline in the input field.


---

### Avatar

File: primitives/avatar.md
URL: https://angularprimitives.com/primitives/avatar

# Avatar

Display an image that represents a user with a text fallback.

## Example

```typescript
import { Component } from '@angular/core';
import { NgpAvatar, NgpAvatarFallback, NgpAvatarImage } from 'ng-primitives/avatar';

@Component({
  selector: 'app-avatar',
  imports: [NgpAvatar, NgpAvatarImage, NgpAvatarFallback],
  styles: `
    [ngpAvatar] {
      position: relative;
      display: inline-flex;
      width: 3rem;
      height: 3rem;
      align-items: center;
      justify-content: center;
      border-radius: 9999px;
      border-width: 2px;
      border-color: var(--ngp-avatar-border);
      background-color: var(--ngp-avatar-background);
      vertical-align: middle;
    }

    [ngpAvatar]:before {
      content: '';
      position: absolute;
      inset: 0;
      border-radius: 9999px;
      box-shadow: inset 0 0 0 1px rgba(0, 0, 0, 0.1);
    }

    [ngpAvatarImage] {
      width: 100%;
      height: 100%;
    }

    [ngpAvatarFallback] {
      text-align: center;
      font-weight: 500;
      color: var(--ngp-text-emphasis);
    }
  `,
  template: `
    <span ngpAvatar>
      <img
        ngpAvatarImage
        src="https://angularprimitives.com/assets/avatar.png"
        alt="Profile Image"
      />
      <span ngpAvatarFallback>NG</span>
    </span>
  `,
})
export default class AvatarExample {}

```

## Import

Import the Avatar primitives from `ng-primitives/avatar`.

```ts
import { NgpAvatar, NgpAvatarImage, NgpAvatarFallback } from 'ng-primitives/avatar';
```

## Usage

Assemble the avatar directives in your template.

```html
<span ngpAvatar>
  <img ngpAvatarImage src="..." alt="..." />
  <span ngpAvatarFallback>NG</span>
</span>
```

## Reusable Component

Create a reusable component that uses the `NgpAvatar` directive.

## Reusable Component

```typescript
import { Component, input } from '@angular/core';
import { NgpAvatar, NgpAvatarFallback, NgpAvatarImage } from 'ng-primitives/avatar';

@Component({
  selector: 'app-avatar',
  hostDirectives: [NgpAvatar],
  imports: [NgpAvatarImage, NgpAvatarFallback],
  template: `
    @if (image()) {
      <img [src]="image()" ngpAvatarImage alt="Profile Image" />
    }
    <span ngpAvatarFallback>{{ fallback() }}</span>
  `,
  styles: `
    :host {
      position: relative;
      display: inline-flex;
      width: 3rem;
      height: 3rem;
      align-items: center;
      justify-content: center;
      border-radius: 9999px;
      border-width: 2px;
      border-color: var(--ngp-avatar-border);
      background-color: var(--ngp-avatar-background);
      vertical-align: middle;
      overflow: hidden;
    }

    :host:before {
      content: '';
      position: absolute;
      inset: 0;
      border-radius: 9999px;
      box-shadow: inset 0 0 0 1px rgba(0, 0, 0, 0.1);
    }

    [ngpAvatarImage] {
      width: 100%;
      height: 100%;
    }

    [ngpAvatarFallback] {
      text-align: center;
      font-weight: 500;
      color: var(--ngp-text-emphasis);
    }
  `,
})
export class Avatar {
  /** Define the avatar image source */
  readonly image = input<string>();

  /** Define the avatar fallback text */
  readonly fallback = input<string>();
}

```

## Schematics

Generate a reusable avatar component using the Angular CLI.

```bash npm
ng g ng-primitives:primitive avatar
```

### Options

- `path`: The path at which to create the component file.
- `prefix`: The prefix to apply to the generated component selector.
- `componentSuffix`: The suffix to apply to the generated component class name.
- `fileSuffix`: The suffix to apply to the generated component file name. Defaults to `component`.
- `exampleStyles`: Whether to include example styles in the generated component file. Defaults to `true`.

## API Reference

The following directives are available to import from the `ng-primitives/avatar` package:

### NgpAvatar

## API Reference

### NgpAvatar

Apply the `ngpAvatar` directive to an element that represents the avatar. This directive is a container for the image and/or fallback.

**Selector:** `[ngpAvatar]`

#### Export As

`ngpAvatar`



#### Data Attributes

| Attribute     | Description                             | Value                                      |
| ------------- | --------------------------------------- | ------------------------------------------ |
| `data-status` | The loading status of the avatar image. | `idle` \| `loading` \| `loaded` \| `error` |

### NgpAvatarImage

## API Reference

### NgpAvatarImage

Apply the `ngpAvatarImage` directive to an element that represents the avatar image. This would typically be an `img` element or a `div` with a background image.

**Selector:** `img[ngpAvatarImage]`

#### Export As

`ngpAvatarImage`



### NgpAvatarFallback

## API Reference

### NgpAvatarFallback

Apply the `ngpAvatarFallback` directive to an element that represents the user in the absence of an image. This is typically the user's initials.

**Selector:** `[ngpAvatarFallback]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpAvatarFallbackDelay` | `number` | `0` | Define a delay before the fallback is shown. This is useful to only show the fallback for those with slower connections. |

#### Export As

`ngpAvatarFallback`



## Global Configuration

You can configure the default options for all avatars in your application by using the `provideAvatarConfig` function in a providers array.

```ts
import { provideAvatarConfig } from 'ng-primitives/avatar';

bootstrapApplication(AppComponent, {
  providers: [provideAvatarConfig({ delay: 1000 })],
});
```

### NgpAvatarConfig

<prop-details name="delay" type="number">
  Define a delay before the fallback is shown. This is useful to only show the fallback for those
  with slower connections.
</prop-details>


---

### Breadcrumbs

File: primitives/breadcrumbs.md
URL: https://angularprimitives.com/primitives/breadcrumbs

# Breadcrumbs

Help users understand their location within a hierarchy with a fully accessible breadcrumb trail.

## Example

```typescript
import { Component } from '@angular/core';
import { NgIcon, provideIcons } from '@ng-icons/core';
import { lucideChevronRight, lucideMoreHorizontal } from '@ng-icons/lucide';
import {
  NgpBreadcrumbEllipsis,
  NgpBreadcrumbItem,
  NgpBreadcrumbLink,
  NgpBreadcrumbList,
  NgpBreadcrumbPage,
  NgpBreadcrumbs,
  NgpBreadcrumbSeparator,
} from 'ng-primitives/breadcrumbs';
import { NgpMenu, NgpMenuItem, NgpMenuTrigger } from 'ng-primitives/menu';

@Component({
  selector: 'app-breadcrumbs',
  imports: [
    NgpBreadcrumbs,
    NgpBreadcrumbList,
    NgpBreadcrumbItem,
    NgpBreadcrumbLink,
    NgpBreadcrumbPage,
    NgpBreadcrumbSeparator,
    NgpBreadcrumbEllipsis,
    NgpMenu,
    NgpMenuTrigger,
    NgpMenuItem,
    NgIcon,
  ],
  providers: [provideIcons({ lucideChevronRight, lucideMoreHorizontal })],
  styles: `
    :host {
      display: contents;
    }

    [ngpBreadcrumbs] {
      display: block;
    }

    [ngpBreadcrumbList] {
      display: flex;
      flex-wrap: wrap;
      align-items: center;
      gap: 0.4rem;
      list-style: none;
      margin: 0;
      padding: 0;
      font-size: 0.875rem;
      color: var(--ngp-text-secondary);
    }

    [ngpBreadcrumbItem] {
      display: inline-flex;
      align-items: center;
      gap: 0.35rem;
    }

    [ngpBreadcrumbLink] {
      color: inherit;
      text-decoration: none;
      transition: color 150ms ease;
    }

    [ngpBreadcrumbLink][data-hover] {
      color: var(--ngp-text-primary);
    }

    [ngpBreadcrumbLink][data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 2px;
    }

    [ngpBreadcrumbPage] {
      font-weight: 500;
      color: var(--ngp-text-primary);
    }

    [ngpBreadcrumbSeparator] {
      color: var(--ngp-border-strong);
      display: inline-flex;
      align-items: center;
      padding: 0;
    }

    [ngpBreadcrumbEllipsis] {
      display: inline-flex;
      align-items: center;
      justify-content: center;
      width: 2.25rem;
      height: 2.25rem;
      border-radius: 999px;
      color: var(--ngp-text-secondary);
      padding: 0;
      border: none;
      background: none;
      cursor: pointer;
    }

    [ngpBreadcrumbEllipsis] ng-icon {
      --ng-icon__size: 1.1rem;
    }

    [ngpBreadcrumbEllipsis][data-hover] {
      color: var(--ngp-text-primary);
    }

    [ngpBreadcrumbEllipsis][data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 2px;
    }

    [ngpBreadcrumbSeparator] ng-icon {
      --ng-icon__size: 0.85rem;
    }

    .sr-only {
      position: absolute;
      width: 1px;
      height: 1px;
      padding: 0;
      margin: -1px;
      overflow: hidden;
      clip: rect(0, 0, 0, 0);
      white-space: nowrap;
      border: 0;
    }

    [ngpMenu] {
      position: fixed;
      display: flex;
      flex-direction: column;
      width: max-content;
      background: var(--ngp-background);
      border: 1px solid var(--ngp-border);
      box-shadow: var(--ngp-shadow-lg);
      border-radius: 8px;
      padding: 4px;
      transform-origin: var(--ngp-menu-transform-origin);
    }

    [ngpMenuItem] {
      padding: 6px 14px;
      border: none;
      background: none;
      cursor: pointer;
      transition: background-color 0.2s;
      border-radius: 4px;
      min-width: 140px;
      text-align: start;
      outline: none;
      font-size: 14px;
      font-weight: 400;
    }

    [ngpMenuItem][data-hover] {
      background-color: var(--ngp-background-hover);
    }

    [ngpMenuItem][data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
    }
  `,
  template: `
    <nav aria-label="Breadcrumb" ngpBreadcrumbs>
      <ol ngpBreadcrumbList>
        <li ngpBreadcrumbItem>
          <a ngpBreadcrumbLink href="#">Home</a>
        </li>
        <li ngpBreadcrumbSeparator aria-hidden="true">
          <ng-icon name="lucideChevronRight" />
        </li>
        <li ngpBreadcrumbItem>
          <button
            [ngpMenuTrigger]="breadcrumbMenu"
            type="button"
            aria-label="Toggle breadcrumb menu"
          >
            <span ngpBreadcrumbEllipsis>
              <ng-icon name="lucideMoreHorizontal" />
            </span>
          </button>

          <ng-template #breadcrumbMenu>
            <div ngpMenu>
              <button ngpMenuItem>Documentation</button>
              <button ngpMenuItem>Themes</button>
              <button ngpMenuItem>GitHub</button>
            </div>
          </ng-template>
        </li>
        <li ngpBreadcrumbSeparator>
          <ng-icon name="lucideChevronRight" />
        </li>
        <li ngpBreadcrumbItem>
          <a ngpBreadcrumbLink href="#">Components</a>
        </li>
        <li ngpBreadcrumbSeparator>
          <ng-icon name="lucideChevronRight" />
        </li>
        <li ngpBreadcrumbItem>
          <span ngpBreadcrumbPage>Breadcrumbs</span>
        </li>
      </ol>
    </nav>
  `,
})
export default class BreadcrumbsExample {}

```

## Import

Import the Breadcrumb primitives from `ng-primitives/breadcrumbs`.

```ts
import {
  NgpBreadcrumbs,
  NgpBreadcrumbList,
  NgpBreadcrumbItem,
  NgpBreadcrumbLink,
  NgpBreadcrumbSeparator,
  NgpBreadcrumbEllipsis,
  NgpBreadcrumbPage,
} from 'ng-primitives/breadcrumbs';
```

## Usage

Assemble the directives to build the breadcrumb structure, applying your own `aria-label` to describe the navigation context. You can optionally wire the ellipsis into the Menu primitives to expose collapsed sections.

```html
<nav aria-label="Breadcrumb" ngpBreadcrumbs>
  <ol ngpBreadcrumbList>
    <li ngpBreadcrumbItem>
      <a ngpBreadcrumbLink href="/">Home</a>
    </li>

    <li ngpBreadcrumbSeparator>/</li>

    <li ngpBreadcrumbItem>
      <button type="button" aria-label="Toggle breadcrumb menu">
        <span ngpBreadcrumbEllipsis>...</span>
      </button>
    </li>

    <li ngpBreadcrumbSeparator>/</li>

    <li ngpBreadcrumbItem>
      <a ngpBreadcrumbLink href="...">Components</a>
    </li>

    <li ngpBreadcrumbSeparator>/</li>

    <li ngpBreadcrumbItem>
      <span ngpBreadcrumbPage>Breadcrumbs</span>
    </li>
  </ol>
</nav>
```

## API Reference

The following directives are available to import from the `ng-primitives/breadcrumbs` package:

### NgpBreadcrumbs

## API Reference

### NgpBreadcrumbs

Apply `ngpBreadcrumbs` to the navigation element that wraps the breadcrumb trail.

**Selector:** `[ngpBreadcrumbs]`

#### Export As

`ngpBreadcrumbs`



### NgpBreadcrumbList

## API Reference

### NgpBreadcrumbList

Apply `ngpBreadcrumbList` to the ordered list that groups breadcrumb items.

**Selector:** `[ngpBreadcrumbList]`

#### Export As

`ngpBreadcrumbList`



### NgpBreadcrumbItem

## API Reference

### NgpBreadcrumbItem

Apply `ngpBreadcrumbItem` to each list item in the breadcrumb trail.

**Selector:** `[ngpBreadcrumbItem]`

#### Export As

`ngpBreadcrumbItem`



### NgpBreadcrumbLink

## API Reference

### NgpBreadcrumbLink

Apply `ngpBreadcrumbLink` to anchors or buttons that navigate to a breadcrumb destination.

**Selector:** `[ngpBreadcrumbLink]`

#### Export As

`ngpBreadcrumbLink`



#### Data Attributes

| Attribute            | Description                                   |
| -------------------- | --------------------------------------------- |
| `data-hover`         | Applied when the breadcrumb link is hovered.  |
| `data-press`         | Applied when the breadcrumb link is pressed.  |
| `data-focus-visible` | Applied when the link receives focus visibly. |
| `data-current`       | Applied when the link represents the page.    |

### NgpBreadcrumbPage

## API Reference

### NgpBreadcrumbPage

Apply `ngpBreadcrumbPage` to non-link content that represents the active page.

**Selector:** `[ngpBreadcrumbPage]`

#### Export As

`ngpBreadcrumbPage`



#### Data Attributes

| Attribute      | Description                               |
| -------------- | ----------------------------------------- |
| `data-current` | Applied to indicate the current location. |

### NgpBreadcrumbSeparator

## API Reference

### NgpBreadcrumbSeparator

Apply `ngpBreadcrumbSeparator` between breadcrumb items to render a visual divider.

**Selector:** `[ngpBreadcrumbSeparator]`

#### Export As

`ngpBreadcrumbSeparator`



### NgpBreadcrumbEllipsis

## API Reference

### NgpBreadcrumbEllipsis

Apply `ngpBreadcrumbEllipsis` to elements that represent collapsed breadcrumb items.

**Selector:** `[ngpBreadcrumbEllipsis]`

#### Export As

`ngpBreadcrumbEllipsis`



## Accessibility

Adheres to the [WAI-ARIA Breadcrumb Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/).

- Breadcrumbs are rendered within a `nav` landmark with an accessible label.
- Separators are hidden from assistive technologies via `role="presentation"` and `aria-hidden`.
- The current location uses `aria-current="page"` for accurate announcements.


---

### Button

File: primitives/button.md
URL: https://angularprimitives.com/primitives/button

# Button

A button is a clickable element that can be used to trigger an action. This primitive enhances the native button element with improved accessibility and interaction handling for hover, press and focus.

## Example

```typescript
import { Component } from '@angular/core';
import { NgpButton } from 'ng-primitives/button';

@Component({
  selector: 'app-button',
  imports: [NgpButton],
  template: `
    <button ngpButton>Button</button>
  `,
  styles: `
    [ngpButton] {
      padding-left: 1rem;
      padding-right: 1rem;
      border-radius: 0.5rem;
      color: var(--ngp-text-primary);
      border: none;
      height: 2.5rem;
      font-weight: 500;
      background-color: var(--ngp-background);
      transition: background-color 300ms cubic-bezier(0.4, 0, 0.2, 1);
      box-shadow: var(--ngp-button-shadow);
    }

    [ngpButton][data-hover] {
      background-color: var(--ngp-background-hover);
    }

    [ngpButton][data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
    }

    [ngpButton][data-press] {
      background-color: var(--ngp-background-active);
    }
  `,
})
export default class ButtonExample {}

```

## Import

Import the Button primitives from `ng-primitives/button`.

```ts
import { NgpButton } from 'ng-primitives/button';
```

## Usage

Assemble the button directives in your template.

```html
<button ngpButton>Button</button>
```

## Reusable Component

Create a button component that uses the `NgpButton` directive.

## Reusable Component

```typescript
import { Component, input } from '@angular/core';
import { NgpButton } from 'ng-primitives/button';

/**
 * The size of the button.
 */
export type ButtonSize = 'sm' | 'md' | 'lg' | 'xl';

/**
 * The variant of the button.
 */
export type ButtonVariant = 'primary' | 'secondary' | 'destructive' | 'outline' | 'ghost' | 'link';

@Component({
  selector: 'button[app-button]',
  hostDirectives: [{ directive: NgpButton, inputs: ['disabled'] }],
  template: `
    <ng-content select="[slot=leading]" />
    <ng-content />
    <ng-content select="[slot=trailing]" />
  `,
  host: {
    '[attr.data-size]': 'size()',
    '[attr.data-variant]': 'variant()',
  },
  styles: `
    :host {
      padding-left: 1rem;
      padding-right: 1rem;
      border-radius: 0.5rem;
      color: var(--ngp-text-primary);
      border: none;
      height: 2.5rem;
      font-weight: 500;
      background-color: var(--ngp-background);
      transition: background-color 300ms cubic-bezier(0.4, 0, 0.2, 1);
      box-shadow: var(--ngp-button-shadow);
      box-sizing: border-box;
      display: inline-flex;
      align-items: center;
      justify-content: center;
      cursor: pointer;
      gap: 0.5rem;
    }

    :host[data-hover] {
      background-color: var(--ngp-background-hover);
    }

    :host[data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
    }

    :host[data-press] {
      background-color: var(--ngp-background-active);
    }

    /* Size variants */
    :host[data-size='sm'] {
      height: 2rem;
      padding-left: 0.75rem;
      padding-right: 0.75rem;
      font-size: 0.875rem;
      --ng-icon__size: 0.875rem;
    }

    :host[data-size='md'],
    :host:not([data-size]) {
      height: 2.5rem;
      padding-left: 1rem;
      padding-right: 1rem;
      font-size: 0.875rem;
      --ng-icon__size: 0.875rem;
    }

    :host[data-size='lg'] {
      height: 3rem;
      padding-left: 1.25rem;
      padding-right: 1.25rem;
      font-size: 1rem;
      --ng-icon__size: 1rem;
    }

    :host[data-size='xl'] {
      height: 3.5rem;
      padding-left: 1.5rem;
      padding-right: 1.5rem;
      font-size: 1.125rem;
      --ng-icon__size: 1.125rem;
    }

    /* Variant styles */
    :host[data-variant='primary'],
    :host:not([data-variant]) {
      background-color: var(--ngp-background);
      color: var(--ngp-text-primary);
      border: none;
    }

    :host[data-variant='primary'][data-hover],
    :host:not([data-variant])[data-hover] {
      background-color: var(--ngp-background-hover);
    }

    :host[data-variant='primary'][data-press],
    :host:not([data-variant])[data-press] {
      background-color: var(--ngp-background-active);
    }

    :host[data-variant='secondary'] {
      background-color: var(--ngp-secondary-background, #f1f5f9);
      color: var(--ngp-secondary-text, #0f172a);
      border: none;
    }

    :host[data-variant='secondary'][data-hover] {
      background-color: var(--ngp-secondary-background-hover, #e2e8f0);
    }

    :host[data-variant='secondary'][data-press] {
      background-color: var(--ngp-secondary-background-active, #cbd5e1);
    }

    :host[data-variant='destructive'] {
      background-color: var(--ngp-destructive-background, #ef4444);
      color: var(--ngp-destructive-text, #ffffff);
      border: none;
    }

    :host[data-variant='destructive'][data-hover] {
      background-color: var(--ngp-destructive-background-hover, #dc2626);
    }

    :host[data-variant='destructive'][data-press] {
      background-color: var(--ngp-destructive-background-active, #b91c1c);
    }

    :host[data-variant='outline'] {
      background-color: transparent;
      color: var(--ngp-text-primary);
      border: 1px solid var(--ngp-outline-border, #e2e8f0);
      box-shadow: none;
    }

    :host[data-variant='outline'][data-hover] {
      background-color: var(--ngp-background-hover);
      border-color: var(--ngp-outline-border-hover, #cbd5e1);
    }

    :host[data-variant='outline'][data-press] {
      background-color: var(--ngp-outline-background-active, rgba(15, 23, 42, 0.1));
    }

    :host[data-variant='ghost'] {
      background-color: transparent;
      color: var(--ngp-text-primary);
      border: none;
      box-shadow: none;
    }

    :host[data-variant='ghost'][data-hover] {
      background-color: var(--ngp-background-hover);
    }

    :host[data-variant='ghost'][data-press] {
      background-color: var(--ngp-background-active);
    }

    :host[data-variant='link'] {
      background-color: transparent;
      color: var(--ngp-link-color, #3b82f6);
      border: none;
      box-shadow: none;
      text-decoration: underline;
      text-underline-offset: 4px;
    }

    :host[data-variant='link'][data-hover] {
      text-decoration-thickness: 2px;
    }

    :host[disabled] {
      opacity: 0.5;
      cursor: not-allowed;
    }
  `,
})
export class Button {
  /**
   * The size of the button.
   */
  readonly size = input<ButtonSize>('md');

  /**
   * The variant of the button.
   */
  readonly variant = input<ButtonVariant>('primary');
}

```

## Examples

### Button Sizes

You can add size support to your reusable button component. This is implemented at the component level rather than in the primitive to provide more flexibility for different design systems.

## Example

```typescript
import { Component, input } from '@angular/core';
import { NgpButton } from 'ng-primitives/button';

/**
 * The size of the button.
 */
export type ButtonSize = 'sm' | 'md' | 'lg' | 'xl';

@Component({
  selector: 'button[app-button]',
  hostDirectives: [{ directive: NgpButton, inputs: ['disabled'] }],
  template: '<ng-content />',
  host: {
    '[attr.data-size]': 'size()',
  },
  styles: `
    :host {
      padding-left: 1rem;
      padding-right: 1rem;
      border-radius: 0.5rem;
      color: var(--ngp-text-primary);
      border: none;
      height: 2.5rem;
      font-weight: 500;
      background-color: var(--ngp-background);
      transition: background-color 300ms cubic-bezier(0.4, 0, 0.2, 1);
      box-shadow: var(--ngp-button-shadow);
      box-sizing: border-box;
    }

    :host[data-hover] {
      background-color: var(--ngp-background-hover);
    }

    :host[data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
    }

    :host[data-press] {
      background-color: var(--ngp-background-active);
    }

    /* Size variants */
    :host[data-size='sm'] {
      height: 2rem;
      padding-left: 0.75rem;
      padding-right: 0.75rem;
      font-size: 0.875rem;
    }

    :host[data-size='md'],
    :host:not([data-size]) {
      height: 2.5rem;
      padding-left: 1rem;
      padding-right: 1rem;
      font-size: 0.875rem;
    }

    :host[data-size='lg'] {
      height: 3rem;
      padding-left: 1.25rem;
      padding-right: 1.25rem;
      font-size: 1rem;
    }

    :host[data-size='xl'] {
      height: 3.5rem;
      padding-left: 1.5rem;
      padding-right: 1.5rem;
      font-size: 1.125rem;
    }
  `,
})
export class Button {
  /**
   * The size of the button.
   */
  readonly size = input<ButtonSize>('md');
}

@Component({
  selector: 'app-button-sizes-example',
  imports: [Button],
  template: `
    <div class="button-container">
      <button size="sm" app-button>Small</button>
      <button app-button>Medium</button>
      <button size="lg" app-button>Large</button>
      <button size="xl" app-button>Extra Large</button>
    </div>
  `,
  styles: `
    .button-container {
      display: flex;
      flex-wrap: wrap;
      align-items: center;
      gap: 1rem;
    }
  `,
})
export default class ButtonSizesExample {}

```

### Button Variants

You can add variant support to your reusable button component to indicate different purposes or importance levels.

## Example

```typescript
import { Component, input } from '@angular/core';
import { NgpButton } from 'ng-primitives/button';

/**
 * The variant of the button.
 */
export type ButtonVariant = 'primary' | 'secondary' | 'destructive' | 'outline' | 'ghost' | 'link';

@Component({
  selector: 'button[app-button]',
  hostDirectives: [{ directive: NgpButton, inputs: ['disabled'] }],
  template: '<ng-content />',
  host: {
    '[attr.data-variant]': 'variant()',
  },
  styles: `
    :host {
      padding-left: 1rem;
      padding-right: 1rem;
      border-radius: 0.5rem;
      color: var(--ngp-text-primary);
      border: none;
      height: 2.5rem;
      font-weight: 500;
      background-color: var(--ngp-background);
      transition: background-color 300ms cubic-bezier(0.4, 0, 0.2, 1);
      box-shadow: var(--ngp-button-shadow);
      box-sizing: border-box;
      display: inline-flex;
      align-items: center;
      justify-content: center;
      cursor: pointer;
    }

    :host[data-variant='primary'],
    :host:not([data-variant]) {
      background-color: var(--ngp-background);
      color: var(--ngp-text-primary);
      border: none;
    }

    :host[data-variant='primary'][data-hover],
    :host:not([data-variant])[data-hover] {
      background-color: var(--ngp-background-hover);
    }

    :host[data-variant='primary'][data-press],
    :host:not([data-variant])[data-press] {
      background-color: var(--ngp-background-active);
    }

    :host[data-variant='secondary'] {
      background-color: var(--ngp-secondary-background, #f1f5f9);
      color: var(--ngp-secondary-text, #0f172a);
      border: none;
    }

    :host[data-variant='secondary'][data-hover] {
      background-color: var(--ngp-secondary-background-hover, #e2e8f0);
    }

    :host[data-variant='secondary'][data-press] {
      background-color: var(--ngp-secondary-background-active, #cbd5e1);
    }

    :host[data-variant='destructive'] {
      background-color: var(--ngp-destructive-background, #ef4444);
      color: var(--ngp-destructive-text, #ffffff);
      border: none;
    }

    :host[data-variant='destructive'][data-hover] {
      background-color: var(--ngp-destructive-background-hover, #dc2626);
    }

    :host[data-variant='destructive'][data-press] {
      background-color: var(--ngp-destructive-background-active, #b91c1c);
    }

    :host[data-variant='outline'] {
      background-color: transparent;
      color: var(--ngp-text-primary);
      border: 1px solid var(--ngp-outline-border, #e2e8f0);
      box-shadow: none;
    }

    :host[data-variant='outline'][data-hover] {
      background-color: var(--ngp-background-hover);
      border-color: var(--ngp-outline-border-hover, #cbd5e1);
    }

    :host[data-variant='outline'][data-press] {
      background-color: var(--ngp-outline-background-active, rgba(15, 23, 42, 0.1));
    }

    :host[data-variant='ghost'] {
      background-color: transparent;
      color: var(--ngp-text-primary);
      border: none;
      box-shadow: none;
    }

    :host[data-variant='ghost'][data-hover] {
      background-color: var(--ngp-background-hover);
    }

    :host[data-variant='ghost'][data-press] {
      background-color: var(--ngp-ghost-background-active, rgba(15, 23, 42, 0.1));
    }

    :host[data-variant='link'] {
      background-color: transparent;
      color: var(--ngp-text-primary);
      border: none;
      box-shadow: none;
      text-decoration-line: none;
      height: auto;
      padding: 0;
    }

    :host[data-variant='link'][data-hover] {
      text-decoration-line: underline;
    }

    :host[data-variant='link'][data-press] {
      text-decoration-line: underline;
    }

    :host[data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
    }
  `,
})
export class Button {
  /**
   * The variant of the button.
   */
  readonly variant = input<ButtonVariant>('primary');
}

@Component({
  selector: 'app-button-variants-example',
  imports: [Button],
  template: `
    <div class="button-container">
      <button app-button>Primary</button>
      <button variant="secondary" app-button>Secondary</button>
      <button variant="destructive" app-button>Destructive</button>
      <button variant="outline" app-button>Outline</button>
      <button variant="ghost" app-button>Ghost</button>
      <button variant="link" app-button>Link</button>
    </div>
  `,
  styles: `
    .button-container {
      display: flex;
      flex-wrap: wrap;
      align-items: center;
      gap: 1rem;
    }
  `,
})
export default class ButtonVariantsExample {}

```

### Button with Icons

You can add icons to your buttons using any Angular icon library or simple SVG elements, but we recommend the [`@ng-icons`](https://github.com/ng-icons/ng-icons) library. This example shows how to create buttons with icons on the leading, trailing, or both sides using content projection slots.

## Example

```typescript
import { Component, input } from '@angular/core';
import { NgIcon, provideIcons } from '@ng-icons/core';
import {
  lucideArrowRight,
  lucideCheck,
  lucideChevronRight,
  lucideShoppingBasket,
} from '@ng-icons/lucide';
import { NgpButton } from 'ng-primitives/button';

/**
 * The size of the button.
 */
export type ButtonSize = 'sm' | 'md' | 'lg' | 'xl';

/**
 * The variant of the button.
 */
export type ButtonVariant = 'primary' | 'secondary' | 'destructive' | 'outline' | 'ghost' | 'link';

@Component({
  selector: 'button[app-button]',
  hostDirectives: [{ directive: NgpButton, inputs: ['disabled'] }],
  template: `
    <ng-content select="[slot=leading]" />
    <ng-content />
    <ng-content select="[slot=trailing]" />
  `,
  host: {
    '[attr.data-size]': 'size()',
    '[attr.data-variant]': 'variant()',
  },
  styles: `
    :host {
      padding-left: 1rem;
      padding-right: 1rem;
      border-radius: 0.5rem;
      color: var(--ngp-text-primary);
      border: none;
      height: 2.5rem;
      font-weight: 500;
      background-color: var(--ngp-background);
      transition: background-color 300ms cubic-bezier(0.4, 0, 0.2, 1);
      box-shadow: var(--ngp-button-shadow);
      box-sizing: border-box;
      display: inline-flex;
      align-items: center;
      justify-content: center;
      cursor: pointer;
      gap: 0.5rem;
    }

    :host[data-hover] {
      background-color: var(--ngp-background-hover);
    }

    :host[data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
    }

    :host[data-press] {
      background-color: var(--ngp-background-active);
    }

    /* Size variants */
    :host[data-size='sm'] {
      height: 2rem;
      padding-left: 0.75rem;
      padding-right: 0.75rem;
      font-size: 0.875rem;
      --ng-icon__size: 0.875rem;
    }

    :host[data-size='md'],
    :host:not([data-size]) {
      height: 2.5rem;
      padding-left: 1rem;
      padding-right: 1rem;
      font-size: 0.875rem;
      --ng-icon__size: 0.875rem;
    }

    :host[data-size='lg'] {
      height: 3rem;
      padding-left: 1.25rem;
      padding-right: 1.25rem;
      font-size: 1rem;
      --ng-icon__size: 1rem;
    }

    :host[data-size='xl'] {
      height: 3.5rem;
      padding-left: 1.5rem;
      padding-right: 1.5rem;
      font-size: 1.125rem;
      --ng-icon__size: 1.125rem;
    }

    /* Variant styles */
    :host[data-variant='primary'],
    :host:not([data-variant]) {
      background-color: var(--ngp-background);
      color: var(--ngp-text-primary);
      border: none;
    }

    :host[data-variant='primary'][data-hover],
    :host:not([data-variant])[data-hover] {
      background-color: var(--ngp-background-hover);
    }

    :host[data-variant='primary'][data-press],
    :host:not([data-variant])[data-press] {
      background-color: var(--ngp-background-active);
    }

    :host[data-variant='secondary'] {
      background-color: var(--ngp-secondary-background, #f1f5f9);
      color: var(--ngp-secondary-text, #0f172a);
      border: none;
    }

    :host[data-variant='secondary'][data-hover] {
      background-color: var(--ngp-secondary-background-hover, #e2e8f0);
    }

    :host[data-variant='secondary'][data-press] {
      background-color: var(--ngp-secondary-background-active, #cbd5e1);
    }

    :host[data-variant='destructive'] {
      background-color: var(--ngp-destructive-background, #ef4444);
      color: var(--ngp-destructive-text, #ffffff);
      border: none;
    }

    :host[data-variant='destructive'][data-hover] {
      background-color: var(--ngp-destructive-background-hover, #dc2626);
    }

    :host[data-variant='destructive'][data-press] {
      background-color: var(--ngp-destructive-background-active, #b91c1c);
    }

    :host[data-variant='outline'] {
      background-color: transparent;
      color: var(--ngp-text-primary);
      border: 1px solid var(--ngp-outline-border, #e2e8f0);
      box-shadow: none;
    }

    :host[data-variant='outline'][data-hover] {
      background-color: var(--ngp-background-hover);
      border-color: var(--ngp-outline-border-hover, #cbd5e1);
    }

    :host[data-variant='outline'][data-press] {
      background-color: var(--ngp-outline-background-active, rgba(15, 23, 42, 0.1));
    }

    :host[data-variant='ghost'] {
      background-color: transparent;
      color: var(--ngp-text-primary);
      border: none;
      box-shadow: none;
    }

    :host[data-variant='ghost'][data-hover] {
      background-color: var(--ngp-background-hover);
    }

    :host[data-variant='ghost'][data-press] {
      background-color: var(--ngp-background-active);
    }

    :host[data-variant='link'] {
      background-color: transparent;
      color: var(--ngp-link-color, #3b82f6);
      border: none;
      box-shadow: none;
      text-decoration: underline;
      text-underline-offset: 4px;
    }

    :host[data-variant='link'][data-hover] {
      text-decoration-thickness: 2px;
    }

    :host[disabled] {
      opacity: 0.5;
      cursor: not-allowed;
    }
  `,
})
export class Button {
  /**
   * The size of the button.
   */
  readonly size = input<ButtonSize>('md');

  /**
   * The variant of the button.
   */
  readonly variant = input<ButtonVariant>('primary');
}

@Component({
  selector: 'app-button-icon-example',
  imports: [Button, NgIcon],
  providers: [
    provideIcons({ lucideArrowRight, lucideCheck, lucideChevronRight, lucideShoppingBasket }),
  ],
  template: `
    <div class="button-container">
      <h3>Button with left icon</h3>
      <div class="button-row">
        <button app-button>
          <ng-icon slot="leading" name="lucideArrowRight" />
          Left Icon
        </button>
        <button app-button variant="secondary">
          <ng-icon slot="leading" name="lucideCheck" />
          Left Icon
        </button>
        <button app-button variant="destructive">
          <ng-icon slot="leading" name="lucideShoppingBasket" />
          Left Icon
        </button>
        <button app-button variant="outline">
          <ng-icon slot="leading" name="lucideChevronRight" />
          Left Icon
        </button>
      </div>

      <h3>Button with right icon</h3>
      <div class="button-row">
        <button app-button>
          Right Icon
          <ng-icon slot="trailing" name="lucideArrowRight" />
        </button>
        <button app-button variant="secondary">
          Right Icon
          <ng-icon slot="trailing" name="lucideCheck" />
        </button>
        <button app-button variant="destructive">
          Right Icon
          <ng-icon slot="trailing" name="lucideShoppingBasket" />
        </button>
        <button app-button variant="outline">
          Right Icon
          <ng-icon slot="trailing" name="lucideChevronRight" />
        </button>
      </div>

      <h3>Button sizes with icons</h3>
      <div class="button-row">
        <button app-button size="sm">
          <ng-icon slot="leading" name="lucideArrowRight" />
          Small
          <ng-icon slot="trailing" name="lucideCheck" />
        </button>
        <button app-button>
          <ng-icon slot="leading" name="lucideArrowRight" />
          Medium
          <ng-icon slot="trailing" name="lucideCheck" />
        </button>
        <button app-button size="lg">
          <ng-icon slot="leading" name="lucideArrowRight" />
          Large
          <ng-icon slot="trailing" name="lucideCheck" />
        </button>
        <button app-button size="xl">
          <ng-icon slot="leading" name="lucideArrowRight" />
          Extra Large
          <ng-icon slot="trailing" name="lucideCheck" />
        </button>
      </div>
    </div>
  `,
  styles: `
    .button-container {
      display: flex;
      flex-direction: column;
      gap: 1.5rem;
    }

    .button-row {
      display: flex;
      flex-wrap: wrap;
      align-items: center;
      gap: 1rem;
    }

    h3 {
      margin-bottom: 0.5rem;
      font-size: 1rem;
      font-weight: 500;
    }
  `,
})
export default class ButtonIconExample {}

```

## Schematics

Generate a reusable button component using the Angular CLI.

```bash npm
ng g ng-primitives:primitive button
```

### Options

- `path`: The path at which to create the component file.
- `prefix`: The prefix to apply to the generated component selector.
- `componentSuffix`: The suffix to apply to the generated component class name.
- `fileSuffix`: The suffix to apply to the generated component file name. Defaults to `component`.
- `exampleStyles`: Whether to include example styles in the generated component file. Defaults to `true`.

## API Reference

The following directives are available to import from the `ng-primitives/button` package:

### NgpButton

## API Reference

### NgpButton



**Selector:** `[ngpButton]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `disabled` | `boolean` | `-` | Whether the button is disabled. |

#### Export As

`ngpButton`



#### Data Attributes

| Attribute            | Description                        |
| -------------------- | ---------------------------------- |
| `data-hover`         | Added to the button when hovered.  |
| `data-focus-visible` | Added to the button when focused.  |
| `data-press`         | Added to the button when pressed.  |
| `data-disabled`      | Added to the button when disabled. |


---

### Checkbox

File: primitives/checkbox.md
URL: https://angularprimitives.com/primitives/checkbox

# Checkbox

Perform state toggling.

## Example

```typescript
import { Component, signal } from '@angular/core';
import { NgIcon, provideIcons } from '@ng-icons/core';
import { heroCheckMini } from '@ng-icons/heroicons/mini';
import { NgpCheckbox } from 'ng-primitives/checkbox';

@Component({
  selector: 'app-checkbox',
  imports: [NgIcon, NgpCheckbox],
  providers: [provideIcons({ heroCheckMini })],
  styles: `
    [ngpCheckbox] {
      display: flex;
      width: 1.25rem;
      height: 1.25rem;
      cursor: pointer;
      align-items: center;
      justify-content: center;
      border-radius: 0.25rem;
      border: 1px solid var(--ngp-border);
      background-color: transparent;
      padding: 0;
      outline: none;
      flex: none;
      color: var(--ngp-text-inverse);
      font-size: 0.75rem;
    }

    [ngpCheckbox][data-hover] {
      background-color: var(--ngp-background-hover);
    }

    [ngpCheckbox][data-checked],
    [ngpCheckbox][data-indeterminate] {
      border-color: var(--ngp-background-inverse);
      background-color: var(--ngp-background-inverse);
    }

    [ngpCheckbox][data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 2px;
    }
  `,
  template: `
    <span [(ngpCheckboxChecked)]="checked" ngpCheckbox>
      @if (checked()) {
        <ng-icon name="heroCheckMini" aria-hidden="true" />
      }
    </span>
  `,
})
export default class CheckboxExample {
  /**
   * The checked state of the checkbox.
   */
  readonly checked = signal(true);
}

```

## Import

Import the Checkbox primitives from `ng-primitives/checkbox`.

```ts
import { NgpCheckbox } from 'ng-primitives/checkbox';
```

## Usage

Assemble the checkbox directives in your template.

```html
<span ngpCheckbox [(ngpCheckboxChecked)]="checked">
  <ng-icon name="checkmark" aria-hidden="true" />
</span>
```

## Reusable Component

Create a reusable component that uses the `NgpCheckbox` directive.

## Reusable Component

```typescript
import { Component } from '@angular/core';
import { ControlValueAccessor } from '@angular/forms';
import { NgIcon, provideIcons } from '@ng-icons/core';
import { heroCheckMini, heroMinusMini } from '@ng-icons/heroicons/mini';
import { injectCheckboxState, NgpCheckbox } from 'ng-primitives/checkbox';
import { ChangeFn, provideValueAccessor, TouchedFn } from 'ng-primitives/utils';

@Component({
  selector: 'app-checkbox',
  hostDirectives: [
    {
      directive: NgpCheckbox,
      inputs: [
        'ngpCheckboxChecked:checked',
        'ngpCheckboxIndeterminate:indeterminate',
        'ngpCheckboxDisabled:disabled',
      ],
      outputs: [
        'ngpCheckboxCheckedChange:checkedChange',
        'ngpCheckboxIndeterminateChange:indeterminateChange',
      ],
    },
  ],
  providers: [provideValueAccessor(Checkbox), provideIcons({ heroCheckMini, heroMinusMini })],
  imports: [NgIcon],
  template: `
    @if (state().indeterminate()) {
      <ng-icon name="heroMinusMini" />
    } @else if (state().checked()) {
      <ng-icon name="heroCheckMini" />
    }
  `,
  styles: `
    :host {
      display: flex;
      width: 1.25rem;
      height: 1.25rem;
      cursor: pointer;
      align-items: center;
      justify-content: center;
      border-radius: 0.25rem;
      border: 1px solid var(--ngp-border);
      background-color: transparent;
      padding: 0;
      outline: none;
      flex: none;
      color: var(--ngp-text-inverse);
      font-size: 0.75rem;
    }

    :host[data-hover] {
      background-color: var(--ngp-background-hover);
    }

    :host[data-checked],
    :host[data-indeterminate] {
      border-color: var(--ngp-background-inverse);
      background-color: var(--ngp-background-inverse);
    }

    :host[data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 2px;
    }
  `,
  host: {
    '(focusout)': 'onTouchedFn?.()',
  },
})
export class Checkbox implements ControlValueAccessor {
  /**
   * The checked state of the checkbox.
   */
  protected readonly state = injectCheckboxState();

  /**
   * The onChange function for the checkbox.
   */
  protected onChangeFn?: ChangeFn<boolean>;

  /**
   * The onTouched function for the checkbox.
   */
  protected onTouchedFn?: TouchedFn;

  constructor() {
    // Whenever the user interacts with the checkbox, call the onChange function with the new value.
    this.state().checkedChange.subscribe(checked => this.onChangeFn?.(checked));
  }

  writeValue(checked: boolean): void {
    this.state().setChecked(checked);
  }

  registerOnChange(fn: ChangeFn<boolean>): void {
    this.onChangeFn = fn;
  }

  registerOnTouched(fn: TouchedFn): void {
    this.onTouchedFn = fn;
  }

  setDisabledState(isDisabled: boolean): void {
    this.state().setDisabled(isDisabled);
  }
}

```

## Schematics

Generate a reusable checkbox component using the Angular CLI.

```bash npm
ng g ng-primitives:primitive checkbox
```

### Options

- `path`: The path at which to create the component file.
- `prefix`: The prefix to apply to the generated component selector.
- `componentSuffix`: The suffix to apply to the generated component class name.
- `fileSuffix`: The suffix to apply to the generated component file name. Defaults to `component`.
- `exampleStyles`: Whether to include example styles in the generated component file. Defaults to `true`.

## Examples

Here are some additional examples of how to use the Checkbox primitives.

### Checkbox Form Field

The checkbox automatically integrates with the form field primitives.

## Example

```typescript
import { Component, signal } from '@angular/core';
import { NgIcon, provideIcons } from '@ng-icons/core';
import { heroCheckMini } from '@ng-icons/heroicons/mini';
import { NgpCheckbox } from 'ng-primitives/checkbox';
import { NgpDescription, NgpFormField, NgpLabel } from 'ng-primitives/form-field';

@Component({
  selector: 'app-checkbox-form-control',
  imports: [NgIcon, NgpCheckbox, NgpFormField, NgpLabel, NgpDescription],
  providers: [provideIcons({ heroCheckMini })],
  styles: `
    [ngpFormField] {
      display: flex;
      column-gap: 0.75rem;
      align-items: baseline;
    }

    [ngpCheckbox] {
      display: flex;
      width: 1.25rem;
      height: 1.25rem;
      cursor: pointer;
      align-items: center;
      justify-content: center;
      border-radius: 0.25rem;
      border: 1px solid var(--ngp-border);
      background-color: transparent;
      padding: 0;
      outline: none;
      flex: none;
    }

    [ngpCheckbox][data-hover] {
      background-color: var(--ngp-background-hover);
    }

    [ngpCheckbox][data-checked] {
      border-color: var(--ngp-background-inverse);
      background-color: var(--ngp-background-inverse);
    }

    [ngpCheckbox][data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 2px;
    }

    ng-icon {
      color: var(--ngp-text-inverse);
      font-size: 0.75rem;
    }

    [ngpLabel] {
      display: flex;
      flex-direction: column;
      row-gap: 0.125rem;
      font-weight: 500;
      font-size: 14px;
      line-height: 14px;
      color: var(--ngp-text-primary);
    }

    [ngpDescription] {
      font-size: 12px;
      line-height: 16px;
      color: var(--ngp-text-secondary);
    }
  `,
  template: `
    <div ngpFormField>
      <span [(ngpCheckboxChecked)]="checked" ngpCheckbox>
        @if (checked()) {
          <ng-icon name="heroCheckMini" aria-hidden="true" />
        }
      </span>

      <label ngpLabel>
        <p>Enable notifications</p>
        <p ngpDescription>Receive notifications when someone follows you.</p>
      </label>
    </div>
  `,
})
export default class CheckboxFormFieldExample {
  /**
   * The checked state of the checkbox.
   */
  readonly checked = signal(true);
}

```

## API Reference

The following directives are available to import from the `ng-primitives/checkbox` package:

### NgpCheckbox

## API Reference

### NgpCheckbox

Apply the `ngpCheckbox` directive to an element to that represents the checkbox, such as a `button`.

**Selector:** `[ngpCheckbox]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpCheckboxChecked` | `boolean` | `-` | Defines whether the checkbox is checked. |
| `ngpCheckboxIndeterminate` | `boolean` | `-` | Defines whether the checkbox is indeterminate. |
| `ngpCheckboxRequired` | `boolean` | `-` | Whether the checkbox is required. |
| `ngpCheckboxDisabled` | `boolean` | `-` | Defines whether the checkbox is disabled. |

#### Outputs

| Event | Type | Description |
|-------|------|-------------|
| `ngpCheckboxCheckedChange` | `boolean` | The event that is emitted when the checkbox value changes. |
| `ngpCheckboxIndeterminateChange` | `boolean` | The event that is emitted when the indeterminate value changes. |



| Attribute            | Description                                 |
| -------------------- | ------------------------------------------- |
| `data-checked`       | Applied when the checkbox is checked.       |
| `data-indeterminate` | Applied when the checkbox is indeterminate. |
| `data-disabled`      | Applied when the checkbox is disabled.      |
| `data-hover`         | Applied when the checkbox is hovered.       |
| `data-focus-visible` | Applied when the checkbox is focused.       |
| `data-press`         | Applied when the checkbox is pressed.       |

## Accessibility

Adheres to the [Tri-State Checkbox WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox).

### Keyboard Interactions

- <kbd>Space</kbd> - Toggle the checked state.


---

### Combobox

File: primitives/combobox.md
URL: https://angularprimitives.com/primitives/combobox

# Combobox

The Combobox primitive is a combination of a dropdown and an input field. It allows users to select from a list of options while filtering the list based on their input.

## Example

```typescript
import { Component, computed, signal } from '@angular/core';
import { NgIcon, provideIcons } from '@ng-icons/core';
import { heroChevronDown } from '@ng-icons/heroicons/outline';
import {
  NgpCombobox,
  NgpComboboxButton,
  NgpComboboxDropdown,
  NgpComboboxInput,
  NgpComboboxOption,
  NgpComboboxPortal,
} from 'ng-primitives/combobox';

@Component({
  selector: 'app-combobox',
  imports: [
    NgpCombobox,
    NgpComboboxDropdown,
    NgpComboboxOption,
    NgpComboboxInput,
    NgpComboboxPortal,
    NgpComboboxButton,
    NgIcon,
  ],
  providers: [provideIcons({ heroChevronDown })],
  template: `
    <div
      [(ngpComboboxValue)]="value"
      (ngpComboboxValueChange)="filter.set($event)"
      (ngpComboboxOpenChange)="resetOnClose($event)"
      ngpCombobox
    >
      <input
        [value]="filter()"
        (input)="onFilterChange($event)"
        placeholder="Select an option"
        ngpComboboxInput
      />

      <button ngpComboboxButton aria-label="Toggle dropdown">
        <ng-icon name="heroChevronDown" />
      </button>

      <div *ngpComboboxPortal ngpComboboxDropdown>
        @for (option of filteredOptions(); track option) {
          <div [ngpComboboxOptionValue]="option" ngpComboboxOption>
            {{ option }}
          </div>
        } @empty {
          <div class="empty-message">No options found</div>
        }
      </div>
    </div>
  `,
  styles: `
    [ngpCombobox] {
      display: flex;
      justify-content: space-between;
      align-items: center;
      height: 36px;
      width: 300px;
      border-radius: 8px;
      border: none;
      background-color: var(--ngp-background);
      box-shadow: var(--ngp-input-shadow);
      box-sizing: border-box;
    }

    [ngpCombobox][data-focus] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 2px;
    }

    [ngpComboboxInput] {
      flex: 1;
      padding: 0 16px;
      border: none;
      background-color: transparent;
      color: var(--ngp-text);
      font-family: inherit;
      font-size: 14px;
      padding: 0 16px;
      outline: none;
      height: 100%;
    }

    [ngpComboboxButton] {
      display: inline-flex;
      justify-content: center;
      align-items: center;
      height: 100%;
      width: 36px;
      background-color: transparent;
      border: none;
      color: var(--ngp-text);
      cursor: pointer;
      box-sizing: border-box;
    }

    [ngpComboboxDropdown] {
      background-color: var(--ngp-background);
      border: 1px solid var(--ngp-border);
      padding: 0.25rem;
      border-radius: 0.75rem;
      outline: none;
      position: absolute;
      animation: popover-show 0.1s ease-out;
      width: var(--ngp-combobox-width);
      box-shadow: var(--ngp-shadow-lg);
      box-sizing: border-box;
      margin-top: 4px;
      max-height: 240px;
      overflow-y: auto;
      z-index: 1001;
    }

    [ngpComboboxDropdown][data-enter] {
      animation: combobox-show 0.1s ease-out;
    }

    [ngpComboboxDropdown][data-exit] {
      animation: combobox-hide 0.1s ease-out;
    }

    [ngpComboboxOption] {
      display: flex;
      align-items: center;
      gap: 0.5rem;
      padding: 0.375rem 0.75rem;
      cursor: pointer;
      border-radius: 0.5rem;
      width: 100%;
      height: 36px;
      font-size: 14px;
      color: var(--ngp-text-primary);
      box-sizing: border-box;
    }

    [ngpComboboxOption][data-hover] {
      background-color: var(--ngp-background-hover);
    }

    [ngpComboboxOption][data-press] {
      background-color: var(--ngp-background-active);
    }

    [ngpComboboxOption][data-active] {
      background-color: var(--ngp-background-active);
    }

    .empty-message {
      display: flex;
      justify-content: center;
      align-items: center;
      padding: 0.5rem;
      color: var(--ngp-text-secondary);
      font-size: 14px;
      font-weight: 500;
      text-align: center;
    }

    @keyframes combobox-show {
      0% {
        opacity: 0;
        transform: translateY(-10px) scale(0.9);
      }
      100% {
        opacity: 1;
        transform: translateY(0) scale(1);
      }
    }

    @keyframes combobox-hide {
      0% {
        opacity: 1;
        transform: translateY(0) scale(1);
      }
      100% {
        opacity: 0;
        transform: translateY(-10px) scale(0.9);
      }
    }
  `,
})
export default class ComboboxExample {
  /** The options for the combobox. */
  readonly options: string[] = [
    'Marty McFly',
    'Doc Brown',
    'Biff Tannen',
    'George McFly',
    'Jennifer Parker',
    'Emmett Brown',
    'Einstein',
    'Clara Clayton',
    'Needles',
    'Goldie Wilson',
    'Marvin Berry',
    'Lorraine Baines',
    'Strickland',
  ];

  /** The selected value. */
  readonly value = signal<string | undefined>(undefined);

  /** The filter value. */
  readonly filter = signal<string>('');

  /** Get the filtered options. */
  protected readonly filteredOptions = computed(() =>
    this.options.filter(option => option.toLowerCase().includes(this.filter().toLowerCase())),
  );

  protected onFilterChange(event: Event): void {
    const input = event.target as HTMLInputElement;
    this.filter.set(input.value);
  }

  protected resetOnClose(open: boolean): void {
    // if the dropdown is closed, reset the filter value
    if (open) {
      return;
    }

    // if the filter value is empty, set the value to undefined
    if (this.filter() === '') {
      this.value.set(undefined);
    } else {
      // otherwise set the filter value to the selected value
      this.filter.set(this.value() ?? '');
    }
  }
}

```

## Import

Import the Combobox primitives from `ng-primitives/combobox`.

```ts
import {
  NgpCombobox,
  NgpComboboxButton,
  NgpComboboxDropdown,
  NgpComboboxInput,
  NgpComboboxOption,
  NgpComboboxPortal,
} from 'ng-primitives/combobox';
```

## Usage

Assemble the combobox directives in your template.

```html
<div ngpCombobox>
  <input ngpComboboxInput />
  <button ngpComboboxButton>▼</button>
  <div ngpComboboxDropdown>
    @for (option of options; track option) {
    <div ngpComboboxOption [ngpComboboxOptionValue]="option">{{ option }}</div>
    }
  </div>
</div>
```

### Without Input Field

You can also create a combobox without an input field, which is useful for select-like behavior with keyboard navigation:

```html
<div ngpCombobox>
  <button ngpComboboxButton>{{ selectedOption || 'Select an option' }} ▼</button>
  <div ngpComboboxDropdown>
    @for (option of options; track option) {
    <div ngpComboboxOption [ngpComboboxOptionValue]="option">{{ option }}</div>
    }
  </div>
</div>
```

When no input is present, the combobox element itself becomes focusable and supports full keyboard navigation.

## Reusable Component

Create a reusable component that uses the `NgpCombobox` directive.

## Reusable Component

```typescript
import { BooleanInput } from '@angular/cdk/coercion';
import { booleanAttribute, Component, computed, input, model, signal } from '@angular/core';
import { ControlValueAccessor } from '@angular/forms';
import { NgIcon, provideIcons } from '@ng-icons/core';
import { heroChevronDown } from '@ng-icons/heroicons/outline';
import {
  NgpCombobox,
  NgpComboboxButton,
  NgpComboboxDropdown,
  NgpComboboxInput,
  NgpComboboxOption,
  NgpComboboxPortal,
} from 'ng-primitives/combobox';
import { ChangeFn, provideValueAccessor, TouchedFn } from 'ng-primitives/utils';

@Component({
  selector: 'app-combobox',
  imports: [
    NgpCombobox,
    NgpComboboxDropdown,
    NgpComboboxOption,
    NgpComboboxInput,
    NgpComboboxPortal,
    NgpComboboxButton,
    NgIcon,
  ],
  providers: [provideIcons({ heroChevronDown }), provideValueAccessor(Combobox)],
  template: `
    <div
      [(ngpComboboxValue)]="value"
      [ngpComboboxDisabled]="disabled() || formDisabled()"
      (ngpComboboxOpenChange)="resetOnClose($event)"
      (ngpComboboxValueChange)="onValueChange($event)"
      ngpCombobox
    >
      <input
        [value]="filter()"
        [placeholder]="placeholder()"
        (input)="onFilterChange($event)"
        (blur)="onTouched?.()"
        ngpComboboxInput
      />

      <button ngpComboboxButton aria-label="Toggle dropdown">
        <ng-icon name="heroChevronDown" />
      </button>

      <div *ngpComboboxPortal ngpComboboxDropdown>
        @for (option of filteredOptions(); track option) {
          <div [ngpComboboxOptionValue]="option" ngpComboboxOption>
            {{ option }}
          </div>
        } @empty {
          <div class="empty-message">No options found</div>
        }
      </div>
    </div>
  `,
  styles: `
    [ngpCombobox] {
      display: flex;
      justify-content: space-between;
      align-items: center;
      height: 36px;
      width: 300px;
      border-radius: 8px;
      border: none;
      background-color: var(--ngp-background);
      box-shadow: var(--ngp-input-shadow);
      box-sizing: border-box;
    }

    [ngpCombobox][data-focus] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 2px;
    }

    [ngpComboboxInput] {
      flex: 1;
      padding: 0 16px;
      border: none;
      background-color: transparent;
      color: var(--ngp-text);
      font-family: inherit;
      font-size: 14px;
      padding: 0 16px;
      outline: none;
      height: 100%;
    }

    [ngpComboboxButton] {
      display: inline-flex;
      justify-content: center;
      align-items: center;
      height: 100%;
      width: 36px;
      background-color: transparent;
      border: none;
      color: var(--ngp-text);
      cursor: pointer;
      box-sizing: border-box;
    }

    [ngpComboboxDropdown] {
      background-color: var(--ngp-background);
      border: 1px solid var(--ngp-border);
      padding: 0.25rem;
      border-radius: 0.75rem;
      outline: none;
      position: absolute;
      animation: popover-show 0.1s ease-out;
      width: var(--ngp-combobox-width);
      box-shadow: var(--ngp-shadow-lg);
      box-sizing: border-box;
      margin-top: 4px;
      max-height: 240px;
      overflow-y: auto;
      transform-origin: var(--ngp-combobox-transform-origin);
    }

    [ngpComboboxDropdown][data-enter] {
      animation: combobox-show 0.1s ease-out;
    }

    [ngpComboboxDropdown][data-exit] {
      animation: combobox-hide 0.1s ease-out;
    }

    [ngpComboboxOption] {
      display: flex;
      align-items: center;
      gap: 0.5rem;
      padding: 0.375rem 0.75rem;
      cursor: pointer;
      border-radius: 0.5rem;
      width: 100%;
      height: 36px;
      font-size: 14px;
      color: var(--ngp-text-primary);
      box-sizing: border-box;
    }

    [ngpComboboxOption][data-hover] {
      background-color: var(--ngp-background-hover);
    }

    [ngpComboboxOption][data-press] {
      background-color: var(--ngp-background-active);
    }

    [ngpComboboxOption][data-active] {
      background-color: var(--ngp-background-active);
    }

    .empty-message {
      display: flex;
      justify-content: center;
      align-items: center;
      padding: 0.5rem;
      color: var(--ngp-text-secondary);
      font-size: 14px;
      font-weight: 500;
      text-align: center;
    }

    @keyframes combobox-show {
      0% {
        opacity: 0;
        transform: translateY(-10px) scale(0.9);
      }
      100% {
        opacity: 1;
        transform: translateY(0) scale(1);
      }
    }

    @keyframes combobox-hide {
      0% {
        opacity: 1;
        transform: translateY(0) scale(1);
      }
      100% {
        opacity: 0;
        transform: translateY(-10px) scale(0.9);
      }
    }
  `,
})
export class Combobox implements ControlValueAccessor {
  /** The options for the combobox. */
  readonly options = input<string[]>([]);

  /** The selected value. */
  readonly value = model<string | undefined>();

  /** The placeholder for the input. */
  readonly placeholder = input<string>('');

  /** The disabled state of the combobox. */
  readonly disabled = input<boolean, BooleanInput>(false, {
    transform: booleanAttribute,
  });

  /** The filter value. */
  protected readonly filter = signal<string>('');

  /** Get the filtered options. */
  protected readonly filteredOptions = computed(() =>
    this.options().filter(option => option.toLowerCase().includes(this.filter().toLowerCase())),
  );

  /** Store the form disabled state */
  protected readonly formDisabled = signal(false);

  /** The on change callback */
  private onChange?: ChangeFn<string>;

  /** The on touch callback */
  protected onTouched?: TouchedFn;

  onFilterChange(event: Event): void {
    const input = event.target as HTMLInputElement;
    this.filter.set(input.value);
  }

  writeValue(value: string | undefined): void {
    this.value.set(value);
    this.filter.set(value ?? '');
  }

  registerOnChange(fn: ChangeFn<string | undefined>): void {
    this.onChange = fn;
  }

  registerOnTouched(fn: TouchedFn): void {
    this.onTouched = fn;
  }

  setDisabledState(isDisabled: boolean): void {
    this.formDisabled.set(isDisabled);
  }

  protected onValueChange(value: string): void {
    this.onChange?.(value);
    // update the filter value
    this.filter.set(value);
  }

  protected resetOnClose(open: boolean): void {
    // if the dropdown is closed, reset the filter value
    if (open) {
      return;
    }

    // if the filter value is empty, set the value to undefined
    if (this.filter() === '') {
      this.value.set(undefined);
    } else {
      // otherwise set the filter value to the selected value
      this.filter.set(this.value() ?? '');
    }
  }
}

```

## Examples

### Button-only Combobox

This example demonstrates a combobox without an input field. The combobox element itself becomes focusable.

## Example

```typescript
import { Component, signal } from '@angular/core';
import { NgIcon, provideIcons } from '@ng-icons/core';
import { heroChevronDown } from '@ng-icons/heroicons/outline';
import {
  NgpCombobox,
  NgpComboboxButton,
  NgpComboboxDropdown,
  NgpComboboxOption,
  NgpComboboxPortal,
} from 'ng-primitives/combobox';

@Component({
  selector: 'app-combobox-button',
  imports: [
    NgpCombobox,
    NgpComboboxDropdown,
    NgpComboboxOption,
    NgpComboboxPortal,
    NgpComboboxButton,
    NgIcon,
  ],
  providers: [provideIcons({ heroChevronDown })],
  template: `
    <div [(ngpComboboxValue)]="value" ngpCombobox>
      <button ngpComboboxButton>
        {{ value() || 'Select a character' }}
        <ng-icon name="heroChevronDown" />
      </button>

      <div *ngpComboboxPortal ngpComboboxDropdown>
        @for (option of options; track option) {
          <div [ngpComboboxOptionValue]="option" ngpComboboxOption>
            {{ option }}
          </div>
        }
      </div>
    </div>
  `,
  styles: `
    [ngpCombobox] {
      display: inline-block;
      width: 300px;
    }

    [ngpCombobox]:focus-within {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 2px;
      border-radius: 8px;
    }

    [ngpComboboxButton] {
      display: flex;
      justify-content: space-between;
      align-items: center;
      width: 100%;
      height: 36px;
      padding: 0 16px;
      border-radius: 8px;
      border: none;
      background-color: var(--ngp-background);
      box-shadow: var(--ngp-input-shadow);
      color: var(--ngp-text);
      font-family: inherit;
      font-size: 14px;
      cursor: pointer;
      box-sizing: border-box;
      transition: all 0.2s ease;
    }

    [ngpComboboxButton]:hover {
      background-color: var(--ngp-background-hover);
    }

    [ngpComboboxButton][aria-expanded='true'] {
      background-color: var(--ngp-background-active);
    }

    [ngpComboboxButton] ng-icon {
      transition: transform 0.2s ease;
      width: 16px;
      height: 16px;
    }

    [ngpComboboxButton][aria-expanded='true'] ng-icon {
      transform: rotate(180deg);
    }

    [ngpComboboxDropdown] {
      background-color: var(--ngp-background);
      border: 1px solid var(--ngp-border);
      padding: 0.25rem;
      border-radius: 0.75rem;
      outline: none;
      position: absolute;
      width: var(--ngp-combobox-width);
      box-shadow: var(--ngp-shadow-lg);
      box-sizing: border-box;
      margin-top: 4px;
      max-height: 240px;
      overflow-y: auto;
      z-index: 1001;
      transform-origin: var(--ngp-combobox-transform-origin);
    }

    [ngpComboboxDropdown][data-enter] {
      animation: dropdown-show 0.15s ease-out;
    }

    [ngpComboboxDropdown][data-exit] {
      animation: dropdown-hide 0.15s ease-in;
    }

    [ngpComboboxOption] {
      display: flex;
      align-items: center;
      gap: 0.5rem;
      padding: 0.375rem 0.75rem;
      cursor: pointer;
      border-radius: 0.5rem;
      width: 100%;
      height: 36px;
      font-size: 14px;
      color: var(--ngp-text-primary);
      box-sizing: border-box;
    }

    [ngpComboboxOption][data-hover] {
      background-color: var(--ngp-background-hover);
    }

    [ngpComboboxOption][data-press] {
      background-color: var(--ngp-background-active);
    }

    [ngpComboboxOption][data-active] {
      background-color: var(--ngp-background-active);
    }

    [ngpComboboxOption][data-selected] {
      background-color: var(--ngp-background-blue);
      color: var(--ngp-text-emphasis);
    }

    @keyframes dropdown-show {
      0% {
        opacity: 0;
        transform: translateY(-10px) scale(0.9);
      }
      100% {
        opacity: 1;
        transform: translateY(0) scale(1);
      }
    }

    @keyframes dropdown-hide {
      0% {
        opacity: 1;
        transform: translateY(0) scale(1);
      }
      100% {
        opacity: 0;
        transform: translateY(-10px) scale(0.9);
      }
    }
  `,
})
export default class ComboboxButtonExample {
  /** The options for the combobox. */
  readonly options: string[] = [
    'Marty McFly',
    'Doc Brown',
    'Biff Tannen',
    'George McFly',
    'Jennifer Parker',
    'Emmett Brown',
    'Einstein',
    'Clara Clayton',
    'Needles',
    'Goldie Wilson',
    'Marvin Berry',
    'Lorraine Baines',
    'Strickland',
  ];

  /** The selected value. */
  readonly value = signal<string | undefined>(undefined);
}

```

### Multiple Selection with chips

## Example

```typescript
import { Component, computed, ElementRef, signal, viewChild } from '@angular/core';
import { NgIcon, provideIcons } from '@ng-icons/core';
import { heroChevronDown, heroXMark } from '@ng-icons/heroicons/outline';
import { heroCheckSolid } from '@ng-icons/heroicons/solid';
import {
  NgpCombobox,
  NgpComboboxButton,
  NgpComboboxDropdown,
  NgpComboboxInput,
  NgpComboboxOption,
  NgpComboboxPortal,
} from 'ng-primitives/combobox';

@Component({
  selector: 'app-combobox-multiple-example',
  imports: [
    NgpCombobox,
    NgpComboboxDropdown,
    NgpComboboxOption,
    NgpComboboxInput,
    NgpComboboxPortal,
    NgpComboboxButton,
    NgIcon,
  ],
  providers: [provideIcons({ heroChevronDown, heroXMark, heroCheckSolid })],
  template: `
    <!-- Combobox multiple with chips -->
    <div
      [(ngpComboboxValue)]="value"
      (ngpComboboxValueChange)="filter.set('')"
      (ngpComboboxOpenChange)="resetOnClose($event)"
      ngpComboboxMultiple
      ngpCombobox
    >
      <div class="input-container" [class.py-1]="value().length > 0">
        @if (value().length > 0) {
          <div class="chips-container">
            @for (selectedOption of value(); track selectedOption; let i = $index) {
              <div class="chip" #chipElement [class.chip-focused]="focusedChipIndex() === i">
                <span class="chip-text">{{ selectedOption }}</span>
                <button
                  class="chip-remove"
                  [attr.aria-label]="'Remove ' + selectedOption"
                  (click)="removeOption(selectedOption)"
                  type="button"
                >
                  <ng-icon name="heroXMark" />
                </button>
              </div>
            }
          </div>
        }
        <input
          #inputElement
          [class.chips]="value().length > 0"
          [value]="filter()"
          (input)="onFilterChange($event)"
          (keydown)="onInputKeyDown($event)"
          placeholder="Select an option"
          ngpComboboxInput
        />
      </div>
      <button ngpComboboxButton aria-label="Toggle dropdown">
        <ng-icon name="heroChevronDown" />
      </button>

      <div *ngpComboboxPortal ngpComboboxDropdown>
        @for (option of filteredOptions(); track option) {
          <div [ngpComboboxOptionValue]="option" ngpComboboxOption>
            {{ option }}
            @if (isSelected(option)) {
              <ng-icon name="heroCheckSolid" />
            }
          </div>
        } @empty {
          <div class="empty-message">No options found</div>
        }
      </div>
    </div>
  `,
  styles: `
    [ngpCombobox] {
      display: flex;
      justify-content: space-between;
      align-items: center;
      width: 300px;
      min-height: 36px;
      border-radius: 8px;
      border: none;
      background-color: var(--ngp-background);
      box-shadow: var(--ngp-input-shadow);
      box-sizing: border-box;
    }

    [ngpCombobox][data-focus] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 2px;
    }

    .input-container {
      display: flex;
      flex-wrap: wrap;
      align-items: center;
      width: 100%;
    }

    [ngpComboboxInput] {
      padding: 0 16px;
      border: none;
      background-color: transparent;
      color: var(--ngp-text);
      font-family: inherit;
      font-size: 14px;
      outline: none;
      height: 100%;
      width: inherit;
    }

    [ngpComboboxInput].chips {
      padding-left: 16px;
      padding-block: 8px;
    }

    [ngpComboboxInput]::placeholder {
      color: var(--ngp-text-secondary);
    }

    [ngpComboboxButton] {
      display: inline-flex;
      justify-content: center;
      align-items: center;
      height: 100%;
      width: 36px;
      background-color: transparent;
      border: none;
      color: var(--ngp-text);
      cursor: pointer;
      box-sizing: border-box;
    }

    [ngpComboboxDropdown] {
      background-color: var(--ngp-background);
      border: 1px solid var(--ngp-border);
      padding: 0.25rem;
      border-radius: 0.75rem;
      outline: none;
      position: absolute;
      animation: popover-show 0.1s ease-out;
      width: var(--ngp-combobox-width);
      box-shadow: var(--ngp-shadow-lg);
      box-sizing: border-box;
      margin-top: 4px;
      max-height: 240px;
      overflow-y: auto;
      z-index: 1001;
    }

    [ngpComboboxDropdown][data-enter] {
      animation: combobox-show 0.1s ease-out;
    }

    [ngpComboboxDropdown][data-exit] {
      animation: combobox-hide 0.1s ease-out;
    }

    [ngpComboboxOption] {
      display: flex;
      align-items: center;
      gap: 0.5rem;
      padding: 0.375rem 0.75rem;
      cursor: pointer;
      border-radius: 0.5rem;
      width: 100%;
      height: 36px;
      font-size: 14px;
      color: var(--ngp-text-primary);
      box-sizing: border-box;
    }

    [ngpComboboxOption][data-hover] {
      background-color: var(--ngp-background-hover);
    }

    [ngpComboboxOption][data-press] {
      background-color: var(--ngp-background-active);
    }

    [ngpComboboxOption][data-active] {
      background-color: var(--ngp-background-active);
    }

    [ngpComboboxOption] ng-icon {
      font-weight: bold;
      margin-left: auto;
    }

    .chips-container {
      display: flex;
      flex-wrap: wrap;
      gap: 2px;
      padding-left: 8px;
    }

    .chip {
      display: inline-flex;
      align-items: center;
      background-color: var(--ngp-background-active);
      border: 1px solid var(--ngp-border-secondary);
      border-radius: 16px;
      padding: 2px 6px 2px 8px;
      font-size: 12px;
      font-weight: 500;
      color: var(--ngp-text-primary);
      max-width: 200px;
      line-height: 20px;
      transition: all 0.15s ease;
    }

    .chip:hover {
      background-color: var(--ngp-background-secondary);
    }

    .chip-focused .chip-remove {
      color: white;
      background-color: var(--ngp-text-red);
      opacity: 1;
    }

    .chip-text {
      white-space: nowrap;
      overflow: hidden;
      text-overflow: ellipsis;
      margin-right: 4px;
      user-select: none;
    }

    .chip-remove {
      display: flex;
      align-items: center;
      justify-content: center;
      width: 16px;
      height: 16px;
      border: none;
      background: transparent;
      color: var(--ngp-text-secondary);
      cursor: pointer;
      border-radius: 50%;
      font-size: 14px;
      line-height: 1;
      padding: 0;
      transition: all 0.15s ease;
      opacity: 0.6;
    }

    .chip-remove:hover {
      opacity: 1;
      background-color: var(--ngp-text-red);
      color: white;
    }

    .chip-remove:focus {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 1px;
    }

    .empty-message {
      display: flex;
      justify-content: center;
      align-items: center;
      padding: 0.5rem;
      color: var(--ngp-text-secondary);
      font-size: 14px;
      font-weight: 500;
      text-align: center;
    }

    @keyframes combobox-show {
      0% {
        opacity: 0;
        transform: translateY(-10px) scale(0.9);
      }
      100% {
        opacity: 1;
        transform: translateY(0) scale(1);
      }
    }

    @keyframes combobox-hide {
      0% {
        opacity: 1;
        transform: translateY(0) scale(1);
      }
      100% {
        opacity: 0;
        transform: translateY(-10px) scale(0.9);
      }
    }
  `,
})
export default class ComboboxMultipleExample {
  readonly inputElement = viewChild.required<ElementRef<HTMLInputElement>>('inputElement');

  /** The options for the combobox. */
  readonly options: string[] = [
    'Marty McFly',
    'Doc Brown',
    'Biff Tannen',
    'George McFly',
    'Jennifer Parker',
    'Emmett Brown',
    'Einstein',
    'Clara Clayton',
    'Needles',
    'Goldie Wilson',
    'Marvin Berry',
    'Lorraine Baines',
    'Strickland',
  ];

  /** The selected values for multiple selection. */
  readonly value = signal<string[]>([]);

  /** The filter value. */
  readonly filter = signal<string>('');

  /** The index of the currently focused chip (-1 means no chip is focused). */
  readonly focusedChipIndex = signal<number>(-1);

  /** Get the filtered options. */
  protected readonly filteredOptions = computed(() =>
    this.options.filter(option => option.toLowerCase().includes(this.filter().toLowerCase())),
  );

  protected onFilterChange(event: Event): void {
    const input = event.target as HTMLInputElement;
    this.filter.set(input.value);
    // Reset focused chip when user starts typing
    this.focusedChipIndex.set(-1);
  }

  protected onInputKeyDown(event: KeyboardEvent): void {
    const input = event.target as HTMLInputElement;
    const currentValue = this.value();

    if (event.key === 'Backspace') {
      if (input.value === '' && currentValue.length > 0) {
        event.preventDefault();
        const currentFocusedIndex = this.focusedChipIndex();

        if (currentFocusedIndex === -1) {
          this.focusedChipIndex.set(currentValue.length - 1);
        } else {
          const optionToRemove = currentValue[currentFocusedIndex];
          this.removeOption(optionToRemove);
          // reset focused chip index and restore focus to input
          this.focusedChipIndex.set(-1);
          this.inputElement().nativeElement.focus();
        }
      } else {
        this.focusedChipIndex.set(-1);
      }
      return;
    }
    this.focusedChipIndex.set(-1);
  }

  protected resetOnClose(open: boolean): void {
    // if the dropdown is closed, reset the filter value and focused chip
    if (open) {
      return;
    }
    this.filter.set('');
    this.focusedChipIndex.set(-1);
  }

  protected isSelected(option: string): boolean {
    return this.value().includes(option);
  }

  protected removeOption(option: string): void {
    const currentValue = this.value();
    const updatedValue = currentValue.filter(item => item !== option);
    this.value.set(updatedValue);

    // Reset focused chip index after removal
    this.focusedChipIndex.set(-1);
  }
}

```

### Select All Functionality

The combobox supports a "Select All" option for multiple selection mode, allowing users to select or deselect all options at once.

## Example

```typescript
import { Component, computed, signal } from '@angular/core';
import { NgIcon, provideIcons } from '@ng-icons/core';
import { heroChevronDown } from '@ng-icons/heroicons/outline';
import { heroCheckSolid, heroMinusSolid } from '@ng-icons/heroicons/solid';
import {
  NgpCombobox,
  NgpComboboxButton,
  NgpComboboxDropdown,
  NgpComboboxInput,
  NgpComboboxOption,
  NgpComboboxPortal,
} from 'ng-primitives/combobox';

@Component({
  selector: 'app-combobox-select-all',
  imports: [
    NgpCombobox,
    NgpComboboxDropdown,
    NgpComboboxOption,
    NgpComboboxInput,
    NgpComboboxPortal,
    NgpComboboxButton,
    NgIcon,
  ],
  providers: [provideIcons({ heroChevronDown, heroCheckSolid, heroMinusSolid })],
  template: `
    <div
      [(ngpComboboxValue)]="value"
      (ngpComboboxOpenChange)="resetOnClose($event)"
      ngpComboboxMultiple
      ngpCombobox
    >
      <input
        [value]="displayValue()"
        (input)="onFilterChange($event)"
        placeholder="Select options..."
        ngpComboboxInput
      />

      <button ngpComboboxButton aria-label="Toggle dropdown">
        <ng-icon name="heroChevronDown" />
      </button>

      <div *ngpComboboxPortal ngpComboboxDropdown>
        <!-- Select All Option -->
        <div class="select-all-option" ngpComboboxOptionValue="all" ngpComboboxOption>
          <span>Select All</span>
          @if (selectAllState() === 'all') {
            <ng-icon name="heroCheckSolid" />
          } @else if (selectAllState() === 'some') {
            <ng-icon name="heroMinusSolid" />
          }
        </div>

        <div class="divider"></div>

        <!-- Regular Options -->
        @for (option of filteredOptions(); track option) {
          <div [ngpComboboxOptionValue]="option" ngpComboboxOption>
            {{ option }}
            @if (isSelected(option)) {
              <ng-icon name="heroCheckSolid" />
            }
          </div>
        } @empty {
          <div class="empty-message">No options found</div>
        }
      </div>
    </div>
  `,
  styles: `
    [ngpCombobox] {
      display: flex;
      justify-content: space-between;
      align-items: center;
      height: 36px;
      width: 300px;
      border-radius: 8px;
      border: none;
      background-color: var(--ngp-background);
      box-shadow: var(--ngp-input-shadow);
      box-sizing: border-box;
    }

    [ngpCombobox][data-focus] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 2px;
    }

    [ngpComboboxInput] {
      flex: 1;
      padding: 0 16px;
      border: none;
      background-color: transparent;
      color: var(--ngp-text);
      font-family: inherit;
      font-size: 14px;
      padding: 0 16px;
      outline: none;
      height: 100%;
    }

    [ngpComboboxButton] {
      display: inline-flex;
      justify-content: center;
      align-items: center;
      height: 100%;
      width: 36px;
      background-color: transparent;
      border: none;
      color: var(--ngp-text);
      cursor: pointer;
      box-sizing: border-box;
    }

    [ngpComboboxDropdown] {
      background-color: var(--ngp-background);
      border: 1px solid var(--ngp-border);
      padding: 0.25rem;
      border-radius: 0.75rem;
      outline: none;
      position: absolute;
      animation: popover-show 0.1s ease-out;
      width: var(--ngp-combobox-width);
      box-shadow: var(--ngp-shadow-lg);
      box-sizing: border-box;
      margin-top: 4px;
      max-height: 240px;
      overflow-y: auto;
      z-index: 1001;
    }

    [ngpComboboxDropdown][data-enter] {
      animation: combobox-show 0.1s ease-out;
    }

    [ngpComboboxDropdown][data-exit] {
      animation: combobox-hide 0.1s ease-out;
    }

    [ngpComboboxOption] {
      display: flex;
      align-items: center;
      justify-content: space-between;
      gap: 0.5rem;
      padding: 0.375rem 0.75rem;
      cursor: pointer;
      border-radius: 0.5rem;
      width: 100%;
      height: 36px;
      font-size: 14px;
      color: var(--ngp-text-primary);
      box-sizing: border-box;
    }

    [ngpComboboxOption][data-hover] {
      background-color: var(--ngp-background-hover);
    }

    [ngpComboboxOption][data-press] {
      background-color: var(--ngp-background-active);
    }

    [ngpComboboxOption][data-active] {
      background-color: var(--ngp-background-active);
    }

    [ngpComboboxOption][data-selected] {
      background-color: var(--ngp-background-active);
    }

    .select-all-option {
      font-weight: 600;
    }

    .divider {
      height: 1px;
      background-color: var(--ngp-border);
      margin: 0.25rem 0;
    }

    .empty-message {
      display: flex;
      justify-content: center;
      align-items: center;
      padding: 0.5rem;
      color: var(--ngp-text-secondary);
      font-size: 14px;
      font-weight: 500;
      text-align: center;
    }

    ng-icon {
      width: 16px;
      height: 16px;
      color: var(--ngp-primary);
    }

    @keyframes combobox-show {
      0% {
        opacity: 0;
        transform: translateY(-10px) scale(0.9);
      }
      100% {
        opacity: 1;
        transform: translateY(0) scale(1);
      }
    }

    @keyframes combobox-hide {
      0% {
        opacity: 1;
        transform: translateY(0) scale(1);
      }
      100% {
        opacity: 0;
        transform: translateY(-10px) scale(0.9);
      }
    }
  `,
})
export default class ComboboxSelectAllExample {
  /** The options for the combobox */
  readonly options: string[] = [
    'Marty McFly',
    'Doc Brown',
    'Biff Tannen',
    'George McFly',
    'Jennifer Parker',
    'Emmett Brown',
    'Einstein',
    'Clara Clayton',
    'Needles',
    'Goldie Wilson',
    'Marvin Berry',
    'Lorraine Baines',
    'Strickland',
  ];

  /** The selected values */
  readonly value = signal<string[]>([]);

  /** The filter value */
  readonly filter = signal<string>('');

  /** Get the filtered options */
  protected readonly filteredOptions = computed(() =>
    this.filter()
      ? this.options.filter(option => option.toLowerCase().includes(this.filter().toLowerCase()))
      : this.options,
  );

  /** Get the display value for the input */
  protected readonly displayValue = computed(() => {
    const selected = this.value();
    if (selected.length === 0) {
      return '';
    }
    if (selected.length === 1) {
      return selected[0];
    }
    return `${selected.length} selected`;
  });

  /** Get the select all state */
  protected readonly selectAllState = computed(() => {
    const selected = this.value();
    const filtered = this.filteredOptions();

    if (filtered.length === 0) {
      return 'none';
    }

    const allSelected = filtered.every(option => selected.includes(option));
    const someSelected = filtered.some(option => selected.includes(option));

    if (allSelected) {
      return 'all';
    }
    if (someSelected) {
      return 'some';
    }
    return 'none';
  });

  /** Check if an option is selected */
  protected isSelected(option: string): boolean {
    return this.value().includes(option);
  }

  /** Handle filter change */
  protected onFilterChange(event: Event): void {
    const input = event.target as HTMLInputElement;
    this.filter.set(input.value);
  }

  /** Reset filter when dropdown closes */
  protected resetOnClose(open: boolean): void {
    if (!open) {
      this.filter.set('');
    }
  }
}

```

#### Select All Features

- **Toggle All**: Click to select all options if not all are selected, or deselect all if all are selected
- **Visual State**: The "Select All" option shows as selected when all individual options are selected
- **Filtering Support**: When options are filtered, "Select All" only affects currently visible options
- **Keyboard Navigation**: Full keyboard support with Arrow keys and Enter
- **Multiple Mode Only**: Automatically disabled in single selection mode

To implement Select All, use the special value `'all'` for your Select All option:

```html
<div ngpComboboxOptionValue="all" ngpComboboxOption>Select All</div>
```

### Virtualized Large Lists

When dealing with large datasets (thousands of items), you can use TanStack Virtual or other virtualization libraries to efficiently render only the visible options, improving performance:

## Example

```typescript
import { Component, computed, ElementRef, signal, viewChild } from '@angular/core';
import { NgIcon, provideIcons } from '@ng-icons/core';
import { heroChevronDown } from '@ng-icons/heroicons/outline';
import { injectVirtualizer } from '@tanstack/angular-virtual';
import {
  NgpCombobox,
  NgpComboboxButton,
  NgpComboboxDropdown,
  NgpComboboxInput,
  NgpComboboxOption,
  NgpComboboxPortal,
} from 'ng-primitives/combobox';

@Component({
  selector: 'app-combobox-virtual',
  imports: [
    NgpCombobox,
    NgpComboboxDropdown,
    NgpComboboxOption,
    NgpComboboxInput,
    NgpComboboxPortal,
    NgpComboboxButton,
    NgIcon,
  ],
  providers: [provideIcons({ heroChevronDown })],
  template: `
    <div
      [(ngpComboboxValue)]="value"
      [ngpComboboxScrollToOption]="scrollToOption"
      [ngpComboboxOptions]="filteredOptions()"
      (ngpComboboxValueChange)="filter.set($event)"
      (ngpComboboxOpenChange)="resetOnClose($event)"
      ngpCombobox
    >
      <input
        [value]="filter()"
        (input)="onFilterChange($event)"
        placeholder="Select from 10,000 options"
        ngpComboboxInput
      />

      <button ngpComboboxButton aria-label="Toggle dropdown">
        <ng-icon name="heroChevronDown" />
      </button>

      <div *ngpComboboxPortal ngpComboboxDropdown>
        @if (filteredOptions().length > 0) {
          <div class="virtual-container" #scrollContainer>
            <div
              class="virtual-list"
              [style.height.px]="virtualizer.getTotalSize()"
              [style.position]="'relative'"
            >
              @for (virtualRow of virtualizer.getVirtualItems(); track virtualRow.index) {
                <div
                  class="virtual-item"
                  [ngpComboboxOptionValue]="filteredOptions()[virtualRow.index]"
                  [style.position]="'absolute'"
                  [style.top.px]="virtualRow.start"
                  [style.left]="'0'"
                  [style.width]="'100%'"
                  [style.height.px]="virtualRow.size"
                  [ngpComboboxOptionIndex]="virtualRow.index"
                  ngpComboboxOption
                >
                  {{ filteredOptions()[virtualRow.index] }}
                </div>
              }
            </div>
          </div>
        } @else {
          <div class="empty-message">No options found</div>
        }

        <div class="results-info">
          Showing {{ filteredOptions().length }} of {{ options.length }} results
        </div>
      </div>
    </div>
  `,
  styles: `
    [ngpCombobox] {
      display: flex;
      justify-content: space-between;
      align-items: center;
      height: 36px;
      width: 300px;
      border-radius: 8px;
      border: none;
      background-color: var(--ngp-background);
      box-shadow: var(--ngp-input-shadow);
      box-sizing: border-box;
    }

    [ngpCombobox][data-focus] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 2px;
    }

    [ngpComboboxInput] {
      flex: 1;
      padding: 0 16px;
      border: none;
      background-color: transparent;
      color: var(--ngp-text);
      font-family: inherit;
      font-size: 14px;
      outline: none;
      height: 100%;
    }

    [ngpComboboxButton] {
      display: inline-flex;
      justify-content: center;
      align-items: center;
      height: 100%;
      width: 36px;
      background-color: transparent;
      border: none;
      color: var(--ngp-text);
      cursor: pointer;
      box-sizing: border-box;
    }

    [ngpComboboxDropdown] {
      background-color: var(--ngp-background);
      border: 1px solid var(--ngp-border);
      padding: 0;
      border-radius: 0.75rem;
      outline: none;
      position: absolute;
      animation: popover-show 0.1s ease-out;
      width: var(--ngp-combobox-width);
      box-shadow: var(--ngp-shadow-lg);
      box-sizing: border-box;
      margin-top: 4px;
      max-height: 300px;
      overflow: hidden;
      z-index: 1001;
      display: flex;
      flex-direction: column;
    }

    [ngpComboboxDropdown][data-enter] {
      animation: combobox-show 0.1s ease-out;
    }

    [ngpComboboxDropdown][data-exit] {
      animation: combobox-hide 0.1s ease-out;
    }

    .virtual-container {
      flex: 1;
      min-height: 0;
      overflow: auto;
      padding: 0.25rem;
      position: relative;
      height: 250px;
    }

    .virtual-item {
      display: flex;
      align-items: center;
      gap: 0.5rem;
      padding: 0.375rem 0.75rem;
      cursor: pointer;
      border-radius: 0.5rem;
      width: 100%;
      height: 36px;
      font-size: 14px;
      color: var(--ngp-text-primary);
      box-sizing: border-box;
    }

    .virtual-item[data-hover] {
      background-color: var(--ngp-background-hover);
    }

    .virtual-item[data-press] {
      background-color: var(--ngp-background-active);
    }

    .virtual-item[data-active] {
      background-color: var(--ngp-background-active);
    }

    .empty-message {
      display: flex;
      justify-content: center;
      align-items: center;
      padding: 1rem;
      color: var(--ngp-text-secondary);
      font-size: 14px;
      font-weight: 500;
      text-align: center;
    }

    .results-info {
      padding: 0.5rem 0.75rem;
      border-top: 1px solid var(--ngp-border);
      font-size: 12px;
      color: var(--ngp-text-secondary);
      background-color: var(--ngp-background-secondary);
      border-radius: 0 0 0.75rem 0.75rem;
    }

    @keyframes combobox-show {
      0% {
        opacity: 0;
        transform: translateY(-10px) scale(0.9);
      }
      100% {
        opacity: 1;
        transform: translateY(0) scale(1);
      }
    }

    @keyframes combobox-hide {
      0% {
        opacity: 1;
        transform: translateY(0) scale(1);
      }
      100% {
        opacity: 0;
        transform: translateY(-10px) scale(0.9);
      }
    }
  `,
})
export default class ComboboxVirtualExample {
  /** The options for the combobox - 10,000 generated names. */
  readonly options: string[] = generateLargeDataset(10000);

  /** The selected value. */
  readonly value = signal<string | undefined>(undefined);

  /** The filter value. */
  readonly filter = signal<string>('');

  /** Get the filtered options. */
  protected readonly filteredOptions = computed(() =>
    this.options.filter(option => option.toLowerCase().includes(this.filter().toLowerCase())),
  );

  /** The scroll container element reference. */
  readonly scrollContainer = viewChild<ElementRef<HTMLDivElement>>('scrollContainer');

  /** The virtualizer instance. */
  readonly virtualizer = injectVirtualizer(() => ({
    count: this.filteredOptions().length,
    scrollElement: this.scrollContainer(),
    estimateSize: () => 36,
    overscan: 5,
  }));

  /** A custom scroll to option function. */
  protected readonly scrollToOption = (index: number) => {
    this.virtualizer.scrollToIndex(index, { behavior: 'auto', align: 'auto' });
  };

  protected onFilterChange(event: Event): void {
    const input = event.target as HTMLInputElement;
    this.filter.set(input.value);
  }

  protected resetOnClose(open: boolean): void {
    // if the dropdown is closed, reset the filter value
    if (open) {
      return;
    }

    // if the filter value is empty, set the value to undefined
    if (this.filter() === '') {
      this.value.set(undefined);
    } else {
      // otherwise set the filter value to the selected value
      this.filter.set(this.value() ?? '');
    }
  }
}

// Generate a large dataset to showcase virtualization
function generateLargeDataset(count: number): string[] {
  const firstNames = [
    'James',
    'Mary',
    'John',
    'Patricia',
    'Robert',
    'Jennifer',
    'Michael',
    'Linda',
    'William',
    'Elizabeth',
    'David',
    'Barbara',
    'Richard',
    'Susan',
    'Joseph',
    'Jessica',
    'Thomas',
    'Sarah',
    'Christopher',
    'Karen',
    'Charles',
    'Nancy',
    'Daniel',
    'Lisa',
    'Matthew',
    'Betty',
    'Anthony',
    'Helen',
    'Mark',
    'Sandra',
    'Donald',
    'Donna',
    'Steven',
    'Carol',
    'Paul',
    'Ruth',
    'Andrew',
    'Sharon',
    'Joshua',
    'Michelle',
    'Kenneth',
    'Laura',
    'Kevin',
    'Emily',
    'Brian',
    'Kimberly',
    'George',
    'Deborah',
    'Edward',
    'Dorothy',
    'Ronald',
    'Amy',
    'Timothy',
    'Angela',
    'Jason',
    'Ashley',
    'Jeffrey',
    'Brenda',
    'Ryan',
    'Emma',
    'Jacob',
    'Olivia',
    'Gary',
    'Cynthia',
  ];

  const lastNames = [
    'Smith',
    'Johnson',
    'Williams',
    'Brown',
    'Jones',
    'Garcia',
    'Miller',
    'Davis',
    'Rodriguez',
    'Martinez',
    'Hernandez',
    'Lopez',
    'Gonzalez',
    'Wilson',
    'Anderson',
    'Thomas',
    'Taylor',
    'Moore',
    'Jackson',
    'Martin',
    'Lee',
    'Perez',
    'Thompson',
    'White',
    'Harris',
    'Sanchez',
    'Clark',
    'Ramirez',
    'Lewis',
    'Robinson',
    'Walker',
    'Young',
    'Allen',
    'King',
    'Wright',
    'Scott',
    'Torres',
    'Nguyen',
    'Hill',
    'Flores',
    'Green',
    'Adams',
    'Nelson',
    'Baker',
    'Hall',
    'Rivera',
    'Campbell',
    'Mitchell',
    'Carter',
    'Roberts',
    'Gomez',
    'Phillips',
    'Evans',
    'Turner',
    'Diaz',
    'Parker',
    'Cruz',
    'Edwards',
    'Collins',
    'Reyes',
    'Stewart',
    'Morris',
    'Morales',
    'Murphy',
  ];

  const options: string[] = [];
  for (let i = 0; i < count; i++) {
    const firstName = firstNames[i % firstNames.length];
    const lastName = lastNames[Math.floor(i / firstNames.length) % lastNames.length];
    const id = String(i + 1).padStart(4, '0');
    options.push(`${firstName} ${lastName} (#${id})`);
  }
  return options;
}

```

### Custom Option Behavior

Options without a value do not perform any selection by default. You can use this to implement custom behavior, such as clearing the selection. These options are still included in keyboard navigation.

## Example

```typescript
import { Component, computed, signal } from '@angular/core';
import { NgIcon, provideIcons } from '@ng-icons/core';
import { heroChevronDown } from '@ng-icons/heroicons/outline';
import {
  NgpCombobox,
  NgpComboboxButton,
  NgpComboboxDropdown,
  NgpComboboxInput,
  NgpComboboxOption,
  NgpComboboxPortal,
} from 'ng-primitives/combobox';

@Component({
  selector: 'app-combobox-custom-option',
  imports: [
    NgpCombobox,
    NgpComboboxDropdown,
    NgpComboboxOption,
    NgpComboboxInput,
    NgpComboboxPortal,
    NgpComboboxButton,
    NgIcon,
  ],
  providers: [provideIcons({ heroChevronDown })],
  template: `
    <div
      [(ngpComboboxValue)]="value"
      (ngpComboboxValueChange)="filter.set($event ?? '')"
      (ngpComboboxOpenChange)="resetOnClose($event)"
      ngpCombobox
    >
      <input
        [value]="filter()"
        (input)="onFilterChange($event)"
        placeholder="Select an option"
        ngpComboboxInput
      />

      <button ngpComboboxButton aria-label="Toggle dropdown">
        <ng-icon name="heroChevronDown" />
      </button>

      <div *ngpComboboxPortal ngpComboboxDropdown>
        <div class="clear-option" (ngpComboboxOptionActivated)="clear()" ngpComboboxOption>
          None
        </div>

        <div class="divider"></div>

        @for (option of filteredOptions(); track option) {
          <div [ngpComboboxOptionValue]="option" ngpComboboxOption>
            {{ option }}
          </div>
        } @empty {
          <div class="empty-message">No options found</div>
        }
      </div>
    </div>
  `,
  styles: `
    [ngpCombobox] {
      display: flex;
      justify-content: space-between;
      align-items: center;
      height: 36px;
      width: 300px;
      border-radius: 8px;
      border: none;
      background-color: var(--ngp-background);
      box-shadow: var(--ngp-input-shadow);
      box-sizing: border-box;
    }

    [ngpCombobox][data-focus] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 2px;
    }

    [ngpComboboxInput] {
      flex: 1;
      padding: 0 16px;
      border: none;
      background-color: transparent;
      color: var(--ngp-text);
      font-family: inherit;
      font-size: 14px;
      padding: 0 16px;
      outline: none;
      height: 100%;
    }

    [ngpComboboxButton] {
      display: inline-flex;
      justify-content: center;
      align-items: center;
      height: 100%;
      width: 36px;
      background-color: transparent;
      border: none;
      color: var(--ngp-text);
      cursor: pointer;
      box-sizing: border-box;
    }

    [ngpComboboxDropdown] {
      background-color: var(--ngp-background);
      border: 1px solid var(--ngp-border);
      padding: 0.25rem;
      border-radius: 0.75rem;
      outline: none;
      position: absolute;
      animation: popover-show 0.1s ease-out;
      width: var(--ngp-combobox-width);
      box-shadow: var(--ngp-shadow-lg);
      box-sizing: border-box;
      margin-top: 4px;
      max-height: 240px;
      overflow-y: auto;
      z-index: 1001;
    }

    [ngpComboboxDropdown][data-enter] {
      animation: combobox-show 0.1s ease-out;
    }

    [ngpComboboxDropdown][data-exit] {
      animation: combobox-hide 0.1s ease-out;
    }

    [ngpComboboxOption] {
      display: flex;
      align-items: center;
      gap: 0.5rem;
      padding: 0.375rem 0.75rem;
      cursor: pointer;
      border-radius: 0.5rem;
      width: 100%;
      height: 36px;
      font-size: 14px;
      color: var(--ngp-text-primary);
      box-sizing: border-box;
    }

    [ngpComboboxOption][data-hover] {
      background-color: var(--ngp-background-hover);
    }

    [ngpComboboxOption][data-press] {
      background-color: var(--ngp-background-active);
    }

    [ngpComboboxOption][data-active] {
      background-color: var(--ngp-background-active);
    }

    .clear-option {
      color: var(--ngp-text-secondary);
      font-style: italic;
    }

    .divider {
      height: 1px;
      background-color: var(--ngp-border);
      margin: 0.25rem 0;
    }

    .empty-message {
      display: flex;
      justify-content: center;
      align-items: center;
      padding: 0.5rem;
      color: var(--ngp-text-secondary);
      font-size: 14px;
      font-weight: 500;
      text-align: center;
    }

    @keyframes combobox-show {
      0% {
        opacity: 0;
        transform: translateY(-10px) scale(0.9);
      }
      100% {
        opacity: 1;
        transform: translateY(0) scale(1);
      }
    }

    @keyframes combobox-hide {
      0% {
        opacity: 1;
        transform: translateY(0) scale(1);
      }
      100% {
        opacity: 0;
        transform: translateY(-10px) scale(0.9);
      }
    }
  `,
})
export default class ComboboxCustomOptionExample {
  /** The options for the combobox. */
  readonly options: string[] = [
    'Marty McFly',
    'Doc Brown',
    'Biff Tannen',
    'George McFly',
    'Jennifer Parker',
    'Emmett Brown',
    'Einstein',
    'Clara Clayton',
    'Needles',
    'Goldie Wilson',
    'Marvin Berry',
    'Lorraine Baines',
    'Strickland',
  ];

  /** The selected value. */
  readonly value = signal<string | undefined>(undefined);

  /** The filter value. */
  readonly filter = signal<string>('');

  /** Get the filtered options. */
  protected readonly filteredOptions = computed(() =>
    this.options.filter(option => option.toLowerCase().includes(this.filter().toLowerCase())),
  );

  protected onFilterChange(event: Event): void {
    const input = event.target as HTMLInputElement;
    this.filter.set(input.value);
  }

  protected resetOnClose(open: boolean): void {
    // if the dropdown is closed, reset the filter value
    if (open) {
      return;
    }

    // if the filter value is empty, set the value to undefined
    if (this.filter() === '') {
      this.value.set(undefined);
    } else {
      // otherwise set the filter value to the selected value
      this.filter.set(this.value() ?? '');
    }
  }

  /** Clear the selection. */
  clear(): void {
    this.value.set(undefined);
    this.filter.set('');
  }
}

```

## Schematics

Generate a reusable combobox component using the Angular CLI.

```bash npm
ng g ng-primitives:primitive combobox
```

### Options

- `path`: The path at which to create the component file.
- `prefix`: The prefix to apply to the generated component selector.
- `componentSuffix`: The suffix to apply to the generated component class name.
- `fileSuffix`: The suffix to apply to the generated component file name. Defaults to `component`.
- `exampleStyles`: Whether to include example styles in the generated component file. Defaults to `true`.

## API Reference

The following directives are available to import from the `ng-primitives/combobox` package:

### NgpCombobox

The main container for the combobox.

## API Reference

### NgpCombobox



**Selector:** `[ngpCombobox]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpComboboxValue` | `any` | `-` | The value of the combobox. |
| `ngpComboboxMultiple` | `boolean` | `-` | Whether the combobox is multiple selection. |
| `ngpComboboxDisabled` | `boolean` | `-` | Whether the combobox is disabled. |
| `ngpComboboxAllowDeselect` | `boolean` | `-` | Whether the combobox allows deselection in single selection mode. |
| `ngpComboboxCompareWith` | `(a: any, b: any) => boolean` | `-` | The comparator function used to compare options. |
| `ngpComboboxDropdownPlacement` | `NgpComboboxPlacement` | `-` | The position of the dropdown. |
| `ngpComboboxDropdownContainer` | `string | HTMLElement | null` | `-` | The container for the dropdown. |
| `ngpComboboxScrollToOption` | `((index: number) => void) | undefined` | `-` | A function that will scroll the active option into view. This can be overridden
for cases such as virtual scrolling where we cannot scroll the option directly because
it may not be rendered. |
| `ngpComboboxOptions` | `any[] | undefined` | `-` | Provide all the option values to the combobox. This is useful for virtual scrolling scenarios
where not all options are rendered in the DOM. This is not an alternative to adding the options
in the DOM, it is only to provide the combobox with the full list of options. This list should match
the order of the options as they would appear in the DOM. |

#### Outputs

| Event | Type | Description |
|-------|------|-------------|
| `ngpComboboxValueChange` | `any` | Event emitted when the value changes. |
| `ngpComboboxOpenChange` | `boolean` | Emit when the dropdown open state changes. |

#### Export As

`ngpCombobox`



#### Data Attributes

The following data attributes are applied to the `ngpCombobox` directive:

| Attribute       | Description                                                    |
| --------------- | -------------------------------------------------------------- |
| `data-open`     | Applied when the combobox is open.                             |
| `data-disabled` | Applied when the combobox is disabled.                         |
| `data-multiple` | Applied when the combobox is in multiple mode.                 |
| `data-hover`    | Applied when the combobox is hovered.                          |
| `data-press`    | Applied when the combobox is pressed.                          |
| `data-focus`    | Applied when the combobox has focus within it.                 |
| `data-invalid`  | Applied when the combobox is invalid.                          |
| `data-valid`    | Applied when the combobox is valid.                            |
| `data-touched`  | Applied when the combobox has been touched.                    |
| `data-pristine` | Applied when the combobox is pristine (not modified).          |
| `data-dirty`    | Applied when the combobox has been modified.                   |
| `data-pending`  | Applied when the combobox is pending (e.g., async validation). |
| `data-disabled` | Applied when the combobox is disabled.                         |

#### Focus Management

When no `ngpComboboxInput` is present, the combobox element itself receives:

- `tabindex="0"` to make it focusable via keyboard navigation
- `tabindex="-1"` when disabled or when an input is present
- Full keyboard navigation support

### NgpComboboxButton

The button that toggles the combobox dropdown.

## API Reference

### NgpComboboxButton



**Selector:** `button[ngpComboboxButton]`

#### Export As

`ngpComboboxButton`



#### Data Attributes

The following data attributes are applied to the `ngpComboboxButton` directive:

| Attribute       | Description                                    |
| --------------- | ---------------------------------------------- |
| `data-open`     | Applied when the combobox is open.             |
| `data-disabled` | Applied when the combobox is disabled.         |
| `data-multiple` | Applied when the combobox is in multiple mode. |

### NgpComboboxDropdown

The dropdown that contains the combobox options.

## API Reference

### NgpComboboxDropdown



**Selector:** `[ngpComboboxDropdown]`

#### Export As

`ngpComboboxDropdown`



#### CSS Custom Properties

The following CSS custom properties are applied to the `ngpComboboxDropdown` directive:

| Property                          | Description                                      |
| --------------------------------- | ------------------------------------------------ |
| `--ngp-combobox-transform-origin` | The transform origin for the dropdown animation. |
| `--ngp-combobox-width`            | The width of the combobox dropdown.              |
| `--ngp-combobox-input-width`      | The width of the combobox input field.           |
| `--ngp-combobox-button-width`     | The width of the combobox button.                |

### NgpComboboxInput

The input field for the combobox.

## API Reference

### NgpComboboxInput



**Selector:** `input[ngpComboboxInput]`

#### Export As

`ngpComboboxInput`



#### Data Attributes

The following data attributes are applied to the `ngpComboboxInput` directive:

| Attribute       | Description                                                 |
| --------------- | ----------------------------------------------------------- |
| `data-open`     | Applied when the combobox is open.                          |
| `data-disabled` | Applied when the combobox is disabled.                      |
| `data-multiple` | Applied when the combobox is in multiple mode.              |
| `data-invalid`  | Applied when the input is invalid.                          |
| `data-valid`    | Applied when the input is valid.                            |
| `data-touched`  | Applied when the input has been touched.                    |
| `data-pristine` | Applied when the input is pristine (not modified).          |
| `data-dirty`    | Applied when the input has been modified.                   |
| `data-pending`  | Applied when the input is pending (e.g., async validation). |
| `data-disabled` | Applied when the input is disabled.                         |

### NgpComboboxOption

The individual options within the combobox dropdown.

## API Reference

### NgpComboboxOption



**Selector:** `[ngpComboboxOption]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpComboboxOptionValue` | `any` | `-` | - |
| `ngpComboboxOptionDisabled` | `boolean` | `-` | The disabled state of the option. |
| `ngpComboboxOptionIndex` | `number | undefined` | `-` | The index of the option in the combobox. This can be used to define the order of options
when virtual scrolling is used or when the order is not determined by DOM order. |

#### Outputs

| Event | Type | Description |
|-------|------|-------------|
| `ngpComboboxOptionActivated` | `void` | Event emitted when the option is activated via click or keyboard.
This is useful for options without values that need custom behavior. |

#### Export As

`ngpComboboxOption`



#### Data Attributes

The following data attributes are applied to the `ngpComboboxOption` directive:

| Attribute       | Description                          |
| --------------- | ------------------------------------ |
| `data-selected` | Applied when the option is selected. |
| `data-active`   | Applied when the option is active.   |
| `data-disabled` | Applied when the option is disabled. |

### NgpComboboxPortal

The portal for rendering the combobox dropdown in an overlay.

## API Reference

### NgpComboboxPortal



**Selector:** `[ngpComboboxPortal]`

#### Export As

`ngpComboboxPortal`



## Animations

The `ngpComboboxDropdown` primitive adds a CSS custom property `--ngp-combobox-transform-origin` to the element that can be used to animate the menu from the trigger element.

The `ngpComboboxDropdown` will also add the `data-enter` and `data-exit` attributes to the element when it is being added or removed from the DOM. This can be used to trigger animations.

```css
:host[data-enter] {
  animation: fade-in 0.2s ease-in-out;
}

:host[data-exit] {
  animation: fade-out 0.2s ease-in-out;
}
```

## Global Configuration

You can configure the default options for all comboboxes in your application by using the `provideComboboxConfig` function in a providers array.

```ts
import { provideComboboxConfig } from 'ng-primitives/combobox';

bootstrapApplication(AppComponent, {
  providers: [provideComboboxConfig({ placement: 'bottom', container: document.body })],
});
```

### NgpComboboxConfig

<prop-details name="placement" type="'top' | 'right' | 'bottom' | 'left'">
  Define the placement of the combobox dropdown.
</prop-details>

<prop-details name="container" type="HTMLElement" default="document.body">
  Define the container element for the combobox dropdown. This is useful for rendering the dropdown in a specific part of the DOM.
</prop-details>

## Accessibility

Adheres to the [WAI-ARIA](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) guidelines for comboboxes.

### Keyboard Interactions

The combobox supports comprehensive keyboard navigation whether or not an input field is present:

#### With Input Field

- <kbd>ArrowDown</kbd>: Open the dropdown and focus the first option. If the dropdown is already open, move focus to the next option.
- <kbd>ArrowUp</kbd>: Open the dropdown and focus the last option. If the dropdown is already open, move focus to the previous option.
- <kbd>Home</kbd>: Move focus to the first option (when dropdown is open).
- <kbd>End</kbd>: Move focus to the last option (when dropdown is open).
- <kbd>Enter</kbd>: Toggle the selection state of the focused option. In single selection mode, this will select the option and close the dropdown. In multiple selection mode, this will toggle the option without closing the dropdown.
- <kbd>Escape</kbd>: Close the dropdown without selecting an option.
- <kbd>Any character key</kbd>: Open the dropdown and filter options based on typed text.

#### Without Input Field

When no `ngpComboboxInput` is present, the combobox container becomes focusable and supports:

- <kbd>Tab</kbd>: Focus the combobox container.
- <kbd>ArrowDown</kbd>: Open the dropdown and focus the first option. If already open, move to the next option.
- <kbd>ArrowUp</kbd>: Open the dropdown and focus the last option. If already open, move to the previous option.
- <kbd>Home</kbd>: Move focus to the first option (when dropdown is open).
- <kbd>End</kbd>: Move focus to the last option (when dropdown is open).
- <kbd>Enter</kbd>: Select the focused option and close the dropdown.
- <kbd>Escape</kbd>: Close the dropdown without selecting an option.


---

### Date Picker

File: primitives/date-picker.md
URL: https://angularprimitives.com/primitives/date-picker

# Date Picker

A date picker is a component that allows users to select a date from a calendar and navigate through months and years.

## Example

```typescript
import { Component, computed, signal } from '@angular/core';
import { NgIcon, provideIcons } from '@ng-icons/core';
import { heroChevronLeftMini, heroChevronRightMini } from '@ng-icons/heroicons/mini';
import {
  NgpDatePicker,
  NgpDatePickerCell,
  NgpDatePickerCellRender,
  NgpDatePickerDateButton,
  NgpDatePickerGrid,
  NgpDatePickerLabel,
  NgpDatePickerNextMonth,
  NgpDatePickerPreviousMonth,
  NgpDatePickerRowRender,
} from 'ng-primitives/date-picker';

@Component({
  selector: 'app-date-picker',
  imports: [
    NgIcon,
    NgpDatePicker,
    NgpDatePickerLabel,
    NgpDatePickerNextMonth,
    NgpDatePickerPreviousMonth,
    NgpDatePickerGrid,
    NgpDatePickerCell,
    NgpDatePickerRowRender,
    NgpDatePickerCellRender,
    NgpDatePickerDateButton,
  ],
  providers: [provideIcons({ heroChevronRightMini, heroChevronLeftMini })],
  template: `
    <div [(ngpDatePickerDate)]="date" [(ngpDatePickerFocusedDate)]="focused" ngpDatePicker>
      <div class="date-picker-header">
        <button ngpDatePickerPreviousMonth aria-label="previous month">
          <ng-icon name="heroChevronLeftMini" />
        </button>
        <h2 ngpDatePickerLabel>{{ label() }}</h2>
        <button ngpDatePickerNextMonth aria-label="next month">
          <ng-icon name="heroChevronRightMini" />
        </button>
      </div>
      <table ngpDatePickerGrid>
        <thead>
          <tr>
            <th scope="col" abbr="Sunday">S</th>
            <th scope="col" abbr="Monday">M</th>
            <th scope="col" abbr="Tuesday">T</th>
            <th scope="col" abbr="Wednesday">W</th>
            <th scope="col" abbr="Thursday">T</th>
            <th scope="col" abbr="Friday">F</th>
            <th scope="col" abbr="Saturday">S</th>
          </tr>
        </thead>
        <tbody>
          <tr *ngpDatePickerRowRender>
            <td *ngpDatePickerCellRender="let date" ngpDatePickerCell>
              <button ngpDatePickerDateButton>{{ date.getDate() }}</button>
            </td>
          </tr>
        </tbody>
      </table>
    </div>
  `,
  styles: `
    [ngpDatePicker] {
      display: inline-block;
      background-color: var(--ngp-background);
      border-radius: 12px;
      padding: 16px;
      box-shadow: var(--ngp-shadow);
      border: 1px solid var(--ngp-border);
    }

    .date-picker-header {
      display: flex;
      align-items: center;
      justify-content: space-between;
      height: 36px;
      margin-bottom: 16px;
    }

    th {
      font-size: 14px;
      font-weight: 500;
      width: 40px;
      height: 40px;
      text-align: center;
      color: var(--ngp-text-secondary);
    }

    [ngpDatePickerLabel] {
      font-size: 14px;
      font-weight: 500;
      color: var(--ngp-text-primary);
    }

    [ngpDatePickerPreviousMonth],
    [ngpDatePickerNextMonth] {
      all: unset;
      width: 32px;
      height: 32px;
      display: flex;
      align-items: center;
      justify-content: center;
      border-radius: 8px;
      font-size: 20px;
      border: 1px solid var(--ngp-border);
      cursor: pointer;
    }

    [ngpDatePickerPreviousMonth][data-hover],
    [ngpDatePickerNextMonth][data-hover] {
      background-color: var(--ngp-background-hover);
    }

    [ngpDatePickerPreviousMonth][data-focus-visible],
    [ngpDatePickerNextMonth][data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
    }

    [ngpDatePickerPreviousMonth][data-press],
    [ngpDatePickerNextMonth][data-press] {
      background-color: var(--ngp-background-active);
    }

    [ngpDatePickerPreviousMonth][data-disabled],
    [ngpDatePickerNextMonth][data-disabled] {
      cursor: not-allowed;
      color: var(--ngp-text-disabled);
    }

    [ngpDatePickerDateButton] {
      all: unset;
      width: 40px;
      height: 40px;
      display: flex;
      align-items: center;
      justify-content: center;
      border-radius: 8px;
      cursor: pointer;
    }

    [ngpDatePickerDateButton][data-today] {
      color: var(--ngp-text-blue);
    }

    [ngpDatePickerDateButton][data-hover] {
      background-color: var(--ngp-background-hover);
    }

    [ngpDatePickerDateButton][data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 2px;
    }

    [ngpDatePickerDateButton][data-press] {
      background-color: var(--ngp-background-active);
    }

    [ngpDatePickerDateButton][data-outside-month] {
      color: var(--ngp-text-disabled);
    }

    [ngpDatePickerDateButton][data-selected] {
      background-color: var(--ngp-background-inverse);
      color: var(--ngp-text-inverse);
    }

    [ngpDatePickerDateButton][data-selected][data-outside-month] {
      background-color: var(--ngp-background-disabled);
      color: var(--ngp-text-disabled);
    }

    [ngpDatePickerDateButton][data-disabled] {
      cursor: not-allowed;
      color: var(--ngp-text-disabled);
    }
  `,
})
export default class DatePickerExample {
  /**
   * The selected date.
   */
  readonly date = signal<Date>(new Date());

  /**
   * Store the current focused date.
   */
  readonly focused = signal<Date>(new Date());

  /**
   * Get the current focused date in string format.
   * @returns The focused date in "February 2024" format.
   */
  readonly label = computed(
    () =>
      `${this.focused().toLocaleString('default', { month: 'long' })} ${this.focused().getFullYear()}`,
  );
}

```

## Import

Import the DatePicker primitives from `ng-primitives/date-picker`.

```ts
import {
  NgpDatePicker,
  NgpDateRangePicker,
  NgpDatePickerLabel,
  NgpDatePickerNextMonth,
  NgpDatePickerPreviousMonth,
  NgpDatePickerGrid,
  NgpDatePickerCell,
  NgpDatePickerRowRender,
  NgpDatePickerCellRender,
  NgpDatePickerDateButton,
} from 'ng-primitives/date-picker';
```

## Usage

Assemble the date-picker directives in your template.

```html
<div ngpDatePicker>
  <div>
    <button ngpDatePickerPreviousMonth>...</button>
    <h2 ngpDatePickerLabel>...</h2>
    <button ngpDatePickerNextMonth>...</button>
  </div>
  <table ngpDatePickerGrid>
    <thead>
      <tr>
        <th scope="col" abbr="Sunday">S</th>
        ...
      </tr>
    </thead>
    <tbody>
      <tr *ngpDatePickerRowRender>
        <td *ngpDatePickerCellRender="let date" ngpDatePickerCell>
          <button ngpDatePickerDateButton>...</button>
        </td>
      </tr>
    </tbody>
  </table>
</div>
```

## Reusable Component

Create a reusable component that uses the date picker directives.

## Reusable Component

```typescript
import { Component, computed } from '@angular/core';
import { ControlValueAccessor } from '@angular/forms';
import { NgIcon, provideIcons } from '@ng-icons/core';
import { heroChevronLeftMini, heroChevronRightMini } from '@ng-icons/heroicons/mini';
import {
  injectDatePickerState,
  NgpDatePicker,
  NgpDatePickerCell,
  NgpDatePickerCellRender,
  NgpDatePickerDateButton,
  NgpDatePickerGrid,
  NgpDatePickerLabel,
  NgpDatePickerNextMonth,
  NgpDatePickerPreviousMonth,
  NgpDatePickerRowRender,
} from 'ng-primitives/date-picker';
import { ChangeFn, provideValueAccessor, TouchedFn } from 'ng-primitives/utils';

@Component({
  selector: 'app-date-picker',
  hostDirectives: [
    {
      directive: NgpDatePicker,
      inputs: [
        'ngpDatePickerDate: date',
        'ngpDatePickerMin: min',
        'ngpDatePickerMax: max',
        'ngpDatePickerDisabled: disabled',
      ],
      outputs: ['ngpDatePickerDateChange: dateChange'],
    },
  ],
  imports: [
    NgIcon,
    NgpDatePickerLabel,
    NgpDatePickerNextMonth,
    NgpDatePickerPreviousMonth,
    NgpDatePickerGrid,
    NgpDatePickerCell,
    NgpDatePickerRowRender,
    NgpDatePickerCellRender,
    NgpDatePickerDateButton,
  ],
  providers: [
    provideIcons({ heroChevronRightMini, heroChevronLeftMini }),
    provideValueAccessor(DatePicker),
  ],
  template: `
    <div class="date-picker-header">
      <button ngpDatePickerPreviousMonth aria-label="previous month">
        <ng-icon name="heroChevronLeftMini" />
      </button>
      <h2 ngpDatePickerLabel>{{ label() }}</h2>
      <button ngpDatePickerNextMonth aria-label="next month">
        <ng-icon name="heroChevronRightMini" />
      </button>
    </div>
    <table ngpDatePickerGrid>
      <thead>
        <tr>
          <th scope="col" abbr="Sunday">S</th>
          <th scope="col" abbr="Monday">M</th>
          <th scope="col" abbr="Tuesday">T</th>
          <th scope="col" abbr="Wednesday">W</th>
          <th scope="col" abbr="Thursday">T</th>
          <th scope="col" abbr="Friday">F</th>
          <th scope="col" abbr="Saturday">S</th>
        </tr>
      </thead>
      <tbody>
        <tr *ngpDatePickerRowRender>
          <td *ngpDatePickerCellRender="let date" ngpDatePickerCell>
            <button ngpDatePickerDateButton>
              {{ date.getDate() }}
            </button>
          </td>
        </tr>
      </tbody>
    </table>
  `,
  styles: `
    :host {
      display: inline-block;
      background-color: var(--ngp-background);
      border-radius: 12px;
      padding: 16px;
      box-shadow: var(--ngp-shadow);
      border: 1px solid var(--ngp-border);
    }

    .date-picker-header {
      display: flex;
      align-items: center;
      justify-content: space-between;
      height: 36px;
      margin-bottom: 16px;
    }

    th {
      font-size: 14px;
      font-weight: 500;
      width: 40px;
      height: 40px;
      text-align: center;
      color: var(--ngp-text-secondary);
    }

    [ngpDatePickerLabel] {
      font-size: 14px;
      font-weight: 500;
      color: var(--ngp-text-primary);
    }

    [ngpDatePickerPreviousMonth],
    [ngpDatePickerNextMonth] {
      all: unset;
      width: 32px;
      height: 32px;
      display: flex;
      align-items: center;
      justify-content: center;
      border-radius: 8px;
      font-size: 20px;
      border: 1px solid var(--ngp-border);
      cursor: pointer;
    }

    [ngpDatePickerPreviousMonth][data-hover],
    [ngpDatePickerNextMonth][data-hover] {
      background-color: var(--ngp-background-hover);
    }

    [ngpDatePickerPreviousMonth][data-focus-visible],
    [ngpDatePickerNextMonth][data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
    }

    [ngpDatePickerPreviousMonth][data-press],
    [ngpDatePickerNextMonth][data-press] {
      background-color: var(--ngp-background-active);
    }

    [ngpDatePickerPreviousMonth][data-disabled],
    [ngpDatePickerNextMonth][data-disabled] {
      cursor: not-allowed;
      color: var(--ngp-text-disabled);
    }

    [ngpDatePickerDateButton] {
      all: unset;
      width: 40px;
      height: 40px;
      display: flex;
      align-items: center;
      justify-content: center;
      border-radius: 8px;
      cursor: pointer;
    }

    [ngpDatePickerDateButton][data-today] {
      color: var(--ngp-text-blue);
    }

    [ngpDatePickerDateButton][data-hover] {
      background-color: var(--ngp-background-hover);
    }

    [ngpDatePickerDateButton][data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 2px;
    }

    [ngpDatePickerDateButton][data-press] {
      background-color: var(--ngp-background-active);
    }

    [ngpDatePickerDateButton][data-outside-month] {
      color: var(--ngp-text-disabled);
    }

    [ngpDatePickerDateButton][data-selected] {
      background-color: var(--ngp-background-inverse);
      color: var(--ngp-text-inverse);
    }

    [ngpDatePickerDateButton][data-selected][data-outside-month] {
      background-color: var(--ngp-background-disabled);
      color: var(--ngp-text-disabled);
    }

    [ngpDatePickerDateButton][data-disabled] {
      cursor: not-allowed;
      color: var(--ngp-text-disabled);
    }
  `,
  host: {
    '(focusout)': 'onTouched?.()',
  },
})
export class DatePicker implements ControlValueAccessor {
  /** Access the date picker host directive */
  private readonly state = injectDatePickerState<Date>();

  /**
   * Get the current focused date in string format.
   * @returns The focused date in "February 2024" format.
   */
  readonly label = computed(
    () =>
      `${this.state().focusedDate().toLocaleString('default', { month: 'long' })} ${this.state().focusedDate().getFullYear()}`,
  );

  /**
   * The onChange callback function for the date picker.
   */
  protected onChange?: ChangeFn<Date | undefined>;

  /**
   * The onTouched callback function for the date picker.
   */
  protected onTouched?: TouchedFn;

  constructor() {
    // Whenever the user interacts with the date picker, call the onChange function with the new value.
    this.state().dateChange.subscribe(date => this.onChange?.(date));
  }

  writeValue(date: Date): void {
    this.state().select(date);
  }

  registerOnChange(fn: ChangeFn<Date | undefined>): void {
    this.onChange = fn;
  }

  registerOnTouched(fn: TouchedFn): void {
    this.onTouched = fn;
  }

  setDisabledState(isDisabled: boolean): void {
    this.state().disabled.set(isDisabled);
  }
}

```

## Schematics

Generate a reusable date-picker component using the Angular CLI.

```bash npm
ng g ng-primitives:primitive date-picker
```

### Options

- `path`: The path at which to create the component file.
- `prefix`: The prefix to apply to the generated component selector.
- `componentSuffix`: The suffix to apply to the generated component class name.
- `fileSuffix`: The suffix to apply to the generated component file name. Defaults to `component`.
- `exampleStyles`: Whether to include example styles in the generated component file. Defaults to `true`.

## Examples

Here are some additional examples of how to use the Date Picker primitives.

### Date Range Picker

The date range picker allows users to select a range of dates by selecting the start and end dates.

## Example

```typescript
import { Component, computed, signal } from '@angular/core';
import { NgIcon, provideIcons } from '@ng-icons/core';
import { heroChevronLeftMini, heroChevronRightMini } from '@ng-icons/heroicons/mini';
import {
  NgpDatePickerCell,
  NgpDatePickerCellRender,
  NgpDatePickerDateButton,
  NgpDatePickerGrid,
  NgpDatePickerLabel,
  NgpDatePickerNextMonth,
  NgpDatePickerPreviousMonth,
  NgpDatePickerRowRender,
  NgpDateRangePicker,
} from 'ng-primitives/date-picker';

@Component({
  selector: 'app-date-range-picker',
  imports: [
    NgIcon,
    NgpDateRangePicker,
    NgpDatePickerLabel,
    NgpDatePickerNextMonth,
    NgpDatePickerPreviousMonth,
    NgpDatePickerGrid,
    NgpDatePickerCell,
    NgpDatePickerRowRender,
    NgpDatePickerCellRender,
    NgpDatePickerDateButton,
  ],
  providers: [provideIcons({ heroChevronRightMini, heroChevronLeftMini })],
  template: `
    <div
      [(ngpDateRangePickerStartDate)]="startDate"
      [(ngpDateRangePickerEndDate)]="endDate"
      [(ngpDateRangePickerFocusedDate)]="focused"
      ngpDateRangePicker
    >
      <div class="date-picker-header">
        <button ngpDatePickerPreviousMonth aria-label="previous month">
          <ng-icon name="heroChevronLeftMini" />
        </button>
        <h2 ngpDatePickerLabel>{{ label() }}</h2>
        <button ngpDatePickerNextMonth aria-label="next month">
          <ng-icon name="heroChevronRightMini" />
        </button>
      </div>
      <table ngpDatePickerGrid>
        <thead>
          <tr>
            <th scope="col" abbr="Sunday">S</th>
            <th scope="col" abbr="Monday">M</th>
            <th scope="col" abbr="Tuesday">T</th>
            <th scope="col" abbr="Wednesday">W</th>
            <th scope="col" abbr="Thursday">T</th>
            <th scope="col" abbr="Friday">F</th>
            <th scope="col" abbr="Saturday">S</th>
          </tr>
        </thead>
        <tbody>
          <tr *ngpDatePickerRowRender>
            <td *ngpDatePickerCellRender="let date" ngpDatePickerCell>
              <button ngpDatePickerDateButton>{{ date.getDate() }}</button>
            </td>
          </tr>
        </tbody>
      </table>
    </div>
  `,
  styles: `
    [ngpDateRangePicker] {
      display: inline-block;
      background-color: var(--ngp-background);
      border-radius: 12px;
      padding: 16px;
      box-shadow: var(--ngp-shadow);
      border: 1px solid var(--ngp-border);
    }

    .date-picker-header {
      display: flex;
      align-items: center;
      justify-content: space-between;
      height: 36px;
      margin-bottom: 16px;
    }

    th {
      font-size: 14px;
      font-weight: 500;
      width: 40px;
      height: 40px;
      text-align: center;
      color: var(--ngp-text-secondary);
    }

    [ngpDatePickerLabel] {
      font-size: 14px;
      font-weight: 500;
      color: var(--ngp-text-primary);
    }

    [ngpDatePickerPreviousMonth],
    [ngpDatePickerNextMonth] {
      all: unset;
      width: 32px;
      height: 32px;
      display: flex;
      align-items: center;
      justify-content: center;
      border-radius: 8px;
      font-size: 20px;
      border: 1px solid var(--ngp-border);
      cursor: pointer;
    }

    [ngpDatePickerPreviousMonth][data-hover],
    [ngpDatePickerNextMonth][data-hover] {
      background-color: var(--ngp-background-hover);
    }

    [ngpDatePickerPreviousMonth][data-focus-visible],
    [ngpDatePickerNextMonth][data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
    }

    [ngpDatePickerPreviousMonth][data-press],
    [ngpDatePickerNextMonth][data-press] {
      background-color: var(--ngp-background-active);
    }

    [ngpDatePickerPreviousMonth][data-disabled],
    [ngpDatePickerNextMonth][data-disabled] {
      cursor: not-allowed;
      color: var(--ngp-text-disabled);
    }

    [ngpDatePickerCell] {
      padding: 0;
    }

    [ngpDatePickerDateButton] {
      all: unset;
      width: 40px;
      height: 40px;
      display: flex;
      align-items: center;
      justify-content: center;
      border-radius: 8px;
      cursor: pointer;
    }

    [ngpDatePickerDateButton][data-today] {
      color: var(--ngp-text-blue);
    }

    [ngpDatePickerDateButton][data-hover] {
      background: var(--ngp-background-hover);
    }

    [ngpDatePickerDateButton][data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 2px;
    }

    [ngpDatePickerDateButton][data-press] {
      background: var(--ngp-background-active);
    }

    [ngpDatePickerDateButton][data-outside-month] {
      color: var(--ngp-text-disabled);
    }

    [ngpDatePickerDateButton][data-selected] {
      background: var(--ngp-background-inverse);
      color: var(--ngp-text-inverse);
    }

    [ngpDatePickerDateButton][data-selected]:not([data-range-end]) {
      border-radius: 8px 0 0 8px;
    }

    [ngpDatePickerDateButton][data-selected][data-range-end] {
      border-radius: 0 8px 8px 0;
    }

    [ngpDatePickerDateButton][data-selected][data-range-start][data-range-end] {
      border-radius: 8px;
    }

    [ngpDatePickerDateButton][data-range-between] {
      background: color-mix(in srgb, var(--ngp-background-inverse) 5%, transparent);
      border-radius: 0;
    }

    [ngpDatePickerDateButton][data-selected][data-outside-month] {
      background-color: var(--ngp-background-disabled);
      color: var(--ngp-text-disabled);
    }

    [ngpDatePickerDateButton][data-disabled] {
      cursor: not-allowed;
      color: var(--ngp-text-disabled);
    }
  `,
})
export default class DateRangePickerExample {
  /**
   * The start date of the range.
   */
  readonly startDate = signal<Date>(new Date(2025, 7, 10));

  /**
   * The end date of the range.
   */
  readonly endDate = signal<Date>(new Date(2025, 7, 14));

  /**
   * Store the current focused date.
   */
  readonly focused = signal<Date>(new Date(2025, 7, 10));

  /**
   * Get the current focused date in string format.
   * @returns The focused date in "February 2024" format.
   */
  readonly label = computed(
    () =>
      `${this.focused().toLocaleString('default', { month: 'long' })} ${this.focused().getFullYear()}`,
  );
}

```

## API Reference

By default, the date picker uses the native JavaScript `Date` object, however the date picker is designed to work with any date library. To use a date library, such as Luxon, you need to specify the appropriate date adapter. The date adapter is an abstraction layer that allows components to use date objects from any date library, ensuring compatibility and easy integration. To learn more about the date adapter, see the [Date Adapter](/utilities/date-adapter) documentation.

The following directives are available to import from the `ng-primitives/date-picker` package:

### NgpDatePicker

## API Reference

### NgpDatePicker

The outermost container for the date picker.

**Selector:** `[ngpDatePicker]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpDatePickerMin` | `T | undefined` | `-` | The minimum date that can be selected. |
| `ngpDatePickerMax` | `T | undefined` | `-` | The maximum date that can be selected. |
| `ngpDatePickerDisabled` | `boolean` | `-` | Determine if the date picker is disabled. |
| `ngpDatePickerDateDisabled` | `(date: T) => boolean` | `-` | A function that is called to determine if a specific date should be disabled. |
| `ngpDatePickerFirstDayOfWeek` | `NgpDatePickerFirstDayOfWeekNumber` | `7 (Sunday)` | Sets which day starts the week in the calendar.
Accepts 0-7 where 1=Monday, 2=Tuesday, 3=Wednesday, 4=Thursday, 5=Friday, 6=Saturday, 7=Sunday.
Defaults to NgpDatePickerConfig.firstDayOfWeek (default 7 if not overridden).
Note: Update calendar header column order when changing from Sunday start. |
| `ngpDatePickerDate` | `T | undefined` | `-` | The selected value. |
| `ngpDatePickerFocusedDate` | `T` | `-` | The focused value. |

#### Outputs

| Event | Type | Description |
|-------|------|-------------|
| `ngpDatePickerDateChange` | `T | undefined` | Emit when the date changes. |
| `ngpDatePickerFocusedDateChange` | `T` | Emit when the focused date changes. |

#### Export As

`ngpDatePicker`



#### Data Attributes

The following data attributes are available on the `ngpDatePicker` directive:

| Attribute       | Description                               |
| --------------- | ----------------------------------------- |
| `data-disabled` | Applied when the date picker is disabled. |

### NgpDateRangePicker

## API Reference

### NgpDateRangePicker



**Selector:** `[ngpDateRangePicker]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpDateRangePickerMin` | `T | undefined` | `-` | The minimum date that can be selected. |
| `ngpDateRangePickerMax` | `T | undefined` | `-` | The maximum date that can be selected. |
| `ngpDateRangePickerDisabled` | `boolean` | `-` | Determine if the date picker is disabled. |
| `ngpDateRangePickerDateDisabled` | `(date: T) => boolean` | `-` | A function that is called to determine if a specific date should be disabled. |
| `ngpDateRangePickerFirstDayOfWeek` | `NgpDatePickerFirstDayOfWeekNumber` | `7 (Sunday)` | Sets which day starts the week in the calendar.
Accepts 0-7 where 1=Monday, 2=Tuesday, 3=Wednesday, 4=Thursday, 5=Friday, 6=Saturday, 7=Sunday.
Defaults to NgpDatePickerConfig.firstDayOfWeek (default 7 if not overridden).
Note: Update calendar header column order when changing from Sunday start. |
| `ngpDateRangePickerStartDate` | `T | undefined` | `-` | The selected start date |
| `ngpDateRangePickerEndDate` | `T | undefined` | `-` | The selected end date |
| `ngpDateRangePickerFocusedDate` | `T` | `-` | The focused value. |

#### Outputs

| Event | Type | Description |
|-------|------|-------------|
| `ngpDateRangePickerStartDateChange` | `T | undefined` | Emit when the date changes. |
| `ngpDateRangePickerEndDateChange` | `T | undefined` | Emit when the end date changes. |
| `ngpDateRangePickerFocusedDateChange` | `T` | Emit when the focused date changes. |

#### Export As

`ngpDateRangePicker`



#### Data Attributes

The following data attributes are available on the `ngpDateRangePicker` directive:

| Attribute       | Description                                     |
| --------------- | ----------------------------------------------- |
| `data-disabled` | Applied when the date range picker is disabled. |

### NgpDatePickerLabel

## API Reference

### NgpDatePickerLabel

The label that displays the current month and year typically in the header of the date picker. This will be announced by screen readers when the date changes.

**Selector:** `[ngpDatePickerLabel]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `aria-live` | `string` | `-` | Define the aria live attribute. |

#### Export As

`ngpDatePickerLabel`



#### Data Attributes

The following data attributes are available on the `ngpDatePickerLabel` directive:

| Attribute       | Description                               |
| --------------- | ----------------------------------------- |
| `data-disabled` | Applied when the date picker is disabled. |

### NgpDatePickerPreviousMonth

## API Reference

### NgpDatePickerPreviousMonth

A button that navigates to the previous month.

**Selector:** `[ngpDatePickerPreviousMonth]`

#### Export As

`ngpDatePickerPreviousMonth`



#### Data Attributes

The following data attributes are available on the `ngpDatePickerPreviousMonth` directive:

| Attribute            | Description                          |
| -------------------- | ------------------------------------ |
| `data-hover`         | Applied when the button is hovered.  |
| `data-focus-visible` | Applied when the button is focused.  |
| `data-press`         | Applied when the button is pressed.  |
| `data-disabled`      | Applied when the button is disabled. |

### NgpDatePickerNextMonth

## API Reference

### NgpDatePickerNextMonth

A button that navigates to the next month.

**Selector:** `[ngpDatePickerNextMonth]`

#### Export As

`ngpDatePickerNextMonth`



#### Data Attributes

The following data attributes are available on the `ngpDatePickerNextMonth` directive:

| Attribute            | Description                          |
| -------------------- | ------------------------------------ |
| `data-hover`         | Applied when the button is hovered.  |
| `data-focus-visible` | Applied when the button is focused.  |
| `data-press`         | Applied when the button is pressed.  |
| `data-disabled`      | Applied when the button is disabled. |

### NgpDatePickerGrid

## API Reference

### NgpDatePickerGrid

The grid that contains the days of the month.

**Selector:** `[ngpDatePickerGrid]`

#### Export As

`ngpDatePickerGrid`



#### Data Attributes

The following data attributes are available on the `ngpDatePickerGrid` directive:

| Attribute       | Description                               |
| --------------- | ----------------------------------------- |
| `data-disabled` | Applied when the date picker is disabled. |

### NgpDatePickerRowRender

## API Reference

### NgpDatePickerRowRender

A structural directive that renders a row of weekdays in the date picker grid.

**Selector:** `[ngpDatePickerRowRender]`

#### Export As

`ngpDatePickerRowRender`



### NgpDatePickerCellRender

A structural directive that renders a cell in the date picker grid.

- Selector: `*ngpDatePickerCellRender`
- Exported As: `ngpDatePickerCellRender`

The following context fields are available on the `ngpDatePickerCellRender` directive:

<prop-details name="$implicit" type="T">
  The date value for the cell.
</prop-details>

### NgpDatePickerCell

## API Reference

### NgpDatePickerCell

A cell in the date picker grid.

**Selector:** `[ngpDatePickerCell]`

#### Export As

`ngpDatePickerCell`



#### Data Attributes

The following data attributes are available on the `ngpDatePickerCell` directive:

| Attribute       | Description                        |
| --------------- | ---------------------------------- |
| `data-disabled` | Applied when the cell is disabled. |
| `data-selected` | Applied when the cell is selected. |

### NgpDatePickerDateButton

## API Reference

### NgpDatePickerDateButton

A button that represents a date in the date picker grid.

**Selector:** `[ngpDatePickerDateButton]`

#### Export As

`ngpDatePickerDateButton`



#### Data Attributes

The following data attributes are available on the `ngpDatePickerDateButton` directive:

| Attribute            | Description                                                           |
| -------------------- | --------------------------------------------------------------------- |
| `data-selected`      | Applied when the button is selected.                                  |
| `data-outside-month` | Applied when the button is outside the current month.                 |
| `data-today`         | Applied when the button represents the current date.                  |
| `data-hover`         | Applied when the button is hovered.                                   |
| `data-focus-visible` | Applied when the button is focused.                                   |
| `data-press`         | Applied when the button is pressed.                                   |
| `data-disabled`      | Applied when the button is disabled.                                  |
| `data-range-start`   | Applied when the button is the start of a date range.                 |
| `data-range-end`     | Applied when the button is the end of a date range.                   |
| `data-range-between` | Applied when the button is between the start and end of a date range. |

## Accessibility

Adheres to the [WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/examples/datepicker-dialog/).

### Keyboard Interactions

- <kbd>Space</kbd> - Selects the focused date.
- <kbd>Enter</kbd> - Selects the focused date.
- <kbd>ArrowUp</kbd> - Moves focus to the same day of the previous week.
- <kbd>ArrowDown</kbd> - Moves focus to the same day of the next week.
- <kbd>ArrowLeft</kbd> - Moves focus to the previous day.
- <kbd>ArrowRight</kbd> - Moves focus to the next day.
- <kbd>Home</kbd> - Moves focus to the first day of the month.
- <kbd>End</kbd> - Moves focus to the last day of the month.
- <kbd>PageUp</kbd> - Moves focus to the same date in the previous month.
- <kbd>PageDown</kbd> - Moves focus to the same date in the next month.

## Global Configuration

You can configure the default options for all `NgpDatePicker` and `NgpDateRangePicker` calendars in your application by using the `provideDatePickerConfig` function in a providers array.

```ts
import { provideDatePickerConfig } from 'ng-primitives/date-picker';

bootstrapApplication(AppComponent, {
  providers: [
    provideDatePickerConfig({
      firstDayOfWeek: 1, // Monday
    }),
  ],
});
```

### NgpDatePickerConfig

<prop-details name="firstDayOfWeek" type="NgpDatePickerFirstDayOfWeekNumber (1-7)">
  Sets which day starts the week in date picker and date range picker calendars.
  Accepts <code>1-7</code> where:
  <ul>
    <li><code>1</code>=Monday,</li>
    <li><code>2</code>=Tuesday,</li>
    <li><code>3</code>=Wednesday,</li>
    <li><code>4</code>=Thursday,</li>
    <li><code>5</code>=Friday,</li>
    <li><code>6</code>=Saturday,</li>
    <li><code>7</code>=Sunday (<code>default</code>).</li>
  </ul>
  Choose based on your users' cultural expectations - most international
  applications use <code>1</code> (Monday), while US applications typically use
  <code>7</code> (Sunday).
  <br />
  Note: When using a non-Sunday start day, update your calendar header column order accordingly.
</prop-details>


---

### Dialog

File: primitives/dialog.md
URL: https://angularprimitives.com/primitives/dialog

# Dialog

A dialog is a floating window that can be used to display information or prompt the user for input.

## Example

```typescript
import { Component } from '@angular/core';
import { NgpButton } from 'ng-primitives/button';
import {
  NgpDialog,
  NgpDialogDescription,
  NgpDialogOverlay,
  NgpDialogTitle,
  NgpDialogTrigger,
} from 'ng-primitives/dialog';

@Component({
  selector: 'app-dialog',
  imports: [
    NgpButton,
    NgpDialog,
    NgpDialogOverlay,
    NgpDialogTitle,
    NgpDialogDescription,
    NgpDialogTrigger,
  ],
  template: `
    <button [ngpDialogTrigger]="dialog" ngpButton>Launch Dialog</button>

    <ng-template #dialog let-close="close">
      <div ngpDialogOverlay>
        <div ngpDialog>
          <h1 ngpDialogTitle>Publish this article?</h1>
          <p ngpDialogDescription>
            Are you sure you want to publish this article? This action is irreversible.
          </p>
          <div class="dialog-footer">
            <button (click)="close()" ngpButton>Cancel</button>
            <button (click)="close()" ngpButton>Confirm</button>
          </div>
        </div>
      </div>
    </ng-template>
  `,
  styles: `
    button {
      padding-left: 1rem;
      padding-right: 1rem;
      border-radius: 0.5rem;
      color: var(--ngp-text-primary);
      border: none;
      outline: none;
      height: 2.5rem;
      font-weight: 500;
      background-color: var(--ngp-background);
      transition: background-color 300ms cubic-bezier(0.4, 0, 0.2, 1);
      box-shadow: var(--ngp-button-shadow);
    }

    button[data-hover] {
      background-color: var(--ngp-background-hover);
    }

    button[data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 2px;
    }

    button[data-press] {
      background-color: var(--ngp-background-active);
    }

    [ngpDialogOverlay] {
      background-color: rgba(0, 0, 0, 0.5);
      backdrop-filter: blur(4px);
      position: fixed;
      inset: 0;
      display: flex;
      justify-content: center;
      align-items: center;
      animation: fadeIn 300ms cubic-bezier(0.4, 0, 0.2, 1);
    }

    [ngpDialogOverlay][data-exit] {
      animation: fadeOut 300ms cubic-bezier(0.4, 0, 0.2, 1);
    }

    [ngpDialog] {
      background-color: var(--ngp-background);
      padding: 24px;
      border-radius: 8px;
      box-shadow: var(--ngp-shadow);
      animation: slideIn 300ms cubic-bezier(0.4, 0, 0.2, 1);
    }

    [ngpDialog][data-exit] {
      animation: slideOut 300ms cubic-bezier(0.4, 0, 0.2, 1);
    }

    [ngpDialogTitle] {
      font-size: 18px;
      line-height: 28px;
      font-weight: 600;
      color: var(--ngp-text-primary);
      margin: 0 0 4px;
    }

    [ngpDialogDescription] {
      font-size: 14px;
      line-height: 20px;
      color: var(--ngp-text-secondary);
      margin: 0;
    }

    .dialog-footer {
      display: flex;
      justify-content: flex-end;
      margin-top: 32px;
      column-gap: 8px;
    }

    .dialog-footer [ngpButton]:last-of-type {
      color: var(--ngp-text-blue);
    }

    @keyframes fadeIn {
      0% {
        opacity: 0;
      }
      100% {
        opacity: 1;
      }
    }

    @keyframes fadeOut {
      0% {
        opacity: 1;
      }
      100% {
        opacity: 0;
      }
    }

    @keyframes slideIn {
      0% {
        transform: translateY(-20px);
        opacity: 0;
      }
      100% {
        transform: translateY(0);
        opacity: 1;
      }
    }
    @keyframes slideOut {
      0% {
        transform: translateY(0);
        opacity: 1;
      }

      100% {
        transform: translateY(-20px);
        opacity: 0;
      }
    }
  `,
})
export default class DialogExample {}

```

## Import

Import the Dialog primitives from `ng-primitives/dialog`.

```ts
import {
  NgpDialog,
  NgpDialogTitle,
  NgpDialogDescription,
  NgpDialogTrigger,
  NgpDialogOverlay,
} from 'ng-primitives/dialog';
```

## Usage

Assemble the dialog directives in your template.

```html
<button [ngpDialogTrigger]="dialog" ngpButton>Launch Dialog</button>

<ng-template #dialog let-close="close">
  <div ngpDialogOverlay>
    <div ngpDialog>
      <h1 ngpDialogTitle>Publish this article?</h1>
      <p ngpDialogDescription>
        Are you sure you want to publish this article? This action is irreversible.
      </p>
      <div class="dialog-footer">
        <button (click)="close()" ngpButton>Cancel</button>
        <button (click)="close()" ngpButton>Confirm</button>
      </div>
    </div>
  </div>
</ng-template>
```

## Reusable Component

Create reusable components that uses the `NgpDialog` and `NgpDialogTrigger` directives.

## Reusable Component

```typescript
import { Component, input } from '@angular/core';
import {
  NgpDialog,
  NgpDialogDescription,
  NgpDialogOverlay,
  NgpDialogTitle,
  provideDialogState,
} from 'ng-primitives/dialog';

@Component({
  selector: 'app-dialog',
  hostDirectives: [NgpDialogOverlay],
  imports: [NgpDialog, NgpDialogTitle, NgpDialogDescription],
  providers: [
    // We need to hoist the dialog state to the host component so that it can be used
    // within ng-content
    provideDialogState(),
  ],
  template: `
    <div ngpDialog>
      <h2 ngpDialogTitle>{{ header() }}</h2>
      <p ngpDialogDescription>
        <ng-content />
      </p>
    </div>
  `,
  styles: `
    :host {
      background-color: rgba(0, 0, 0, 0.5);
      backdrop-filter: blur(4px);
      position: fixed;
      inset: 0;
      display: flex;
      justify-content: center;
      align-items: center;
      animation: fadeIn 300ms cubic-bezier(0.4, 0, 0.2, 1);
    }

    :host[data-exit] {
      animation: fadeOut 300ms cubic-bezier(0.4, 0, 0.2, 1);
    }

    [ngpDialog] {
      background-color: var(--ngp-background);
      padding: 24px;
      border-radius: 8px;
      box-shadow: var(--ngp-shadow);
      animation: slideIn 300ms cubic-bezier(0.4, 0, 0.2, 1);
    }

    [ngpDialog][data-exit] {
      animation: slideOut 300ms cubic-bezier(0.4, 0, 0.2, 1);
    }

    [ngpDialogTitle] {
      font-size: 18px;
      line-height: 28px;
      font-weight: 600;
      color: var(--ngp-text-primary);
      margin: 0 0 4px;
    }

    [ngpDialogDescription] {
      font-size: 14px;
      line-height: 20px;
      color: var(--ngp-text-secondary);
      margin: 0;
    }

    @keyframes fadeIn {
      0% {
        opacity: 0;
      }
      100% {
        opacity: 1;
      }
    }

    @keyframes fadeOut {
      0% {
        opacity: 1;
      }
      100% {
        opacity: 0;
      }
    }

    @keyframes slideIn {
      0% {
        transform: translateY(-20px);
        opacity: 0;
      }
      100% {
        transform: translateY(0);
        opacity: 1;
      }
    }
    @keyframes slideOut {
      0% {
        transform: translateY(0);
        opacity: 1;
      }

      100% {
        transform: translateY(-20px);
        opacity: 0;
      }
    }
  `,
})
export class Dialog {
  /** The dialog title */
  readonly header = input.required<string>();
}

```

## Schematics

Generate a reusable dialog component using the Angular CLI.

```bash npm
ng g ng-primitives:primitive dialog
```

### Options

- `path`: The path at which to create the component file.
- `prefix`: The prefix to apply to the generated component selector.
- `componentSuffix`: The suffix to apply to the generated component class name.
- `fileSuffix`: The suffix to apply to the generated component file name. Defaults to `component`.
- `exampleStyles`: Whether to include example styles in the generated component file. Defaults to `true`.

## API Reference

The following directives are available to import from the `ng-primitives/dialog` package:

### NgpDialog

## API Reference

### NgpDialog



**Selector:** `[ngpDialog]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpDialogRole` | `NgpDialogRole | undefined` | `-` | The dialog role. |
| `ngpDialogModal` | `boolean` | `-` | Whether the dialog is a modal. |

#### Export As

`ngpDialog`



| Attribute   | Description                         |
| ----------- | ----------------------------------- |
| `data-exit` | Applied when the dialog is closing. |

### NgpDialogTitle

## API Reference

### NgpDialogTitle



**Selector:** `[ngpDialogTitle]`

#### Export As

`ngpDialogTitle`



### NgpDialogDescription

## API Reference

### NgpDialogDescription



**Selector:** `[ngpDialogDescription]`

#### Export As

`ngpDialogDescription`



### NgpDialogTrigger

## API Reference

### NgpDialogTrigger



**Selector:** `[ngpDialogTrigger]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpDialogTrigger` | `TemplateRef<NgpDialogContext<unknown` | `-` | The template to launch. |
| `ngpDialogTriggerCloseOnEscape` | `boolean | undefined` | ``true`` | Whether the dialog should close on escape. |

#### Outputs

| Event | Type | Description |
|-------|------|-------------|
| `ngpDialogTriggerClosed` | `T` | Emits whenever the dialog is closed with the given result. |

#### Export As

`ngpDialogTrigger`



| Attribute            | Description                           |
| -------------------- | ------------------------------------- |
| `data-hover`         | Applied when the trigger is hovered.  |
| `data-focus-visible` | Applied when the trigger is focused.  |
| `data-press`         | Applied when the trigger is pressed.  |
| `data-disabled`      | Applied when the trigger is disabled. |

### NgpDialogOverlay

## API Reference

### NgpDialogOverlay



**Selector:** `[ngpDialogOverlay]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpDialogOverlayCloseOnClick` | `boolean | undefined` | ``true`` | Whether the dialog should close on backdrop click. |

#### Export As

`ngpDialogOverlay`



| Attribute   | Description                         |
| ----------- | ----------------------------------- |
| `data-exit` | Applied when the dialog is closing. |

### NgpDialogManager

The `NgpDialogManager` can be used as an alternative to the `NgpDialogTrigger` directive for programmatically opening dialogs.

The manager provides a method to open or close all dialogs and accepts a component or template reference to display.

<prop-details name="open" type="(component: Type | TemplateRef, options?: NgpDialogConfig) => NgpDialogRef">
  Opens a dialog with the specified component or template reference.
</prop-details>

<prop-details name="closeAll" type="() => void">
  Closes all open dialogs.
</prop-details>

## Examples

### Dialog with external data

Data can be passed to the dialog using the `NgpDialogManager`.

## Example

```typescript
import { Component, inject } from '@angular/core';
import { NgpButton } from 'ng-primitives/button';
import {
  injectDialogRef,
  NgpDialog,
  NgpDialogDescription,
  NgpDialogManager,
  NgpDialogOverlay,
  NgpDialogTitle,
} from 'ng-primitives/dialog';

@Component({
  selector: 'app-dialog',
  imports: [NgpButton],
  template: `
    <button (click)="openDialog()" ngpButton>Launch Dialog</button>
  `,
  styles: `
    button {
      padding-left: 1rem;
      padding-right: 1rem;
      border-radius: 0.5rem;
      color: var(--ngp-text-primary);
      border: none;
      outline: none;
      height: 2.5rem;
      font-weight: 500;
      background-color: var(--ngp-background);
      transition: background-color 300ms cubic-bezier(0.4, 0, 0.2, 1);
      box-shadow: var(--ngp-button-shadow);
    }

    button[data-hover] {
      background-color: var(--ngp-background-hover);
    }

    button[data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 2px;
    }

    button[data-press] {
      background-color: var(--ngp-background-active);
    }
  `,
})
export default class DialogDataExample {
  private dialogManager = inject(NgpDialogManager);

  openDialog() {
    this.dialogManager.open(Dialog, {
      data: 'This came from the dialog opener!',
    });
  }
}

@Component({
  imports: [NgpButton, NgpDialog, NgpDialogOverlay, NgpDialogTitle, NgpDialogDescription],
  template: `
    <div ngpDialogOverlay>
      <div ngpDialog>
        <h1 ngpDialogTitle>Dialog data example</h1>
        <p ngpDialogDescription>The following value was passed to the dialog:</p>

        <p class="dialog-data">{{ dialogRef.data }}</p>

        <div class="dialog-footer">
          <button (click)="close()" ngpButton>Cancel</button>
          <button (click)="close()" ngpButton>Confirm</button>
        </div>
      </div>
    </div>
  `,
  styles: `
    button {
      padding-left: 1rem;
      padding-right: 1rem;
      border-radius: 0.5rem;
      color: var(--ngp-text-primary);
      border: none;
      outline: none;
      height: 2.5rem;
      font-weight: 500;
      background-color: var(--ngp-background);
      transition: background-color 300ms cubic-bezier(0.4, 0, 0.2, 1);
      box-shadow: var(--ngp-button-shadow);
    }

    button[data-hover] {
      background-color: var(--ngp-background-hover);
    }

    button[data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 2px;
    }

    button[data-press] {
      background-color: var(--ngp-background-active);
    }

    .dialog-data {
      font-size: 14px;
      font-weight: 600;
      line-height: 20px;
      color: var(--ngp-text-primary);
      margin: 8px 0 0;
    }

    [ngpDialogOverlay] {
      background-color: rgba(0, 0, 0, 0.5);
      backdrop-filter: blur(4px);
      position: fixed;
      inset: 0;
      display: flex;
      justify-content: center;
      align-items: center;
      animation: fadeIn 300ms cubic-bezier(0.4, 0, 0.2, 1);
    }

    [ngpDialogOverlay][data-exit] {
      animation: fadeOut 300ms cubic-bezier(0.4, 0, 0.2, 1);
    }

    [ngpDialog] {
      background-color: var(--ngp-background);
      padding: 24px;
      border-radius: 8px;
      box-shadow: var(--ngp-shadow);
      animation: slideIn 300ms cubic-bezier(0.4, 0, 0.2, 1);
    }

    [ngpDialog][data-exit] {
      animation: slideOut 300ms cubic-bezier(0.4, 0, 0.2, 1);
    }

    [ngpDialogTitle] {
      font-size: 18px;
      line-height: 28px;
      font-weight: 600;
      color: var(--ngp-text-primary);
      margin: 0 0 4px;
    }

    [ngpDialogDescription] {
      font-size: 14px;
      line-height: 20px;
      color: var(--ngp-text-secondary);
      margin: 0;
    }

    .dialog-footer {
      display: flex;
      justify-content: flex-end;
      margin-top: 32px;
      column-gap: 8px;
    }

    .dialog-footer [ngpButton]:last-of-type {
      color: var(--ngp-text-blue);
    }

    @keyframes fadeIn {
      0% {
        opacity: 0;
      }
      100% {
        opacity: 1;
      }
    }

    @keyframes fadeOut {
      0% {
        opacity: 1;
      }
      100% {
        opacity: 0;
      }
    }

    @keyframes slideIn {
      0% {
        transform: translateY(-20px);
        opacity: 0;
      }
      100% {
        transform: translateY(0);
        opacity: 1;
      }
    }
    @keyframes slideOut {
      0% {
        transform: translateY(0);
        opacity: 1;
      }

      100% {
        transform: translateY(-20px);
        opacity: 0;
      }
    }
  `,
})
export class Dialog {
  protected readonly dialogRef = injectDialogRef<string>();

  close() {
    this.dialogRef.close();
  }
}

```

### Drawer

A drawer is a type of dialog that slides in from the side of the screen.

## Example

```typescript
import { Component } from '@angular/core';
import { NgpButton } from 'ng-primitives/button';
import {
  NgpDialog,
  NgpDialogDescription,
  NgpDialogOverlay,
  NgpDialogTitle,
  NgpDialogTrigger,
} from 'ng-primitives/dialog';

@Component({
  selector: 'app-dialog-drawer',
  imports: [
    NgpButton,
    NgpDialog,
    NgpDialogOverlay,
    NgpDialogTitle,
    NgpDialogDescription,
    NgpDialogTrigger,
  ],
  template: `
    <button [ngpDialogTrigger]="drawer" ngpButton>Launch Drawer</button>

    <ng-template #drawer let-close="close">
      <div ngpDialogOverlay>
        <div ngpDialog>
          <h1 ngpDialogTitle>Settings</h1>
          <p ngpDialogDescription>Change your preferences or manage your account in this drawer.</p>
          <div class="drawer-footer">
            <button (click)="close()" ngpButton>Cancel</button>
            <button (click)="close()" ngpButton>Save</button>
          </div>
        </div>
      </div>
    </ng-template>
  `,
  styles: `
    button {
      padding-left: 1rem;
      padding-right: 1rem;
      border-radius: 0.5rem;
      color: var(--ngp-text-primary);
      border: none;
      outline: none;
      height: 2.5rem;
      font-weight: 500;
      background-color: var(--ngp-background);
      transition: background-color 300ms cubic-bezier(0.4, 0, 0.2, 1);
      box-shadow: var(--ngp-button-shadow);
    }

    button[data-hover] {
      background-color: var(--ngp-background-hover);
    }

    button[data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 2px;
    }

    button[data-press] {
      background-color: var(--ngp-background-active);
    }

    [ngpDialogOverlay] {
      background-color: rgba(0, 0, 0, 0.5);
      backdrop-filter: blur(4px);
      position: fixed;
      inset: 0;
      display: flex;
      justify-content: flex-end;
      align-items: stretch;
      animation: fadeIn 300ms cubic-bezier(0.4, 0, 0.2, 1);
    }

    [ngpDialogOverlay][data-exit] {
      animation: fadeOut 300ms cubic-bezier(0.4, 0, 0.2, 1);
    }

    [ngpDialog] {
      background-color: var(--ngp-background);
      padding: 24px;
      width: 320px;
      max-width: 100%;
      height: 100%;
      box-shadow: var(--ngp-shadow);
      animation: drawerSlideIn 300ms cubic-bezier(0.4, 0, 0.2, 1);
    }

    [ngpDialog][data-exit] {
      animation: drawerSlideOut 300ms cubic-bezier(0.4, 0, 0.2, 1);
    }

    [ngpDialogTitle] {
      font-size: 18px;
      line-height: 28px;
      font-weight: 600;
      color: var(--ngp-text-primary);
      margin: 0 0 4px;
    }

    [ngpDialogDescription] {
      font-size: 14px;
      line-height: 20px;
      color: var(--ngp-text-secondary);
      margin: 0;
    }

    .drawer-footer {
      display: flex;
      justify-content: flex-end;
      margin-top: 32px;
      column-gap: 8px;
    }

    .drawer-footer [ngpButton]:last-of-type {
      color: var(--ngp-text-blue);
    }

    @keyframes fadeIn {
      0% {
        opacity: 0;
      }
      100% {
        opacity: 1;
      }
    }

    @keyframes fadeOut {
      0% {
        opacity: 1;
      }
      100% {
        opacity: 0;
      }
    }

    @keyframes drawerSlideIn {
      0% {
        transform: translateX(100%);
        opacity: 0;
      }
      100% {
        transform: translateX(0);
        opacity: 1;
      }
    }

    @keyframes drawerSlideOut {
      0% {
        transform: translateX(0);
        opacity: 1;
      }
      100% {
        transform: translateX(100%);
        opacity: 0;
      }
    }
  `,
})
export default class DialogDrawerExample {}

```

## Accessibility

Adheres to the [WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/examples/dialog/).

### Keyboard Interactions

- <kbd>Esc</kbd>: Close the dialog.
- <kbd>Tab</kbd>: Navigate through focusable elements within the dialog.
- <kbd>Shift</kbd> + <kbd>Tab</kbd>: Navigate backwards through focusable elements within the dialog.

```

```


---

### File Upload

File: primitives/file-upload.md
URL: https://angularprimitives.com/primitives/file-upload

# File Upload

The file upload primitive allows you to trigger a file upload from any element, giving you the more control over the appearance and behavior compared to the native file input.

## Example

```typescript
import { Component } from '@angular/core';
import { NgIcon, provideIcons } from '@ng-icons/core';
import { heroCloudArrowUp } from '@ng-icons/heroicons/outline';
import { NgpFileUpload } from 'ng-primitives/file-upload';

@Component({
  selector: 'app-file-upload',
  imports: [NgpFileUpload, NgIcon],
  providers: [provideIcons({ heroCloudArrowUp })],
  template: `
    <div
      (ngpFileUploadSelected)="onFilesSelected($event)"
      (ngpFileUploadRejected)="onFilesRejected()"
      ngpFileUploadFileTypes=".svg, .pdf"
      ngpFileUpload
      ngpFileUploadMultiple
    >
      <ng-icon name="heroCloudArrowUp" aria-hidden="true" />
      <p class="heading">Select or drag and drop files here.</p>
      <p class="subheading">Max file size: 10MB</p>
    </div>
  `,
  styles: `
    [ngpFileUpload] {
      display: flex;
      cursor: pointer;
      flex-direction: column;
      align-items: center;
      justify-content: center;
      row-gap: 0.25rem;
      border-radius: 0.5rem;
      border: 1px dashed var(--ngp-border-secondary);
      background-color: var(--ngp-background);
      padding: 2rem 3rem;
    }

    [ngpFileUpload][data-dragover] {
      border-color: var(--ngp-border);
      background-color: var(--ngp-background-hover);
    }

    ng-icon {
      color: var(--ngp-text-primary);
      font-size: 20px;
      margin-bottom: 0.25rem;
    }

    .heading {
      font-size: 0.875rem;
      font-weight: 500;
      color: var(--ngp-text-primary);
      line-height: 1.25rem;
      text-align: center;
      margin: 0;
    }

    .subheading {
      font-size: 0.75rem;
      color: var(--ngp-text-secondary);
      line-height: 1rem;
      text-align: center;
      margin: 0;
    }
  `,
})
export default class FileUploadExample {
  onFilesSelected(files: FileList | null): void {
    if (files) {
      alert(`Selected ${files.length} files.`);
    }
  }

  onFilesRejected(): void {
    alert('File type not supported.');
  }
}

```

## Import

Import the FileUpload primitives from `ng-primitives/file-upload`.

```ts
import { NgpFileUpload } from 'ng-primitives/file-upload';
```

## Usage

Assemble the file-upload directives in your template.

```html
<button
  ngpFileUpload
  (ngpFileUploadSelected)="onFilesSelected($event)"
  (ngpFileUploadCanceled)="onCancel()"
></button>
```

## Examples

### File Dropzone

The file dropzone primitive allows you to create a dropzone for files. This functionality is built into the file upload primitive, but can also be used separately if you don't want to show the file upload dialog on click.

## Example

```typescript
import { Component } from '@angular/core';
import { NgpFileDropzone } from 'ng-primitives/file-upload';

@Component({
  selector: 'app-file-dropzone',
  imports: [NgpFileDropzone],
  template: `
    <div
      (ngpFileDropzoneSelected)="onFilesSelected($event)"
      (ngpFileDropzoneRejected)="onFilesRejected()"
      ngpFileDropzoneFileTypes=".svg, .pdf"
      ngpFileDropzone
    >
      <h3>Drag and drop files anywhere here!</h3>
      <p>But clicking won't open a file selection dialog.</p>
    </div>
  `,
  styles: `
    [ngpFileDropzone] {
      display: flex;
      align-items: center;
      justify-content: center;
      padding: 2rem 3rem;
      flex-direction: column;
      row-gap: 0.25rem;
      width: 100%;
      height: 100%;
      border-radius: 0.5rem;
      border: 1px dashed var(--ngp-border-secondary);
      background-color: var(--ngp-background);
      padding: 2rem 3rem;
    }

    [ngpFileDropzone][data-dragover] {
      border-color: var(--ngp-border);
      background-color: var(--ngp-background-hover);
    }

    h3 {
      font-size: 0.875rem;
      font-weight: 500;
      color: var(--ngp-text-primary);
      line-height: 1.25rem;
      text-align: center;
      margin: 0;
    }

    p {
      font-size: 0.75rem;
      color: var(--ngp-text-secondary);
      line-height: 1rem;
      text-align: center;
      margin: 0;
    }
  `,
})
export default class FileDropzoneExample {
  onFilesSelected(files: FileList | null): void {
    if (files) {
      alert(`Selected ${files.length} files.`);
    }
  }

  onFilesRejected(): void {
    alert('File type not supported.');
  }
}

```

## Reusable Component

Create a file upload component that uses the `NgpFileUpload` directive.

## Reusable Component

```typescript
import { Component } from '@angular/core';
import { NgpFileUpload } from 'ng-primitives/file-upload';

@Component({
  selector: 'app-file-upload',
  hostDirectives: [
    {
      directive: NgpFileUpload,
      inputs: [
        'ngpFileUploadFileTypes:types',
        'ngpFileUploadMultiple:multiple',
        'ngpFileUploadDirectory:directory',
        'ngpFileUploadDragDrop:dragDrop',
        'ngpFileUploadDisabled:disabled',
      ],
      outputs: ['ngpFileUploadSelected:selected', 'ngpFileUploadCanceled:canceled'],
    },
  ],
  template: `
    Drop files here or click to upload
  `,
  styles: `
    :host {
      display: flex;
      cursor: pointer;
      flex-direction: column;
      align-items: center;
      justify-content: center;
      row-gap: 0.25rem;
      border-radius: 0.5rem;
      border: 1px dashed var(--ngp-border-secondary);
      background-color: var(--ngp-background);
      padding: 2rem 3rem;
    }

    :host[data-dragover] {
      border-color: var(--ngp-border);
      background-color: var(--ngp-background-hover);
    }
  `,
})
export class FileUpload {}

```

## Schematics

Generate a reusable file upload component using the Angular CLI.

```bash npm
ng g ng-primitives:primitive file-upload
```

### Options

- `path`: The path at which to create the component file.
- `prefix`: The prefix to apply to the generated component selector.
- `componentSuffix`: The suffix to apply to the generated component class name.
- `fileSuffix`: The suffix to apply to the generated component file name. Defaults to `component`.
- `exampleStyles`: Whether to include example styles in the generated component file. Defaults to `true`.

## API Reference

The following directives are available to import from the `ng-primitives/file-upload` package:

### NgpFileUpload

## API Reference

### NgpFileUpload

A directive that allows you to turn any element into a file upload trigger.

**Selector:** `[ngpFileUpload]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpFileUploadFileTypes` | `string[] | undefined` | `-` | The accepted file types. This can be an array of strings or a comma-separated string.
Accepted types can either be file extensions (e.g. `.jpg`) or MIME types (e.g. `image/jpeg`). |
| `ngpFileUploadMultiple` | `boolean` | `-` | Whether to allow multiple files to be selected. |
| `ngpFileUploadDirectory` | `boolean` | `-` | Whether to allow the user to select directories. |
| `ngpFileUploadDragDrop` | `boolean` | `-` | Whether drag-and-drop is enabled. |
| `ngpFileUploadDisabled` | `boolean` | `-` | Whether the file upload is disabled. |

#### Outputs

| Event | Type | Description |
|-------|------|-------------|
| `ngpFileUploadSelected` | `FileList | null` | Emits when the user selects files. |
| `ngpFileUploadCanceled` | `void` | Emits when the user cancel the file selection. |
| `ngpFileUploadRejected` | `void` | Emits when uploaded files are rejected because they do not match the allowed {@link fileTypes}. |
| `ngpFileUploadDragOver` | `boolean` | Emits when the user drags a file over the file upload. |

#### Export As

`ngpFileUpload`



#### Data Attributes

| Attribute            | Description                                      |
| -------------------- | ------------------------------------------------ |
| `data-hover`         | Applied when the element is hovered.             |
| `data-focus-visible` | Applied when the element is focus visible.       |
| `data-press`         | Applied when the element is pressed.             |
| `data-dragover`      | Applied when a file is dragged over the element. |
| `data-disabled`      | Applied when the element is disabled.            |

### NgpFileDropzone

## API Reference

### NgpFileDropzone

Capture files dropped on the element.

**Selector:** `[ngpFileDropzone]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpFileDropzoneFileTypes` | `string[] | undefined` | `-` | The accepted file types. This can be an array of strings or a comma-separated string.
Accepted types can either be file extensions (e.g. `.jpg`) or MIME types (e.g. `image/jpeg`). |
| `ngpFileDropzoneMultiple` | `boolean` | `-` | Whether to allow multiple files to be selected. |
| `ngpFileDropzoneDirectory` | `boolean` | `-` | Whether to allow the user to select directories. |
| `ngpFileDropzoneDisabled` | `boolean` | `-` | Whether the file upload is disabled. |

#### Outputs

| Event | Type | Description |
|-------|------|-------------|
| `ngpFileDropzoneSelected` | `FileList | null` | Emits when the user selects files. |
| `ngpFileDropzoneRejected` | `void` | Emits when uploaded files are rejected because they do not match the allowed {@link fileTypes}. |
| `ngpFileDropzoneDragOver` | `boolean` | Emits when the user drags a file over the file upload. |

#### Export As

`ngpFileDropzone`



#### Data Attributes

| Attribute       | Description                                      |
| --------------- | ------------------------------------------------ |
| `data-hover`    | Applied when the element is hovered.             |
| `data-dragover` | Applied when a file is dragged over the element. |
| `data-disabled` | Applied when the element is disabled.            |


---

### Form Field

File: primitives/form-field.md
URL: https://angularprimitives.com/primitives/form-field

# Form Field

## Example

```typescript
import { Component } from '@angular/core';
import { FormControl, FormGroup, ReactiveFormsModule, Validators } from '@angular/forms';
import {
  NgpDescription,
  NgpError,
  NgpFormControl,
  NgpFormField,
  NgpLabel,
} from 'ng-primitives/form-field';

@Component({
  selector: 'app-form-field',
  imports: [NgpFormField, NgpLabel, NgpError, NgpDescription, NgpFormControl, ReactiveFormsModule],
  template: `
    <div [formGroup]="formGroup" ngpFormField>
      <label ngpLabel>Full Name</label>
      <p ngpDescription>Please include any middle names, no matter how ridiculous.</p>
      <input
        ngpFormControl
        type="text"
        placeholder="Enter your full name"
        formControlName="fullName"
      />
      <p ngpError ngpErrorValidator="required">This field is required.</p>
    </div>
  `,
  styles: `
    :host {
      display: contents;
    }

    [ngpFormField] {
      display: flex;
      flex-direction: column;
      gap: 6px;
      width: 90%;
    }

    [ngpFormControl] {
      height: 36px;
      width: 100%;
      border-radius: 8px;
      padding: 0 16px;
      border: none;
      box-shadow: var(--ngp-input-shadow);
      background-color: var(--ngp-background);
      outline: none;
    }

    [ngpFormControl]:focus {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 2px;
    }

    [ngpFormControl]::placeholder {
      color: var(--ngp-text-placeholder);
    }

    [ngpLabel] {
      color: var(--ngp-text-primary);
      font-size: 0.875rem;
      line-height: 1.25rem;
      font-weight: 500;
      margin: 0;
    }

    [ngpDescription] {
      color: var(--ngp-text-secondary);
      font-size: 0.75rem;
      line-height: 1rem;
      margin: 0 0 4px;
    }

    [ngpError] {
      display: none;
      color: var(--ngp-text-red);
      font-size: 0.75rem;
      line-height: 1rem;
      margin: 0;
    }

    [ngpError][data-validator='fail'][data-dirty] {
      display: block;
    }
  `,
})
export default class FormFieldExample {
  /** The Angular Form Group */
  readonly formGroup = new FormGroup({
    fullName: new FormControl('', Validators.required),
  });
}

```

## Import

Import the FormField primitives from `ng-primitives/form-field`.

```ts
import {
  NgpFormField,
  NgpLabel,
  NgpDescription,
  NgpError,
  NgpFormControl,
} from 'ng-primitives/form-field';
```

## Usage

Assemble the form-field directives in your template.

```html
<div ngpFormField>
  <label ngpLabel>Label</label>
  <!-- Typically ngpFormControl would not be used directly, but a primitive like ngpInput would be used instead -->
  <input ngpFormControl />
  <p ngpDescription>Description</p>
  <p ngpError ngpErrorValidator="required">Error</p>
</div>
```

## Reusable Component

Create a reusable component that uses the `NgpFormField` directive.

## Reusable Component

```typescript
import { Component } from '@angular/core';
import { NgpFormField } from 'ng-primitives/form-field';

@Component({
  selector: 'app-form-field',
  hostDirectives: [NgpFormField],
  template: `
    <ng-content />
  `,
  styles: `
    :host {
      display: flex;
      flex-direction: column;
      gap: 6px;
      width: 90%;
    }
  `,
})
export class FormField {}

```

## Schematics

Generate a reusable form-field component using the Angular CLI.

```bash npm
ng g ng-primitives:primitive form-field
```

### Options

- `path`: The path at which to create the component file.
- `prefix`: The prefix to apply to the generated component selector.
- `componentSuffix`: The suffix to apply to the generated component class name.
- `fileSuffix`: The suffix to apply to the generated component file name. Defaults to `component`.
- `exampleStyles`: Whether to include example styles in the generated component file. Defaults to `true`.

## API Reference

The following directives are available to import from the `ng-primitives/form-field` package:

### NgpFormField

## API Reference

### NgpFormField

The `NgpFormField` directive is a container for form field elements. Any labels, form controls, or descriptions should be placed within this directive.

**Selector:** `[ngpFormField]`

#### Export As

`ngpFormField`



#### Data Attributes

| Attribute       | Description                                |
| --------------- | ------------------------------------------ |
| `data-invalid`  | Applied when the form control is invalid.  |
| `data-valid`    | Applied when the form control is valid.    |
| `data-touched`  | Applied when the form control is touched.  |
| `data-pristine` | Applied when the form control is pristine. |
| `data-dirty`    | Applied when the form control is dirty.    |
| `data-pending`  | Applied when the form control is pending.  |
| `data-disabled` | Applied when the form control is disabled. |

### NgpLabel

## API Reference

### NgpLabel

The `NgpLabel` directive is used to mark a label element within a form field. Preferably, there should use an HTML `<label>` element.

**Selector:** `[ngpLabel]`

#### Export As

`ngpLabel`



#### Data Attributes

| Attribute       | Description                                | Value |
| --------------- | ------------------------------------------ | ----- |
| `data-invalid`  | Applied when the form control is invalid.  |
| `data-valid`    | Applied when the form control is valid.    |
| `data-touched`  | Applied when the form control is touched.  |
| `data-pristine` | Applied when the form control is pristine. |
| `data-dirty`    | Applied when the form control is dirty.    |
| `data-pending`  | Applied when the form control is pending.  |
| `data-disabled` | Applied when the form control is disabled. |

### NgpDescription

## API Reference

### NgpDescription

The `NgpDescription` directive is used to mark a description element within a form field. There may be multiple descriptions associated with a form control.

**Selector:** `[ngpDescription]`

#### Export As

`ngpDescription`



#### Data Attributes

| Attribute       | Description                                | Value |
| --------------- | ------------------------------------------ | ----- |
| `data-invalid`  | Applied when the form control is invalid.  |
| `data-valid`    | Applied when the form control is valid.    |
| `data-touched`  | Applied when the form control is touched.  |
| `data-pristine` | Applied when the form control is pristine. |
| `data-dirty`    | Applied when the form control is dirty.    |
| `data-pending`  | Applied when the form control is pending.  |
| `data-disabled` | Applied when the form control is disabled. |

### NgpError

## API Reference

### NgpError

The `NgpError` directive is used to mark an error message element within a form field. There may be multiple error messages associated with a form control.

**Selector:** `[ngpError]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpErrorValidator` | `string | null` | `-` | The validator associated with the error message. |

#### Export As

`ngpError`



#### Data Attributes

| Attribute        | Description                                                        | Value            |
| ---------------- | ------------------------------------------------------------------ | ---------------- |
| `data-validator` | Whether the validator specified in `ngpErrorValidator` is failing. | `fail` \| `pass` |
| `data-invalid`   | Applied when the form control is invalid.                          | `-`              |
| `data-valid`     | Applied when the form control is valid.                            | `-`              |
| `data-touched`   | Applied when the form control is touched.                          | `-`              |
| `data-pristine`  | Applied when the form control is pristine.                         | `-`              |
| `data-dirty`     | Applied when the form control is dirty.                            | `-`              |
| `data-pending`   | Applied when the form control is pending.                          | `-`              |
| `data-disabled`  | Applied when the form control is disabled.                         | `-`              |

### NgpFormControl

## API Reference

### NgpFormControl

Typically this primitive would be not be used directly, but instead a more specific form control primitive would be used (e.g. `ngpInput`). All of our form control primitives use `ngpFormControl` internally so they will have the same accessibility features as described below.

The `NgpFormControl` directive is used to mark a form control element within a form field. This element will have an `aria-labelledby` attribute set to the ID of the label element within the form field and an `aria-describedby` attribute set to the ID of the description elements within the form field.

**Selector:** `[ngpFormControl]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpFormControlDisabled` | `boolean` | `-` | Whether the form control is disabled by a parent. |

#### Export As

`ngpFormControl`



#### Data Attributes

| Attribute       | Description                                | Value |
| --------------- | ------------------------------------------ | ----- |
| `data-invalid`  | Applied when the form control is invalid.  |
| `data-valid`    | Applied when the form control is valid.    |
| `data-touched`  | Applied when the form control is touched.  |
| `data-pristine` | Applied when the form control is pristine. |
| `data-dirty`    | Applied when the form control is dirty.    |
| `data-pending`  | Applied when the form control is pending.  |
| `data-disabled` | Applied when the form control is disabled. |

## Accessibility

The label and description elements should be associated with the form control using the `aria-labelledby` and `aria-describedby` attributes, respectively. This will ensure that screen readers can provide the necessary context to users.


---

### Icons

File: primitives/icons.md
URL: https://angularprimitives.com/primitives/icons

# Icons

Enhance your application by providing a visually appealing and intuitive way to represent actions, statuses, and features. Icons improve user experience, aid in navigation, and help convey information quickly.

We also maintain the popular [Angular Icons library](https://ng-icons.github.io/ng-icons) which gives you access to over 50,000 icons from popular icon libraries like Font Awesome, Material Design, Heroicons and more.

## Import

The `NgIcon` component is used to render icons in your application. To use icons, you need to import the `NgIcon` directive from `@ng-icons/core`.

Icons must be registered using the `provideIcons` function. The icons you want to use must be individually imported from their respective packages.

```ts
import { NgIcon, provideIcons } from '@ng-icons/core';
import { featherAirplay } from '@ng-icons/feather-icons';
import { heroUsers } from '@ng-icons/heroicons/outline';

@Component({
  selector: 'app-root',
  template: `
    <ng-icon name="featherAirplay" />
    <ng-icon name="heroUsers" />
  `,
  imports: [NgIcon],
  providers: [provideIcons({ featherAirplay, heroUsers })],
})
export class AppComponent {}
```

View the full list of available icons in the [Angular Icons documentation](https://ng-icons.github.io/ng-icons/#/browse-icons).


---

### Input OTP

File: primitives/input-otp.md
URL: https://angularprimitives.com/primitives/input-otp

# Input OTP

One-Time Password (OTP) input component with individual character slots for secure authentication codes.

## Example

```typescript
import { Component, signal } from '@angular/core';
import { NgpInputOtp, NgpInputOtpInput, NgpInputOtpSlot } from 'ng-primitives/input-otp';

@Component({
  selector: 'app-input-otp',
  imports: [NgpInputOtp, NgpInputOtpInput, NgpInputOtpSlot],
  template: `
    <div [(ngpInputOtpValue)]="value" (ngpInputOtpComplete)="onComplete($event)" ngpInputOtp>
      <input ngpInputOtpInput />

      <div class="slots">
        <div ngpInputOtpSlot></div>
        <div ngpInputOtpSlot></div>
        <div ngpInputOtpSlot></div>
        <div ngpInputOtpSlot></div>
        <div ngpInputOtpSlot></div>
        <div ngpInputOtpSlot></div>
      </div>
    </div>
  `,
  styles: `
    [ngpInputOtp] {
      display: flex;
      flex-direction: column;
      gap: 1rem;
      align-items: center;
      position: relative;
    }

    .slots {
      display: flex;
      gap: 0.5rem;
      align-items: center;
    }

    [ngpInputOtpSlot] {
      position: relative;
      width: 3rem;
      height: 3rem;
      border: 2px solid var(--ngp-border);
      border-radius: 0.5rem;
      display: flex;
      align-items: center;
      justify-content: center;
      background-color: var(--ngp-background);
      cursor: pointer;
      transition: all 0.2s ease;
      overflow: hidden;
      font-size: 1.25rem;
      font-weight: 600;
      color: var(--ngp-text-primary);
    }

    [ngpInputOtp][data-disabled] [ngpInputOtpSlot] {
      cursor: default;
      opacity: 0.5;
    }

    [ngpInputOtpSlot]:hover {
      border-color: var(--ngp-border-hover);
    }

    [ngpInputOtpSlot][data-active] {
      border-color: var(--ngp-focus-ring);
      box-shadow: 0 0 0 1px var(--ngp-focus-ring);
    }

    [ngpInputOtpSlot][data-placeholder] {
      color: var(--ngp-text-placeholder);
    }

    [ngpInputOtpSlot][data-caret]::after {
      content: '';
      position: absolute;
      width: 1px;
      height: 1.5rem;
      background-color: var(--ngp-focus-ring);
      animation: blink 1s infinite;
    }

    @keyframes blink {
      0%,
      50% {
        opacity: 1;
      }
      51%,
      100% {
        opacity: 0;
      }
    }
  `,
})
export default class InputOtpExample {
  readonly value = signal<string>('');

  protected onComplete(value: string): void {
    console.log('OTP Complete:', value);
  }
}

```

## Import

Import the InputOtp primitives from `ng-primitives/input-otp`.

```ts
import { NgpInputOtp, NgpInputOtpInput, NgpInputOtpSlot } from 'ng-primitives/input-otp';
```

## Usage

Assemble the input-otp directives in your template.

```html
<div ngpInputOtp [(ngpInputOtpValue)]="otpValue">
  <input ngpInputOtpInput />

  <div>
    <div ngpInputOtpSlot></div>
    <div ngpInputOtpSlot></div>
    <div ngpInputOtpSlot></div>
  </div>
</div>
```

## Reusable Component

Create a reusable component that uses the `NgpInputOtp` directive.

## Reusable Component

```typescript
import { BooleanInput, NumberInput } from '@angular/cdk/coercion';
import {
  booleanAttribute,
  Component,
  computed,
  forwardRef,
  input,
  model,
  numberAttribute,
  signal,
} from '@angular/core';
import { ControlValueAccessor, NG_VALUE_ACCESSOR } from '@angular/forms';
import { NgpInputOtp, NgpInputOtpInput, NgpInputOtpSlot } from 'ng-primitives/input-otp';
import { ChangeFn, TouchedFn } from 'ng-primitives/utils';

@Component({
  selector: 'app-input-otp',
  imports: [NgpInputOtp, NgpInputOtpInput, NgpInputOtpSlot],
  providers: [
    {
      provide: NG_VALUE_ACCESSOR,
      useExisting: forwardRef(() => InputOtp),
      multi: true,
    },
  ],
  template: `
    <div
      [ngpInputOtpValue]="value()"
      [ngpInputOtpDisabled]="disabled() || formDisabled()"
      [ngpInputOtpPattern]="pattern()"
      [ngpInputOtpPlaceholder]="placeholder()"
      [ngpInputOtpInputMode]="inputMode()"
      (ngpInputOtpValueChange)="onValueChange($event)"
      (ngpInputOtpComplete)="onComplete()"
      ngpInputOtp
    >
      <input ngpInputOtpInput />
      <div class="slots">
        @for (_ of slots(); track $index) {
          <div class="slot" ngpInputOtpSlot></div>
        }
      </div>
    </div>
  `,
  styles: `
    :host {
      display: inline-flex;
      flex-direction: column;
      gap: 12px;
      max-width: 100%;
    }

    .slots {
      display: flex;
      gap: 8px;
    }

    .slot {
      display: flex;
      align-items: center;
      justify-content: center;
      width: 48px;
      height: 48px;
      border: 2px solid var(--ngp-border);
      border-radius: 8px;
      background: var(--ngp-background);
      font-size: 18px;
      font-weight: 600;
      color: var(--ngp-text-primary);
      transition: all 150ms cubic-bezier(0.4, 0, 0.2, 1);
      cursor: pointer;
      position: relative;
    }

    .slot[data-filled] {
      border-color: var(--ngp-border-strong);
      background: var(--ngp-background-accent);
    }

    .slot[data-active] {
      border-color: var(--ngp-focus-ring);
      box-shadow: 0 0 0 1px var(--ngp-focus-ring);
    }

    .slot[data-placeholder] {
      color: var(--ngp-text-placeholder);
    }

    .slot[data-caret]::after {
      content: '';
      position: absolute;
      width: 2px;
      height: 20px;
      background: var(--ngp-focus-ring);
      animation: blink 1s infinite;
    }

    @keyframes blink {
      0%,
      50% {
        opacity: 1;
      }
      51%,
      100% {
        opacity: 0;
      }
    }

    :host([data-disabled]) .slot {
      background: var(--ngp-background-disabled);
      color: var(--ngp-text-disabled);
      border-color: var(--ngp-border-disabled);
      cursor: not-allowed;
    }
  `,
})
export class InputOtp implements ControlValueAccessor {
  /**
   * The number of slots to display.
   */
  readonly length = input<number, NumberInput>(6, {
    transform: numberAttribute,
  });

  /**
   * Whether the input is disabled.
   */
  readonly disabled = input<boolean, BooleanInput>(false, {
    transform: booleanAttribute,
  });

  /**
   * The pattern for allowed characters.
   */
  readonly pattern = input('[0-9]');

  /**
   * The placeholder character for empty slots.
   */
  readonly placeholder = input('');

  /**
   * The input mode for the hidden input.
   */
  readonly inputMode = input<'numeric' | 'text' | 'decimal' | 'tel' | 'search' | 'email' | 'url'>(
    'numeric',
  );

  /**
   * Create an array for tracking slots.
   */
  protected readonly slots = computed(() => Array.from({ length: this.length() }, (_, i) => i));

  /**
   * The current value.
   */
  readonly value = model<string>('');

  private onChange: ChangeFn<string> = () => {};
  private onTouched: TouchedFn = () => {};

  protected readonly formDisabled = signal(false);

  /**
   * Handle value changes from the input-otp directive.
   */
  onValueChange(value: string): void {
    this.value.set(value);
    this.onChange(value);
  }

  /**
   * Handle completion events from the input-otp directive.
   */
  onComplete(): void {
    this.onTouched();
  }

  // ControlValueAccessor implementation
  writeValue(value: string): void {
    this.value.set(value);
  }

  registerOnChange(fn: ChangeFn<string>): void {
    this.onChange = fn;
  }

  registerOnTouched(fn: TouchedFn): void {
    this.onTouched = fn;
  }

  setDisabledState(isDisabled: boolean): void {
    this.formDisabled.set(isDisabled);
  }
}

```

## Schematics

Generate a reusable input-otp component using the Angular CLI.

```bash npm
ng g ng-primitives:primitive input-otp
```

### Options

- `path`: The path at which to create the component file.
- `prefix`: The prefix to apply to the generated component selector.
- `componentSuffix`: The suffix to apply to the generated component class name.
- `fileSuffix`: The suffix to apply to the generated component file name. Defaults to `component`.
- `exampleStyles`: Whether to include example styles in the generated component file. Defaults to `true`.

## API Reference

The following directives are available to import from the `ng-primitives/input-otp` package:

### NgpInputOtp

The root container for the OTP input component.

## API Reference

### NgpInputOtp



**Selector:** `[ngpInputOtp]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpInputOtpValue` | `string` | `-` | The current value of the OTP. |
| `ngpInputOtpPattern` | `string` | `-` | The regex pattern for allowed characters. |
| `ngpInputOtpInputMode` | `NgpInputOtpInputMode` | `-` | The input mode for the hidden input. |
| `ngpInputOtpPasteTransformer` | `((text: string) => string) | undefined` | `-` | Function to transform pasted text. |
| `ngpInputOtpDisabled` | `boolean` | `-` | Whether the input-otp is disabled. |
| `ngpInputOtpPlaceholder` | `string` | `-` | The placeholder character to display when a slot is empty. |

#### Outputs

| Event | Type | Description |
|-------|------|-------------|
| `ngpInputOtpValueChange` | `string` | Event emitted when the value changes. |
| `ngpInputOtpComplete` | `string` | Event emitted when the OTP is complete (maxLength characters entered). |

#### Export As

`ngpInputOtp`



### NgpInputOtpInput

The hidden input element that captures user input.

## API Reference

### NgpInputOtpInput



**Selector:** `input[ngpInputOtpInput]`

#### Export As

`ngpInputOtpInput`



### NgpInputOtpSlot

A directive that represents individual character slots. Automatically registers with the parent input OTP and derives its index from registration order.

## API Reference

### NgpInputOtpSlot



**Selector:** `[ngpInputOtpSlot]`

#### Export As

`ngpInputOtpSlot`



#### Data Attributes

| Attribute          | Description                                       |
| ------------------ | ------------------------------------------------- |
| `data-slot-index`  | The index of this slot.                           |
| `data-active`      | Added to the active (focused) slot.               |
| `data-filled`      | Added to slots that contain a character.          |
| `data-caret`       | Added to slots that show the cursor.              |
| `data-placeholder` | Added to slots that should show placeholder text. |


---

### Input

File: primitives/input.md
URL: https://angularprimitives.com/primitives/input

# Input

The input primitive can be used to enhance the accessibility of an input element and provide consistent interaction handling for hover, focus, press and autofill states.

## Example

```typescript
import { Component } from '@angular/core';
import { NgpInput } from 'ng-primitives/input';

@Component({
  selector: 'app-input',
  imports: [NgpInput],
  template: `
    <input ngpInput type="text" placeholder="Enter your full name" />
  `,
  styles: `
    :host {
      display: contents;
    }

    [ngpInput] {
      height: 36px;
      width: 100%;
      border-radius: 8px;
      padding: 0 16px;
      border: none;
      box-shadow: var(--ngp-input-shadow);
      background-color: var(--ngp-background);
      outline: none;
    }

    [ngpInput]:focus {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 2px;
    }

    [ngpInput]::placeholder {
      color: var(--ngp-text-placeholder);
    }
  `,
})
export default class InputExample {}

```

## Import

Import the Input primitives from `ng-primitives/input`.

```ts
import { NgpInput } from 'ng-primitives/input';
```

## Usage

Assemble the input directives in your template.

```html
<input ngpInput type="text" />
```

## Reusable Component

Create an input component that uses the `NgpInput` directive.

## Reusable Component

```typescript
import { Component } from '@angular/core';
import { NgpInput } from 'ng-primitives/input';

@Component({
  selector: 'input[app-input]',
  hostDirectives: [{ directive: NgpInput, inputs: ['disabled'] }],
  template: '',
  styles: `
    :host {
      height: 36px;
      width: 100%;
      border-radius: 8px;
      padding: 0 16px;
      border: none;
      box-shadow: var(--ngp-input-shadow);
      outline: none;
      box-sizing: border-box;
    }

    :host:focus {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 2px;
    }

    :host::placeholder {
      color: var(--ngp-text-placeholder);
    }
  `,
})
export class Input {}

```

## Schematics

Generate a reusable input component using the Angular CLI.

```bash npm
ng g ng-primitives:primitive input
```

### Options

- `path`: The path at which to create the component file.
- `prefix`: The prefix to apply to the generated component selector.
- `componentSuffix`: The suffix to apply to the generated component class name.
- `fileSuffix`: The suffix to apply to the generated component file name. Defaults to `component`.
- `exampleStyles`: Whether to include example styles in the generated component file. Defaults to `true`.

## Examples

Here are some additional examples of how to use the Input primitive.

### Input Form Field

The input automatically integrates with the form field primitives.

## Example

```typescript
import { Component } from '@angular/core';
import { NgpDescription, NgpFormField, NgpLabel } from 'ng-primitives/form-field';
import { NgpInput } from 'ng-primitives/input';

@Component({
  selector: 'app-input-form-field',
  imports: [NgpInput, NgpLabel, NgpDescription, NgpFormField],
  template: `
    <div ngpFormField>
      <label ngpLabel>Email address</label>
      <p ngpDescription>We'll never share your email with anyone else, unless they pay us.</p>
      <input ngpInput type="email" placeholder="Enter your email address" />
    </div>
  `,
  styles: `
    :host {
      display: contents;
    }

    [ngpFormField] {
      display: flex;
      flex-direction: column;
      gap: 6px;
      width: 90%;
    }

    [ngpInput] {
      height: 36px;
      width: 100%;
      border-radius: 8px;
      padding: 0 16px;
      border: none;
      box-shadow: var(--ngp-input-shadow);
      background-color: var(--ngp-background);
      outline: none;
    }

    [ngpInput]:focus {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 2px;
    }

    [ngpInput]::placeholder {
      color: var(--ngp-text-placeholder);
    }

    [ngpLabel] {
      color: var(--ngp-text-primary);
      font-size: 0.875rem;
      line-height: 1.25rem;
      font-weight: 500;
      margin: 0;
    }

    [ngpDescription] {
      color: var(--ngp-text-secondary);
      font-size: 0.75rem;
      line-height: 1rem;
      margin: 0 0 4px;
    }
  `,
})
export default class InputFormFieldExample {}

```

## API Reference

The following directives are available to import from the `ng-primitives/input` package:

### NgpInput

## API Reference

### NgpInput



**Selector:** `input[ngpInput]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `disabled` | `boolean` | `-` | Whether the element is disabled. |

#### Export As

`ngpInput`



#### Data Attributes

The following data attributes are applied to the `ngpInput` directive:

| Attribute       | Description                           |
| --------------- | ------------------------------------- |
| `data-hover`    | Applied to the input when hovered.    |
| `data-focus`    | Applied to the input when focused.    |
| `data-disabled` | Applied to the input when disabled.   |
| `data-autofill` | Applied to the input when autofilled. |


---

### Listbox

File: primitives/listbox.md
URL: https://angularprimitives.com/primitives/listbox

# Listbox

A listbox presents a set of choices and lets users select one or multiple options.

## Example

```typescript
import { Component, signal } from '@angular/core';
import { NgIcon, provideIcons } from '@ng-icons/core';
import { heroCheckSolid } from '@ng-icons/heroicons/solid';
import { NgpListbox, NgpListboxOption } from 'ng-primitives/listbox';

@Component({
  selector: 'app-listbox',
  imports: [NgpListbox, NgpListboxOption, NgIcon],
  providers: [provideIcons({ heroCheckSolid })],
  template: `
    <div [(ngpListboxValue)]="selection" ngpListbox aria-label="Characters">
      @for (option of options; track option.id) {
        <div [ngpListboxOptionValue]="option" ngpListboxOption>
          <ng-icon name="heroCheckSolid" size="16px" />
          {{ option.name }}
        </div>
      }
    </div>
  `,
  styles: `
    [ngpListbox] {
      background-color: var(--ngp-background);
      border: 1px solid var(--ngp-border);
      padding: 0.25rem;
      border-radius: 0.75rem;
      outline: none;
    }

    [ngpListboxOption] {
      display: flex;
      align-items: center;
      gap: 0.5rem;
      padding: 0.375rem 0.75rem;
      cursor: pointer;
      border-radius: 0.5rem;
      width: 200px;
      height: 36px;
      box-sizing: border-box;
    }

    [ngpListboxOption][data-hover] {
      background-color: var(--ngp-background-hover);
    }

    [ngpListboxOption][data-press] {
      background-color: var(--ngp-background-active);
    }

    [ngpListboxOption][data-active] {
      background-color: var(--ngp-background-active);
    }

    [ngpListboxOption] ng-icon {
      visibility: hidden;
    }

    [ngpListboxOption][data-selected] ng-icon {
      visibility: visible;
    }
  `,
})
export default class ListboxExample {
  readonly options: Option[] = [
    { id: 1, name: 'Marty McFly' },
    { id: 2, name: 'Doc Brown' },
    { id: 3, name: 'Biff Tannen' },
    { id: 4, name: 'Lorraine Baines' },
    { id: 5, name: 'George McFly' },
  ];

  readonly selection = signal<Option[]>([this.options[0]]);
}

interface Option {
  id: number;
  name: string;
}

```

## Import

Import the Listbox primitives from `ng-primitives/listbox`.

```ts
import { NgpListbox } from 'ng-primitives/listbox';
```

## Usage

Assemble the listbox directives in your template.

```html
<div ngpListbox>
  <div ngpListboxOption ngpListboxOptionValue="1">Option 1</div>
  <div ngpListboxOption ngpListboxOptionValue="2">Option 2</div>
  <div ngpListboxOption ngpListboxOptionValue="3">Option 3</div>
</div>
```

## Reusable Component

Create a reusable component that uses the listbox directives.

## Reusable Component

```typescript
import { BooleanInput } from '@angular/cdk/coercion';
import { booleanAttribute, Component, input, model } from '@angular/core';
import { ControlValueAccessor } from '@angular/forms';
import { provideIcons } from '@ng-icons/core';
import { heroChevronDownSolid } from '@ng-icons/heroicons/solid';
import { NgpSelectionMode } from 'ng-primitives/common';
import { injectListboxState, NgpListbox, provideListboxState } from 'ng-primitives/listbox';
import { ChangeFn, provideValueAccessor, TouchedFn } from 'ng-primitives/utils';

@Component({
  selector: 'app-listbox',
  providers: [
    provideIcons({ heroChevronDownSolid }),
    provideListboxState(),
    provideValueAccessor(Listbox),
  ],
  imports: [NgpListbox],
  template: `
    <div
      [(ngpListboxValue)]="value"
      [ngpListboxMode]="mode()"
      [ngpListboxDisabled]="disabled()"
      [ngpListboxCompareWith]="compareWith()"
      [attr.aria-label]="ariaLabel()"
      (ngpListboxValueChange)="onListboxValueChange($event)"
      ngpListbox
    >
      <ng-content />
    </div>
  `,
  styles: `
    [ngpListbox] {
      background-color: var(--ngp-background);
      border: 1px solid var(--ngp-border);
      padding: 0.25rem;
      border-radius: 0.75rem;
      outline: none;
      width: var(--ngp-popover-trigger-width);
      box-sizing: border-box;
    }
  `,
  host: {
    '[attr.aria-label]': 'null',
  },
})
export class Listbox implements ControlValueAccessor {
  /**
   * Access the listbox state
   */
  protected readonly state = injectListboxState<NgpListbox<string>>();

  /**
   * The listbox mode.
   */
  readonly mode = input<NgpSelectionMode>('single');

  /**
   * The listbox value.
   */
  readonly value = model<string[]>([]);

  /**
   * The listbox disabled state.
   */
  readonly disabled = input<boolean, BooleanInput>(false, {
    transform: booleanAttribute,
  });

  /**
   * The comparator function to use when comparing values.
   */
  readonly compareWith = input<(a: string, b: string) => boolean>((a, b) => a === b);

  /**
   * The placeholder text.
   */
  readonly placeholder = input<string>('Select an option');

  /**
   * The aria-label attribute for the listbox.
   */
  readonly ariaLabel = input<string>('Listbox', {
    alias: 'aria-label',
  });

  /**
   * The onChange callback.
   */
  protected onChange?: ChangeFn<string[]>;

  /**
   * The onTouch callback.
   */
  protected onTouch?: TouchedFn;

  writeValue(value: string[]): void {
    this.state()?.value.set(value);
  }

  registerOnChange(fn: ChangeFn<string[]>): void {
    this.onChange = fn;
  }

  registerOnTouched(fn: TouchedFn): void {
    this.onTouch = fn;
  }

  setDisabledState(isDisabled: boolean): void {
    this.state()?.disabled.set(isDisabled);
  }

  onListboxValueChange(value: string[]): void {
    this.value.set(value);
    if (this.onChange) this.onChange(value);
  }
}

```

## Schematics

Generate a reusable listbox component using the Angular CLI.

```bash npm
ng g ng-primitives:primitive listbox
```

### Options

- `path`: The path at which to create the component file.
- `prefix`: The prefix to apply to the generated component selector.
- `componentSuffix`: The suffix to apply to the generated component class name.
- `fileSuffix`: The suffix to apply to the generated component file name. Defaults to `component`.
- `exampleStyles`: Whether to include example styles in the generated component file. Defaults to `true`.

## Examples

### Multi-Select Listbox

The listbox can be configured to allow multiple selections.

## Example

```typescript
import { Component, signal } from '@angular/core';
import { NgIcon, provideIcons } from '@ng-icons/core';
import { heroCheckSolid } from '@ng-icons/heroicons/solid';
import { NgpListbox, NgpListboxOption } from 'ng-primitives/listbox';

@Component({
  selector: 'app-listbox-multiple',
  imports: [NgpListbox, NgpListboxOption, NgIcon],
  providers: [provideIcons({ heroCheckSolid })],
  template: `
    <div [(ngpListboxValue)]="selection" ngpListbox ngpListboxMode="multiple">
      @for (option of options; track option.id) {
        <div [ngpListboxOptionValue]="option" ngpListboxOption>
          <ng-icon name="heroCheckSolid" size="16px" />
          {{ option.name }}
        </div>
      }
    </div>
  `,
  styles: `
    [ngpListbox] {
      background-color: var(--ngp-background);
      border: 1px solid var(--ngp-border);
      padding: 0.25rem;
      border-radius: 0.75rem;
      outline: none;
    }

    [ngpListboxOption] {
      display: flex;
      align-items: center;
      gap: 0.5rem;
      padding: 0.375rem 0.75rem;
      cursor: pointer;
      border-radius: 0.5rem;
      width: 200px;
      height: 36px;
      box-sizing: border-box;
    }

    [ngpListboxOption][data-hover] {
      background-color: var(--ngp-background-hover);
    }

    [ngpListboxOption][data-press] {
      background-color: var(--ngp-background-active);
    }

    [ngpListboxOption][data-active] {
      background-color: var(--ngp-background-active);
    }

    [ngpListboxOption] ng-icon {
      visibility: hidden;
    }

    [ngpListboxOption][data-selected] ng-icon {
      visibility: visible;
    }
  `,
})
export default class ListboxMultipleExample {
  readonly options: Option[] = [
    { id: 1, name: 'Marty McFly' },
    { id: 2, name: 'Doc Brown' },
    { id: 3, name: 'Biff Tannen' },
    { id: 4, name: 'Lorraine Baines' },
    { id: 5, name: 'George McFly' },
  ];

  readonly selection = signal<Option[]>([this.options[0], this.options[1]]);
}

interface Option {
  id: number;
  name: string;
}

```

### Listbox with Sections

The listbox can be configured to have sections and headers.

## Example

```typescript
import { Component, signal } from '@angular/core';
import { NgIcon, provideIcons } from '@ng-icons/core';
import { heroCheckSolid } from '@ng-icons/heroicons/solid';
import {
  NgpListbox,
  NgpListboxHeader,
  NgpListboxOption,
  NgpListboxSection,
} from 'ng-primitives/listbox';

@Component({
  selector: 'app-listbox-sections',
  imports: [NgpListbox, NgpListboxOption, NgpListboxSection, NgpListboxHeader, NgIcon],
  providers: [provideIcons({ heroCheckSolid })],
  template: `
    <div [(ngpListboxValue)]="selection" ngpListbox aria-label="Sections">
      @for (section of sections; track section.name) {
        <header class="listbox-header" ngpListboxHeader>{{ section.name }}</header>

        <div ngpListboxSection>
          @for (option of section.options; track option.id) {
            <div [ngpListboxOptionValue]="option" ngpListboxOption>
              <ng-icon name="heroCheckSolid" size="16px" />
              {{ option.name }}
            </div>
          }
        </div>
      }
    </div>
  `,
  styles: `
    [ngpListbox] {
      background-color: var(--ngp-background);
      border: 1px solid var(--ngp-border);
      padding: 0.25rem;
      border-radius: 0.75rem;
      list-style: none;
      outline: none;
      max-height: 300px;
      overflow-y: auto;
    }

    .listbox-header {
      padding: 0.25rem 0.75rem;
      font-weight: 600;
    }

    [ngpListboxOption] {
      display: flex;
      align-items: center;
      gap: 0.5rem;
      padding: 0.375rem 0.75rem;
      cursor: pointer;
      border-radius: 0.5rem;
      width: 200px;
      height: 36px;
      box-sizing: border-box;
    }

    [ngpListboxOption][data-hover] {
      background-color: var(--ngp-background-hover);
    }

    [ngpListboxOption][data-press] {
      background-color: var(--ngp-background-active);
    }

    [ngpListboxOption][data-active] {
      background-color: var(--ngp-background-active);
    }

    [ngpListboxOption] ng-icon {
      visibility: hidden;
    }

    [ngpListboxOption][data-selected] ng-icon {
      visibility: visible;
    }
  `,
})
export default class ListboxSectionsExample {
  readonly sections: Section[] = [
    {
      name: 'Characters',
      options: [
        { id: 1, name: 'Marty McFly' },
        { id: 2, name: 'Doc Brown' },
        { id: 3, name: 'Biff Tannen' },
        { id: 4, name: 'Lorraine Baines' },
        { id: 5, name: 'George McFly' },
      ],
    },
    {
      name: 'Locations',
      options: [
        { id: 6, name: 'Hill Valley' },
        { id: 7, name: 'Twin Pines Mall' },
        { id: 8, name: 'Lyon Estates' },
      ],
    },
    {
      name: 'Items',
      options: [
        { id: 9, name: 'DeLorean' },
        { id: 10, name: 'Hoverboard' },
        { id: 11, name: 'Sports Almanac' },
        { id: 13, name: 'Plutonium' },
        { id: 14, name: 'Mr. Fusion' },
        { id: 15, name: 'Flux Capacitor' },
      ],
    },
  ];

  readonly selection = signal<Option[]>([this.sections[0].options[0]]);
}

interface Section {
  name: string;
  options: Option[];
}

interface Option {
  id: number;
  name: string;
}

```

### Listbox with popover

The listbox can be paired with the `NgpPopover` directive to create a dropdown listbox.

## Example

```typescript
import { Component, signal } from '@angular/core';
import { NgIcon, provideIcons } from '@ng-icons/core';
import { heroCheckSolid, heroChevronDownSolid } from '@ng-icons/heroicons/solid';
import { NgpButton } from 'ng-primitives/button';
import { NgpDescription, NgpFormField, NgpLabel } from 'ng-primitives/form-field';
import { NgpListbox, NgpListboxOption, NgpListboxTrigger } from 'ng-primitives/listbox';
import { NgpPopover, NgpPopoverTrigger } from 'ng-primitives/popover';

@Component({
  selector: 'app-listbox-select',
  imports: [
    NgpListbox,
    NgpLabel,
    NgpDescription,
    NgpListboxOption,
    NgpButton,
    NgpFormField,
    NgpPopover,
    NgpPopoverTrigger,
    NgpListboxTrigger,
    NgIcon,
  ],
  providers: [provideIcons({ heroCheckSolid, heroChevronDownSolid })],
  template: `
    <div ngpFormField>
      <label ngpLabel>Character</label>
      <p ngpDescription>Select a character from the list below.</p>

      <button [ngpPopoverTrigger]="dropdown" ngpButton ngpListboxTrigger>
        {{ selection()[0].name }}
        <ng-icon name="heroChevronDownSolid" />
      </button>

      <ng-template #dropdown>
        <div [(ngpListboxValue)]="selection" ngpPopover ngpListbox aria-label="Characters">
          @for (option of options; track option.id) {
            <div [ngpListboxOptionValue]="option" ngpListboxOption>
              <ng-icon name="heroCheckSolid" size="16px" />
              {{ option.name }}
            </div>
          }
        </div>
      </ng-template>
    </div>
  `,
  styles: `
    [ngpFormField] {
      display: flex;
      flex-direction: column;
      gap: 6px;
      width: 90%;
    }

    [ngpLabel] {
      color: var(--ngp-text-primary);
      font-size: 0.875rem;
      line-height: 1.25rem;
      font-weight: 500;
      margin: 0;
    }

    [ngpDescription] {
      color: var(--ngp-text-secondary);
      font-size: 0.75rem;
      line-height: 1rem;
      margin: 0 0 4px;
    }

    [ngpButton] {
      display: flex;
      justify-content: space-between;
      align-items: center;
      height: 36px;
      width: 300px;
      border-radius: 8px;
      padding: 0 16px;
      border: none;
      background-color: var(--ngp-background);
      text-align: left;
      box-shadow: var(--ngp-input-shadow);
      outline: none;
    }

    [ngpButton][data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 2px;
    }

    [ngpListbox] {
      background-color: var(--ngp-background);
      border: 1px solid var(--ngp-border);
      padding: 0.25rem;
      border-radius: 0.75rem;
      outline: none;
      position: absolute;
      animation: popover-show 0.1s ease-out;
      width: var(--ngp-popover-trigger-width);
      box-shadow: var(--ngp-shadow-lg);
    }

    [ngpListboxOption] {
      display: flex;
      align-items: center;
      gap: 0.5rem;
      padding: 0.375rem 0.75rem;
      cursor: pointer;
      border-radius: 0.5rem;
      width: 100%;
      height: 36px;
      box-sizing: border-box;
    }

    [ngpListboxOption][data-hover] {
      background-color: var(--ngp-background-hover);
    }

    [ngpListboxOption][data-press] {
      background-color: var(--ngp-background-active);
    }

    [ngpListboxOption][data-active] {
      background-color: var(--ngp-background-active);
    }

    [ngpListboxOption] ng-icon {
      visibility: hidden;
    }

    [ngpListboxOption][data-selected] ng-icon {
      visibility: visible;
    }

    @keyframes popover-show {
      0% {
        opacity: 0;
        transform: translateY(-10px) scale(0.9);
      }
      100% {
        opacity: 1;
        transform: translateY(0) scale(1);
      }
    }
  `,
})
export default class ListboxSelectExample {
  readonly options: Option[] = [
    { id: 1, name: 'Marty McFly' },
    { id: 2, name: 'Doc Brown' },
    { id: 3, name: 'Biff Tannen' },
    { id: 4, name: 'Lorraine Baines' },
    { id: 5, name: 'George McFly' },
  ];

  readonly selection = signal<Option[]>([this.options[0]]);
}

interface Option {
  id: number;
  name: string;
}

```

## API Reference

The following directives are available to import from the `ng-primitives/listbox` package:

### NgpListbox

## API Reference

### NgpListbox



**Selector:** `[ngpListbox]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpListboxMode` | `NgpSelectionMode` | `-` | The listbox selection mode. |
| `ngpListboxValue` | `T[]` | `-` | The listbox selection. |
| `ngpListboxDisabled` | `boolean` | `-` | The listbox disabled state. |
| `ngpListboxCompareWith` | `(a: T, b: T) => boolean` | `-` | The comparator function to use when comparing values.
If not provided, strict equality (===) is used. |

#### Outputs

| Event | Type | Description |
|-------|------|-------------|
| `ngpListboxValueChange` | `T[]` | Emits when the listbox selection changes. |

#### Export As

`ngpListbox`



#### Data Attributes

The following data attributes are applied to the `ngpListbox` directive:

| Attribute            | Description                                           |
| -------------------- | ----------------------------------------------------- |
| `data-focus-visible` | Applied to the listbox when focused via the keyboard. |

### NgpListboxOption

## API Reference

### NgpListboxOption



**Selector:** `[ngpListboxOption]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpListboxOptionValue` | `T` | `-` | The value of the option. |
| `ngpListboxOptionDisabled` | `boolean` | `-` | Whether the option is disabled. |

#### Export As

`ngpListboxOption`



#### Data Attributes

The following data attributes are applied to the `ngpListboxOption` directive:

| Attribute            | Description                                                     |
| -------------------- | --------------------------------------------------------------- |
| `data-hover`         | Applied to the listbox option when hovered.                     |
| `data-focus`         | Applied to the listbox option when focused.                     |
| `data-focus-visible` | Applied to the listbox option when focused via the keyboard.    |
| `data-active`        | Applied to the listbox option when it is the active descendant. |
| `data-disabled`      | Applied to the listbox option when it is disabled.              |
| `data-selected`      | Applied to the listbox option when it is selected.              |

### NgpListboxSection

## API Reference

### NgpListboxSection



**Selector:** `[ngpListboxSection]`

#### Export As

`ngpListboxSection`



### NgpListboxTrigger

## API Reference

### NgpListboxTrigger



**Selector:** `[ngpListboxTrigger]`

#### Export As

`ngpListboxTrigger`



Augments the popover trigger with listbox-specific behavior, such as opening the listbox when the arrow keys are pressed.

## Accessibility

Adheres to the [WAI-ARIA Listbox Design Pattern](https://www.w3.org/TR/wai-aria-practices-1.1/#Listbox).

### Keyboard Interactions

- <kbd>Arrow Down</kbd> - Move focus to the next option.
- <kbd>Arrow Up</kbd> - Move focus to the previous option.
- <kbd>Home</kbd> - Move focus to the first option.
- <kbd>End</kbd> - Move focus to the last option.
- <kbd>Space</kbd> - Select the focused option.
- <kbd>Enter</kbd> - Select the focused option.
- <kbd>Escape</kbd> - Close the listbox.


---

### Menu

File: primitives/menu.md
URL: https://angularprimitives.com/primitives/menu

# Menu

A menu is a list of options or commands presented to the user in a dropdown list.

## Example

```typescript
import { Component } from '@angular/core';
import { NgpButton } from 'ng-primitives/button';
import { NgpMenu, NgpMenuItem, NgpMenuTrigger } from 'ng-primitives/menu';

@Component({
  selector: 'app-menu',
  imports: [NgpButton, NgpMenu, NgpMenuTrigger, NgpMenuItem],
  template: `
    <button [ngpMenuTrigger]="menu" ngpButton>Open Menu</button>

    <ng-template #menu>
      <div ngpMenu>
        <button ngpMenuItem>Item 1</button>
        <button ngpMenuItem>Item 2</button>
        <button ngpMenuItem>Item 3</button>
      </div>
    </ng-template>
  `,
  styles: `
    [ngpButton] {
      padding-left: 1rem;
      padding-right: 1rem;
      border-radius: 0.5rem;
      color: var(--ngp-text-primary);
      border: none;
      outline: none;
      height: 2.5rem;
      font-weight: 500;
      background-color: var(--ngp-background);
      transition: background-color 300ms cubic-bezier(0.4, 0, 0.2, 1);
      box-shadow: var(--ngp-button-shadow);
    }

    [ngpButton][data-hover] {
      background-color: var(--ngp-background-hover);
    }

    [ngpButton][data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
    }

    [ngpButton][data-press] {
      background-color: var(--ngp-background-active);
    }

    [ngpMenu] {
      position: fixed;
      display: flex;
      flex-direction: column;
      width: max-content;
      background: var(--ngp-background);
      border: 1px solid var(--ngp-border);
      box-shadow: var(--ngp-shadow-lg);
      border-radius: 8px;
      padding: 4px;
      transform-origin: var(--ngp-menu-transform-origin);
    }

    [ngpMenu][data-enter] {
      animation: menu-show 0.1s ease-out;
    }

    [ngpMenu][data-exit] {
      animation: menu-hide 0.1s ease-out;
    }

    [ngpMenu][data-enter] {
      animation: menu-show 0.1s ease-out;
    }

    [ngpMenu][data-exit] {
      animation: menu-hide 0.1s ease-out;
    }

    [ngpMenuItem] {
      padding: 6px 14px;
      border: none;
      background: none;
      cursor: pointer;
      transition: background-color 0.2s;
      border-radius: 4px;
      min-width: 120px;
      text-align: start;
      outline: none;
      font-size: 14px;
      font-weight: 400;
    }

    [ngpMenuItem][data-hover] {
      background-color: var(--ngp-background-hover);
    }

    [ngpMenuItem][data-press] {
      background-color: var(--ngp-background-active);
    }

    [ngpMenuItem][data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
      z-index: 1;
    }

    @keyframes menu-show {
      0% {
        opacity: 0;
        transform: scale(0.9);
      }
      100% {
        opacity: 1;
        transform: scale(1);
      }
    }

    @keyframes menu-hide {
      0% {
        opacity: 1;
        transform: scale(1);
      }
      100% {
        opacity: 0;
        transform: scale(0.9);
      }
    }
  `,
})
export default class MenuExample {}

```

## Import

Import the Menu primitives from `ng-primitives/menu`.

```ts
import { NgpMenu, NgpMenuItem, NgpMenuTrigger, NgpSubmenuTrigger } from 'ng-primitives/menu';
```

## Usage

Assemble the menu directives in your template.

```html
<button [ngpMenuTrigger]="menu" ngpButton></button>

<ng-template #menu>
  <div ngpMenu>
    <button ngpMenuItem>Item 1</button>
    <button ngpMenuItem>Item 2</button>
    <button ngpMenuItem>Item 3</button>
  </div>
</ng-template>
```

## Reusable Component

Create reusable components that use the `NgpMenu` directive.

## Reusable Component

```typescript
import { Component } from '@angular/core';
import { NgpMenu } from 'ng-primitives/menu';

@Component({
  selector: 'app-menu',
  hostDirectives: [NgpMenu],
  template: `
    <ng-content />
  `,
  styles: `
    :host {
      position: fixed;
      display: flex;
      flex-direction: column;
      width: max-content;
      background: var(--ngp-background);
      border: 1px solid var(--ngp-border);
      box-shadow: var(--ngp-shadow);
      border-radius: 8px;
      padding: 4px;
      animation: menu-show 300ms ease-out;
    }

    :host[data-exit] {
      animation: menu-hide 300ms ease-out;
    }

    @keyframes menu-show {
      0% {
        opacity: 0;
        transform: scale(0.9);
      }
      100% {
        opacity: 1;
        transform: scale(1);
      }
    }

    @keyframes menu-hide {
      0% {
        opacity: 1;
        transform: scale(1);
      }
      100% {
        opacity: 0;
        transform: scale(0.9);
      }
    }
  `,
})
export class Menu {}

```

## Schematics

Generate a reusable menu component using the Angular CLI.

```bash npm
ng g ng-primitives:primitive menu
```

### Options

- `path`: The path at which to create the component file.
- `prefix`: The prefix to apply to the generated component selector.
- `componentSuffix`: The suffix to apply to the generated component class name.
- `fileSuffix`: The suffix to apply to the generated component file name. Defaults to `component`.
- `exampleStyles`: Whether to include example styles in the generated component file. Defaults to `true`.

## Examples

Here are some additional examples of how to use the Menu primitives.

### Submenu

The menu can contain submenus, which are nested menus that can be opened by hovering on a menu item.

## Example

```typescript
import { Component } from '@angular/core';
import { NgIcon, provideIcons } from '@ng-icons/core';
import { heroChevronRightMini } from '@ng-icons/heroicons/mini';
import { NgpButton } from 'ng-primitives/button';
import { NgpMenu, NgpMenuItem, NgpMenuTrigger, NgpSubmenuTrigger } from 'ng-primitives/menu';

@Component({
  selector: 'app-menu-submenu',
  imports: [NgpButton, NgpMenu, NgpMenuTrigger, NgpMenuItem, NgpSubmenuTrigger, NgIcon],
  providers: [provideIcons({ heroChevronRightMini })],
  template: `
    <button [ngpMenuTrigger]="menu" ngpButton>Open Menu</button>

    <ng-template #menu>
      <div ngpMenu>
        <button ngpMenuItem>Item 1</button>
        <button ngpMenuItem>Item 2</button>
        <button [ngpSubmenuTrigger]="submenu" ngpMenuItem>
          Item 3
          <ng-icon name="heroChevronRightMini" />
        </button>
      </div>
    </ng-template>

    <ng-template #submenu>
      <div ngpMenu>
        <button ngpMenuItem>Item 1</button>
        <button ngpMenuItem>Item 2</button>
        <button ngpMenuItem>Item 3</button>
      </div>
    </ng-template>
  `,
  styles: `
    [ngpButton] {
      padding-left: 1rem;
      padding-right: 1rem;
      border-radius: 0.5rem;
      color: var(--ngp-text-primary);
      border: none;
      outline: none;
      height: 2.5rem;
      font-weight: 500;
      background-color: var(--ngp-background);
      transition: background-color 300ms cubic-bezier(0.4, 0, 0.2, 1);
      box-shadow: var(--ngp-button-shadow);
    }

    [ngpButton][data-hover] {
      background-color: var(--ngp-background-hover);
    }

    [ngpButton][data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
    }

    [ngpButton][data-press] {
      background-color: var(--ngp-background-active);
    }

    [ngpMenu] {
      position: fixed;
      display: flex;
      flex-direction: column;
      width: max-content;
      background: var(--ngp-background);
      border: 1px solid var(--ngp-border);
      box-shadow: var(--ngp-shadow-lg);
      border-radius: 8px;
      padding: 4px;
      animation: menu-show 0.2s ease-out;
      transform-origin: var(--ngp-popover-transform-origin);
    }

    [ngpMenu][data-exit] {
      animation: menu-hide 0.2s ease-out;
    }

    [ngpMenuItem] {
      display: flex;
      align-items: center;
      justify-content: space-between;
      padding: 6px 8px 6px 14px;
      border: none;
      background: none;
      cursor: pointer;
      transition: background-color 0.2s;
      border-radius: 4px;
      min-width: 120px;
      text-align: start;
      outline: none;
      font-size: 14px;
      font-weight: 400;
    }

    [ngpMenuItem][data-hover] {
      background-color: var(--ngp-background-hover);
    }

    [ngpMenuItem][data-press] {
      background-color: var(--ngp-background-active);
    }

    [ngpMenuItem][data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
      z-index: 1;
    }

    @keyframes menu-show {
      0% {
        opacity: 0;
        transform: scale(0.9);
      }
      100% {
        opacity: 1;
        transform: scale(1);
      }
    }

    @keyframes menu-hide {
      0% {
        opacity: 1;
        transform: scale(1);
      }
      100% {
        opacity: 0;
        transform: scale(0.9);
      }
    }
  `,
})
export default class MenuExample {}

```

### Custom Offset

You can customize the offset using either a simple number or an object for more precise control:

```html
<!-- Simple number offset -->
<button [ngpMenuTrigger]="menu" ngpMenuTriggerOffset="12">Menu with 12px offset</button>

<!-- Object offset for precise control -->
<button
  [ngpMenuTrigger]="menu"
  [ngpMenuTriggerOffset]="{mainAxis: 8, crossAxis: 4, alignmentAxis: 2}"
>
  Menu with custom offset
</button>
```

### Custom Shift

You can customize the shift behavior to control how the menu stays within the viewport:

```html
<!-- Disable shift -->
<button [ngpMenuTrigger]="menu" [ngpMenuTriggerShift]="false">Menu without shift</button>

<!-- Object shift for precise control -->
<button [ngpMenuTrigger]="menu" [ngpMenuTriggerShift]="{padding: 8}">
  Menu with custom shift padding
</button>
```

## API Reference

The following directives are available to import from the `ng-primitives/menu` package:

### NgpMenuTrigger

## API Reference

### NgpMenuTrigger

The `NgpMenuTrigger` directive allows you to turn an element into a menu trigger.

**Selector:** `[ngpMenuTrigger]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpMenuTrigger` | `NgpOverlayContent<T> | undefined` | `-` | Access the menu template ref or ComponentType. |
| `ngpMenuTriggerDisabled` | `boolean` | `false` | Define if the trigger should be disabled. |
| `ngpMenuTriggerPlacement` | `NgpMenuPlacement` | `'bottom-start'` | Define the placement of the menu relative to the trigger. |
| `ngpMenuTriggerOffset` | `NgpOffset` | `4` | Define the offset of the menu relative to the trigger.
Can be a number (applies to mainAxis) or an object with mainAxis, crossAxis, and alignmentAxis. |
| `ngpMenuTriggerFlip` | `boolean` | `true` | Define whether the menu should flip when there is not enough space for the menu. |
| `ngpMenuTriggerShift` | `NgpShift` | `undefined (enabled by default in overlay)` | Configure shift behavior to keep the menu in view.
Can be a boolean to enable/disable, or an object with padding and limiter options. |
| `ngpMenuTriggerContainer` | `string | HTMLElement | null` | `document.body` | Define the container in which the menu should be attached. |
| `ngpMenuTriggerScrollBehavior` | `"reposition" | "block"` | `'block'` | Defines how the menu behaves when the window is scrolled. |
| `ngpMenuTriggerContext` | `T | undefined` | `-` | Provide context to the menu. This can be used to pass data to the menu content. |

#### Export As

`ngpMenuTrigger`



#### Data Attributes

The following data attributes are available on the `NgpMenuTrigger` directive:

| Attribute   | Description                    |
| ----------- | ------------------------------ |
| `data-open` | Applied when the menu is open. |

### NgpMenu

## API Reference

### NgpMenu

The `NgpMenu` is a container for menu items.

**Selector:** `[ngpMenu]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpMenuWrap` | `boolean` | `true` | Whether focus should wrap around when reaching the end of the menu. |

#### Export As

`ngpMenu`



#### Data Attributes

The following data attributes are available on the `NgpMenu` directive:

| Attribute        | Description                                                                                  |
| ---------------- | -------------------------------------------------------------------------------------------- |
| `data-enter`     | Applied when the menu is being added to the DOM. This can be used to trigger animations.     |
| `data-exit`      | Applied when the menu is being removed from the DOM. This can be used to trigger animations. |
| `data-placement` | The final rendered placement of the menu.                                                    |

The following CSS custom properties are applied to the `ngpMenu` directive:

| Property                      | Description                                      |
| ----------------------------- | ------------------------------------------------ |
| `--ngp-menu-transform-origin` | The transform origin of the menu for animations. |
| `--ngp-menu-trigger-width`    | The width of the trigger element.                |

### NgpMenuItem

## API Reference

### NgpMenuItem

The `NgpMenuItem` directive represents a menu item.

**Selector:** `[ngpMenuItem]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpMenuItemDisabled` | `boolean` | `-` | Whether the menu item is disabled |

#### Export As

`ngpMenuItem`



#### Data Attributes

The following data attributes are available on the `NgpMenuItem` directive:

| Attribute       | Description                        |
| --------------- | ---------------------------------- |
| `data-disabled` | Applied when the item is disabled. |

### NgpSubmenuTrigger

## API Reference

### NgpSubmenuTrigger



**Selector:** `[ngpSubmenuTrigger]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpSubmenuTrigger` | `NgpOverlayContent<T> | undefined` | `-` | Access the submenu template ref. |
| `ngpSubmenuTriggerDisabled` | `boolean` | `false` | Define if the trigger should be disabled. |
| `ngpSubmenuTriggerPlacement` | `NgpMenuPlacement` | `'right-start'` | Define the placement of the menu relative to the trigger. |
| `ngpSubmenuTriggerOffset` | `NgpOffset` | `0` | Define the offset of the menu relative to the trigger.
Can be a number (applies to mainAxis) or an object with mainAxis, crossAxis, and alignmentAxis. |
| `ngpSubmenuTriggerFlip` | `boolean` | `true` | Define whether the menu should flip when there is not enough space for the menu. |

#### Export As

`ngpSubmenuTrigger`



#### Data Attributes

The following data attributes are available on the `NgpSubmenuTrigger` directive:

| Attribute   | Description                       |
| ----------- | --------------------------------- |
| `data-open` | Applied when the submenu is open. |

## Styling

For the menu to be positioned correctly relative to the trigger element, it should use fixed positioning. For example, you can use the following CSS:

```css
[ngpMenu] {
  position: fixed;
}
```

## Animations

The `ngpMenu` primitive adds a CSS custom property `--ngp-menu-transform-origin` to the element that can be used to animate the menu from the trigger element.

The `ngpMenu` will also add the `data-enter` and `data-exit` attributes to the element when it is being added or removed from the DOM. This can be used to trigger animations.

```css
:host[data-enter] {
  animation: fade-in 0.2s ease-in-out;
}

:host[data-exit] {
  animation: fade-out 0.2s ease-in-out;
}
```

## Global Configuration

You can configure the default options for all menus in your application by using the `provideMenuConfig` function in a providers array.

```ts
import { provideMenuConfig } from 'ng-primitives/menu';

bootstrapApplication(AppComponent, {
  providers: [
    provideMenuConfig({
      offset: 4,
      placement: 'top',
      flip: true,
      container: document.body,
      scrollBehavior: 'reposition',
    }),
  ],
});
```

### NgpMenuConfig

<prop-details name="offset" type="number | NgpOffsetOptions">
  Define the offset from the trigger element. Can be a number (applies to mainAxis) or an object with mainAxis, crossAxis, and alignmentAxis properties.
  
  **Number format:** `offset: 8` - Applies to mainAxis (distance from trigger)
  
  **Object format:** 
  ```ts
  offset: {
    mainAxis: 8,     // Distance between menu and trigger element
    crossAxis: 4,    // Skidding along the alignment axis  
    alignmentAxis: 2 // Same as crossAxis but for aligned placements
  }
  ```
</prop-details>

<prop-details name="shift" type="boolean | NgpShiftOptions" default="true">
  Define the shift behavior to keep the menu in view. When enabled (default), the menu will shift along its axis to stay visible when it would otherwise overflow the viewport. Set to `false` to disable.
  
  **Boolean format:** `shift: false` - Disables shift behavior
  
  **Object format:** 
  ```ts
  shift: {
    padding: 8,     // Minimum padding between menu and viewport edges
    limiter: {      // Optional limiter to control shifting behavior
      fn: limitShift,
      options: { /* limiter options */ }
    }
  }
  ```
</prop-details>

<prop-details name="placement" type="'top' | 'right' | 'bottom' | 'left'">
  Define the placement of the menu.
</prop-details>

<prop-details name="flip" type="boolean">
  Define if the menu should flip when it reaches the edge of the viewport.
</prop-details>

<prop-details name="container" type="HTMLElement">
  Define the container element for the menu. This is the document body by default.
</prop-details>

<prop-details name="scrollBehavior" type="reposition | block">
Defines how the menu behaves when the window is scrolled. If set to `reposition`, the menu will adjust its position automatically during scrolling. Make sure the menu uses `position: absolute` in this mode. If set to `block`, scrolling will be disabled while the menu is open. In this case, the menu should use `position: fixed`.
</prop-details>

## Accessibility

Adhere to the [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/) for menus and submenus.


---

### Meter

File: primitives/meter.md
URL: https://angularprimitives.com/primitives/meter

# Meter

A meter is a visual representation of a value within a range.

## Example

```typescript
import { Component, signal } from '@angular/core';
import {
  NgpMeter,
  NgpMeterIndicator,
  NgpMeterLabel,
  NgpMeterTrack,
  NgpMeterValue,
} from 'ng-primitives/meter';

@Component({
  selector: 'app-meter',
  imports: [NgpMeter, NgpMeterLabel, NgpMeterValue, NgpMeterIndicator, NgpMeterTrack],
  template: `
    <div [ngpMeterValue]="value()" ngpMeter>
      <span ngpMeterLabel>Label</span>
      <span ngpMeterValue>{{ value() }}%</span>

      <div ngpMeterTrack>
        <div ngpMeterIndicator></div>
      </div>
    </div>
  `,
  styles: `
    [ngpMeter] {
      display: grid;
      grid-template-columns: 1fr 1fr;
      grid-row-gap: 0.5rem;
      width: 200px;
      box-sizing: border-box;
      padding: 0.5rem;
    }

    [ngpMeterLabel] {
      color: var(--ngp-text-emphasis);
      font-size: 14px;
      font-weight: 600;
    }

    [ngpMeterValue] {
      color: var(--ngp-text-secondary);
      font-size: 14px;
      font-weight: 500;
      text-align: right;
      grid-column-start: 2;
      text-align: end;
    }

    [ngpMeterTrack] {
      grid-column: 1 / 3;
      overflow: hidden;
      background-color: var(--ngp-background);
      box-shadow: var(--ngp-shadow-border);
      border-radius: 4px;
      height: 8px;
    }

    [ngpMeterIndicator] {
      background-color: var(--ngp-background-success);
      height: 100%;
      transition: width 0.2s ease-in-out;
      inset-inline-start: 0px;
      border-radius: 4px;
    }
  `,
})
export default class MeterExample {
  /** The value of the meter. */
  value = signal(30);
}

```

## Import

Import the Meter primitives from `ng-primitives/meter`.

```ts
import {
  NgpMeter,
  NgpMeterValue,
  NgpMeterIndicator,
  NgpMeterTrack,
  NgpMeterLabel,
} from 'ng-primitives/meter';
```

## Usage

Assemble the meter directives in your template.

```html
<div ngpMeter>
  <span ngpMeterLabel>Label</span>
  <span ngpMeterValue>Value</span>
  <div ngpMeterTrack>
    <div ngpMeterIndicator></div>
  </div>
</div>
```

## Reusable Component

Create a reusable component that uses the `NgpMeter` directive.

## Reusable Component

```typescript
import { NumberInput } from '@angular/cdk/coercion';
import { Component, input, numberAttribute } from '@angular/core';
import {
  NgpMeter,
  NgpMeterIndicator,
  NgpMeterLabel,
  NgpMeterTrack,
  NgpMeterValue,
} from 'ng-primitives/meter';

@Component({
  selector: 'app-meter',
  hostDirectives: [
    { directive: NgpMeter, inputs: ['ngpMeterValue:value', 'ngpMeterMin:min', 'ngpMeterMax:max'] },
  ],
  imports: [NgpMeterIndicator, NgpMeterLabel, NgpMeterValue, NgpMeterTrack],
  template: `
    <span ngpMeterLabel>{{ label() }}</span>
    <span ngpMeterValue>{{ value() }}%</span>

    <div ngpMeterTrack>
      <div ngpMeterIndicator></div>
    </div>
  `,
  styles: `
    :host {
      display: grid;
      grid-template-columns: 1fr 1fr;
      grid-row-gap: 0.5rem;
      width: 200px;
      box-sizing: border-box;
      padding: 0.5rem;
    }

    [ngpMeterLabel] {
      color: var(--ngp-text-emphasis);
      font-size: 14px;
      font-weight: 600;
    }

    [ngpMeterValue] {
      color: var(--ngp-text-secondary);
      font-size: 14px;
      font-weight: 500;
      text-align: right;
      grid-column-start: 2;
      text-align: end;
    }

    [ngpMeterTrack] {
      grid-column: 1 / 3;
      overflow: hidden;
      background-color: var(--ngp-background);
      box-shadow: var(--ngp-shadow-border);
      border-radius: 4px;
      height: 8px;
    }

    [ngpMeterIndicator] {
      background-color: var(--ngp-background-success);
      height: 100%;
      transition: width 0.2s ease-in-out;
      inset-inline-start: 0px;
      border-radius: 4px;
    }
  `,
})
export class Meter {
  /** The value of the meter. */
  readonly value = input<number, NumberInput>(0, {
    transform: numberAttribute,
  });

  /** The label of the meter. */
  readonly label = input.required<string>();
}

```

## Schematics

Generate a reusable meter component using the Angular CLI.

```bash npm
ng g ng-primitives:primitive meter
```

### Options

- `path`: The path at which to create the component file.
- `prefix`: The prefix to apply to the generated component selector.
- `componentSuffix`: The suffix to apply to the generated component class name.
- `fileSuffix`: The suffix to apply to the generated component file name. Defaults to `component`.
- `exampleStyles`: Whether to include example styles in the generated component file. Defaults to `true`.

## API Reference

The following directives are available to import from the `ng-primitives/meter` package:

### NgpMeter

## API Reference

### NgpMeter



**Selector:** `[ngpMeter]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpMeterValue` | `number` | `-` | The value of the meter. |
| `ngpMeterMin` | `number` | `-` | The minimum value of the meter. |
| `ngpMeterMax` | `number` | `-` | The maximum value of the meter. |
| `ngpMeterValueLabel` | `NgpMeterValueTextFn` | `-` | Define a function that returns the meter value label. |

#### Export As

`ngpMeter`



### NgpMeterLabel

## API Reference

### NgpMeterLabel



**Selector:** `[ngpMeterLabel]`

#### Export As

`ngpMeterLabel`



### NgpMeterValue

## API Reference

### NgpMeterValue



**Selector:** `[ngpMeterValue]`

#### Export As

`ngpMeterValue`



### NgpMeterTrack

## API Reference

### NgpMeterTrack



**Selector:** `[ngpMeterTrack]`

#### Export As

`ngpMeterTrack`



### NgpMeterIndicator

## API Reference

### NgpMeterIndicator



**Selector:** `[ngpMeterIndicator]`

#### Export As

`ngpMeterIndicator`



## Accessibility

Adheres to the [Meter Accessibility](https://www.w3.org/WAI/ARIA/apg/patterns/meter/) guidelines.


---

### Pagination

File: primitives/pagination.md
URL: https://angularprimitives.com/primitives/pagination

# Pagination

The Pagination primitives provide a set of directives to create a pagination control. The pagination control is used to navigate through a set of data that is split into multiple pages.

## Example

```typescript
import { Component, signal } from '@angular/core';
import { NgIcon, provideIcons } from '@ng-icons/core';
import {
  heroChevronDoubleLeft,
  heroChevronDoubleRight,
  heroChevronLeft,
  heroChevronRight,
} from '@ng-icons/heroicons/outline';
import {
  NgpPagination,
  NgpPaginationButton,
  NgpPaginationFirst,
  NgpPaginationLast,
  NgpPaginationNext,
  NgpPaginationPrevious,
} from 'ng-primitives/pagination';

@Component({
  selector: 'app-pagination',
  imports: [
    NgIcon,
    NgpPagination,
    NgpPaginationButton,
    NgpPaginationFirst,
    NgpPaginationNext,
    NgpPaginationPrevious,
    NgpPaginationLast,
  ],
  providers: [
    provideIcons({
      heroChevronDoubleLeft,
      heroChevronDoubleRight,
      heroChevronLeft,
      heroChevronRight,
    }),
  ],
  template: `
    <nav
      [(ngpPaginationPage)]="page"
      ngpPagination
      ngpPaginationPageCount="5"
      aria-label="Pagination Navigation"
    >
      <ul>
        <li>
          <button ngpPaginationFirst aria-label="First Page">
            <ng-icon name="heroChevronDoubleLeft" />
          </button>
        </li>

        <li>
          <button ngpPaginationPrevious aria-label="Previous Page">
            <ng-icon name="heroChevronLeft" />
          </button>
        </li>

        <li>
          <button ngpPaginationButton ngpPaginationButtonPage="1" aria-label="Page 1">1</button>
        </li>
        <li>
          <button ngpPaginationButton ngpPaginationButtonPage="2" aria-label="Page 2">2</button>
        </li>
        <li>
          <button ngpPaginationButton ngpPaginationButtonPage="3" aria-label="Page 3">3</button>
        </li>
        <li>
          <button ngpPaginationButton ngpPaginationButtonPage="4" aria-label="Page 4">4</button>
        </li>
        <li>
          <button ngpPaginationButton ngpPaginationButtonPage="5" aria-label="Page 5">5</button>
        </li>

        <li>
          <button ngpPaginationNext aria-label="Next Page">
            <ng-icon name="heroChevronRight" />
          </button>
        </li>

        <li>
          <button ngpPaginationLast aria-label="Last Page">
            <ng-icon name="heroChevronDoubleRight" />
          </button>
        </li>
      </ul>
    </nav>
  `,
  styles: `
    :host {
      display: contents;
    }

    ul {
      display: flex;
      align-items: center;
      column-gap: 0.5rem;
    }

    [ngpPaginationFirst],
    [ngpPaginationPrevious],
    [ngpPaginationButton],
    [ngpPaginationNext],
    [ngpPaginationLast] {
      all: unset;
      display: flex;
      justify-content: center;
      align-items: center;
      width: 2rem;
      height: 2rem;
      border-radius: 0.5rem;
      color: var(--ngp-text-primary);
      outline: none;
      font-size: 14px;
      font-weight: 500;
      background-color: var(--ngp-background);
      box-shadow: var(--ngp-button-shadow);
      cursor: pointer;
      transition: background-color 0.2s;

      &[data-hover]:not([data-disabled]):not([data-selected]) {
        background-color: var(--ngp-background-hover);
      }

      &[data-focus-visible]:not([data-disabled]) {
        outline: 2px solid var(--ngp-focus-ring);
      }

      &[data-press]:not([data-disabled]):not([data-selected]) {
        background-color: var(--ngp-background-active);
      }

      &[data-disabled] {
        color: rgb(210 210 210);
        background-color: var(--ngp-background-disabled);
        cursor: not-allowed;
        box-shadow: none;
      }

      &[data-selected] {
        background-color: var(--ngp-background-inverse);
        color: var(--ngp-text-inverse);
      }
    }
  `,
})
export default class PaginationExample {
  /**
   * The currently selected page.
   */
  readonly page = signal<number>(1);
}

```

## Import

Import the Pagination primitives from `ng-primitives/pagination`.

```ts
import {
  NgpPagination,
  NgpPaginationButton,
  NgpPaginationFirst,
  NgpPaginationNext,
  NgpPaginationPrevious,
  NgpPaginationLast,
} from 'ng-primitives/pagination';
```

## Usage

Assemble the pagination directives in your template.

```html
<nav
  [(ngpPaginationPage)]="page"
  ngpPagination
  ngpPaginationPageCount="5"
  aria-label="Pagination Navigation"
>
  <ul>
    <li>
      <a ngpPaginationFirst aria-label="First Page">
        <ng-icon name="heroChevronDoubleLeft" />
      </a>
    </li>

    <li>
      <a ngpPaginationPrevious aria-label="Previous Page">
        <ng-icon name="heroChevronLeft" />
      </a>
    </li>

    <li>
      <a ngpPaginationButton ngpPaginationButtonPage="1" aria-label="Page 1">1</a>
    </li>
    <li>
      <a ngpPaginationButton ngpPaginationButtonPage="2" aria-label="Page 2">2</a>
    </li>
    <li>
      <a ngpPaginationButton ngpPaginationButtonPage="3" aria-label="Page 3">3</a>
    </li>
    <li>
      <a ngpPaginationButton ngpPaginationButtonPage="4" aria-label="Page 4">4</a>
    </li>
    <li>
      <a ngpPaginationButton ngpPaginationButtonPage="5" aria-label="Page 5">5</a>
    </li>

    <li>
      <a ngpPaginationNext aria-label="Next Page">
        <ng-icon name="heroChevronRight" />
      </a>
    </li>

    <li>
      <a ngpPaginationLast aria-label="Last Page">
        <ng-icon name="heroChevronDoubleRight" />
      </a>
    </li>
  </ul>
</nav>
```

## Reusable Component

Create a reusable component that uses the pagination directives.

## Reusable Component

```typescript
import { Component, computed } from '@angular/core';
import { ControlValueAccessor } from '@angular/forms';
import { NgIcon, provideIcons } from '@ng-icons/core';
import {
  heroChevronDoubleLeft,
  heroChevronDoubleRight,
  heroChevronLeft,
  heroChevronRight,
} from '@ng-icons/heroicons/outline';
import {
  injectPaginationState,
  NgpPagination,
  NgpPaginationButton,
  NgpPaginationFirst,
  NgpPaginationLast,
  NgpPaginationNext,
  NgpPaginationPrevious,
} from 'ng-primitives/pagination';
import { ChangeFn, provideValueAccessor, TouchedFn } from 'ng-primitives/utils';

@Component({
  selector: 'app-pagination',
  hostDirectives: [
    {
      directive: NgpPagination,
      inputs: [
        'ngpPaginationPage:page',
        'ngpPaginationPageCount:pageCount',
        'ngpPaginationDisabled:disabled',
      ],
      outputs: ['ngpPaginationPageChange:pageChange'],
    },
  ],
  imports: [
    NgpPaginationButton,
    NgpPaginationFirst,
    NgpPaginationLast,
    NgpPaginationNext,
    NgpPaginationPrevious,
    NgIcon,
  ],
  providers: [
    provideValueAccessor(NgpPagination),
    provideIcons({
      heroChevronDoubleLeft,
      heroChevronDoubleRight,
      heroChevronLeft,
      heroChevronRight,
    }),
  ],
  template: `
    <ul>
      <li>
        <button ngpPaginationFirst aria-label="First Page">
          <ng-icon name="heroChevronDoubleLeft" />
        </button>
      </li>

      <li>
        <button ngpPaginationPrevious aria-label="Previous Page">
          <ng-icon name="heroChevronLeft" />
        </button>
      </li>

      @for (page of pages(); track page) {
        <li>
          <button
            [ngpPaginationButtonPage]="page"
            [attr.aria-label]="'Page ' + page"
            ngpPaginationButton
          >
            {{ page }}
          </button>
        </li>
      }

      <li>
        <button ngpPaginationNext aria-label="Next Page">
          <ng-icon name="heroChevronRight" />
        </button>
      </li>

      <li>
        <button ngpPaginationLast aria-label="Last Page">
          <ng-icon name="heroChevronDoubleRight" />
        </button>
      </li>
    </ul>
  `,
  styles: `
    ul {
      display: flex;
      align-items: center;
      column-gap: 0.5rem;
      list-style: none;
    }

    [ngpPaginationFirst],
    [ngpPaginationPrevious],
    [ngpPaginationButton],
    [ngpPaginationNext],
    [ngpPaginationLast] {
      all: unset;
      display: flex;
      justify-content: center;
      align-items: center;
      width: 2rem;
      height: 2rem;
      border-radius: 0.5rem;
      color: var(--ngp-text-primary);
      outline: none;
      font-size: 14px;
      font-weight: 500;
      background-color: var(--ngp-background);
      box-shadow: var(--ngp-button-shadow);
      cursor: pointer;
      transition: background-color 0.2s;

      &[data-hover]:not([data-disabled]):not([data-selected]) {
        background-color: var(--ngp-background-hover);
      }

      &[data-focus-visible]:not([data-disabled]) {
        outline: 2px solid var(--ngp-focus-ring);
      }

      &[data-press]:not([data-disabled]):not([data-selected]) {
        background-color: var(--ngp-background-active);
      }

      &[data-disabled] {
        color: rgb(210 210 210);
        background-color: var(--ngp-background-disabled);
        cursor: not-allowed;
        box-shadow: none;
      }

      &[data-selected] {
        background-color: var(--ngp-background-inverse);
        color: var(--ngp-text-inverse);
      }
    }
  `,
  host: {
    '(focusout)': 'onTouched?.()',
  },
})
export class Pagination implements ControlValueAccessor {
  /** Access the pagination state */
  protected readonly state = injectPaginationState();

  /** Get the pages as an array we can iterate over */
  protected readonly pages = computed(() =>
    Array.from({ length: this.state().pageCount() }).map((_, i) => i + 1),
  );

  /** The onChange callback */
  private onChange?: ChangeFn<number>;

  /** The onTouched callback */
  protected onTouched?: TouchedFn;

  constructor() {
    this.state().pageChange.subscribe(value => this.onChange?.(value));
  }

  /** Write a new value to the control */
  writeValue(value: number): void {
    this.state().page.set(value);
  }

  /** Register a callback to be called when the value changes */
  registerOnChange(fn: ChangeFn<number>): void {
    this.onChange = fn;
  }

  /** Register a callback to be called when the control is touched */
  registerOnTouched(fn: TouchedFn): void {
    this.onTouched = fn;
  }
}

```

## Schematics

Generate a reusable pagination component using the Angular CLI.

```bash npm
ng g ng-primitives:primitive pagination
```

### Options

- `path`: The path at which to create the component file.
- `prefix`: The prefix to apply to the generated component selector.
- `componentSuffix`: The suffix to apply to the generated component class name.
- `fileSuffix`: The suffix to apply to the generated component file name. Defaults to `component`.
- `exampleStyles`: Whether to include example styles in the generated component file. Defaults to `true`.

## API Reference

The following directives are available to import from the `ng-primitives/pagination` package:

### NgpPagination

## API Reference

### NgpPagination

The `NgpPagination` directive is used to create a pagination control.

**Selector:** `[ngpPagination]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpPaginationPage` | `number` | `-` | The currently selected page. |
| `ngpPaginationPageCount` | `number` | `-` | The total number of pages. |
| `ngpPaginationDisabled` | `boolean` | `-` | Whether the pagination is disabled. |

#### Outputs

| Event | Type | Description |
|-------|------|-------------|
| `ngpPaginationPageChange` | `number` | The event that is fired when the page changes. |

#### Export As

`ngpPagination`



#### Data Attributes

The following data attributes are applied to the `ngpPagination` directive:

| Attribute         | Description                                 | Value     |
| ----------------- | ------------------------------------------- | --------- |
| `data-page`       | The current page number.                    | `number`  |
| `data-page-count` | The total number of pages.                  | `number`  |
| `data-disabled`   | Disables the pagination control.            | `boolean` |
| `data-first-page` | Whether the current page is the first page. | `boolean` |
| `data-last-page`  | Whether the current page is the last page.  | `boolean` |

### NgpPaginationButton

## API Reference

### NgpPaginationButton

The `NgpPaginationButton` directive is used to create a pagination button.

**Selector:** `[ngpPaginationButton]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpPaginationButtonPage` | `number` | `-` | Define the page this button represents. |
| `ngpPaginationButtonDisabled` | `boolean` | `-` | Whether the button is disabled. |

#### Export As

`ngpPaginationButton`



#### Data Attributes

The following data attributes are applied to the `ngpPaginationButton` directive:

| Attribute            | Description                                   | Value    |
| -------------------- | --------------------------------------------- | -------- |
| `data-page`          | The page number that the button navigates to. | `number` |
| `data-selected`      | Applied when the button is selected.          | `-`      |
| `data-hover`         | Applied when the button is hovered.           | `-`      |
| `data-focus-visible` | Applied when the button is focused.           | `-`      |
| `data-press`         | Applied when the button is pressed.           | `-`      |
| `data-disabled`      | Disables the pagination button.               | `-`      |

### NgpPaginationFirst

## API Reference

### NgpPaginationFirst

The `NgpPaginationFirst` directive is used to create a pagination button that navigates to the first page.

**Selector:** `[ngpPaginationFirst]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpPaginationFirstDisabled` | `boolean` | `-` | Whether the button is disabled. |

#### Export As

`ngpPaginationFirst`



#### Data Attributes

The following data attributes are applied to the `ngpPaginationFirst` directive:

| Attribute            | Description                                      |
| -------------------- | ------------------------------------------------ |
| `data-first-page`    | Applied when the current page is the first page. |
| `data-hover`         | Applied when the button is hovered.              |
| `data-focus-visible` | Applied when the button is focused.              |
| `data-press`         | Applied when the button is pressed.              |
| `data-disabled`      | Applied when the button is disabled.             |

### NgpPaginationPrevious

## API Reference

### NgpPaginationPrevious

The `NgpPaginationPrevious` directive is used to create a pagination button that navigates to the previous page.

**Selector:** `[ngpPaginationPrevious]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpPaginationPreviousDisabled` | `boolean` | `-` | Whether the button is disabled. |

#### Export As

`ngpPaginationPrevious`



#### Data Attributes

The following data attributes are applied to the `ngpPaginationPrevious` directive:

| Attribute            | Description                                      |
| -------------------- | ------------------------------------------------ |
| `data-first-page`    | Applied when the current page is the first page. |
| `data-hover`         | Applied when the button is hovered.              |
| `data-focus-visible` | Applied when the button is focused.              |
| `data-press`         | Applied when the button is pressed.              |
| `data-disabled`      | Applied when the button is disabled.             |

### NgpPaginationNext

## API Reference

### NgpPaginationNext

The `NgpPaginationNext` directive is used to create a pagination button that navigates to the next page.

**Selector:** `[ngpPaginationNext]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpPaginationNextDisabled` | `boolean` | `-` | Whether the button is disabled. |

#### Export As

`ngpPaginationNext`



#### Data Attributes

The following data attributes are applied to the `ngpPaginationNext` directive:

| Attribute            | Description                                     |
| -------------------- | ----------------------------------------------- |
| `data-last-page`     | Applied when the current page is the last page. |
| `data-hover`         | Applied when the button is hovered.             |
| `data-focus-visible` | Applied when the button is focused.             |
| `data-press`         | Applied when the button is pressed.             |
| `data-disabled`      | Applied when the button is disabled.            |

### NgpPaginationLast

## API Reference

### NgpPaginationLast

The `NgpPaginationLast` directive is used to create a pagination button that navigates to the last page.

**Selector:** `[ngpPaginationLast]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpPaginationLastDisabled` | `boolean` | `-` | Whether the button is disabled. |

#### Export As

`ngpPaginationLast`



#### Data Attributes

The following data attributes are applied to the `ngpPaginationLast` directive:

| Attribute            | Description                                     |
| -------------------- | ----------------------------------------------- |
| `data-last-page`     | Applied when the current page is the last page. |
| `data-hover`         | Applied when the button is hovered.             |
| `data-focus-visible` | Applied when the button is focused.             |
| `data-press`         | Applied when the button is pressed.             |
| `data-disabled`      | Applied when the button is disabled.            |


---

### Popover

File: primitives/popover.md
URL: https://angularprimitives.com/primitives/popover

# Popover

Display arbitrary content inside floating panels.

## Example

```typescript
import { Component } from '@angular/core';
import { NgpButton } from 'ng-primitives/button';
import { NgpPopover, NgpPopoverArrow, NgpPopoverTrigger } from 'ng-primitives/popover';

@Component({
  selector: 'app-popover',
  imports: [NgpPopoverTrigger, NgpPopover, NgpPopoverArrow, NgpButton],
  template: `
    <button [ngpPopoverTrigger]="popover" ngpButton type="button">Popover</button>

    <ng-template #popover>
      <div ngpPopover>
        <h3>Need Help?</h3>
        <p>
          Get quick tips and guidance on how to use this feature effectively. Check out our
          documentation for more details!
        </p>

        <a target="_blank" href="https://www.youtube.com/watch?v=xvFZjo5PgG0">Learn More</a>

        <div ngpPopoverArrow></div>
      </div>
    </ng-template>
  `,
  styles: `
    button {
      padding-left: 1rem;
      padding-right: 1rem;
      border-radius: 0.5rem;
      color: var(--ngp-text-primary);
      outline: none;
      height: 2.5rem;
      font-weight: 500;
      background-color: var(--ngp-background);
      transition: background-color 300ms cubic-bezier(0.4, 0, 0.2, 1);
      box-shadow: var(--ngp-button-shadow);
    }

    button[data-hover] {
      background-color: var(--ngp-background-hover);
    }

    button[data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
    }

    button[data-press] {
      background-color: var(--ngp-background-active);
    }

    [ngpPopover] {
      position: absolute;
      display: flex;
      flex-direction: column;
      row-gap: 4px;
      max-width: 280px;
      border-radius: 0.75rem;
      background: var(--ngp-background);
      padding: 0.75rem 1rem;
      box-shadow: var(--ngp-shadow);
      border: 1px solid var(--ngp-border);
      outline: none;
      animation: popover-show 0.1s ease-out;
      transform-origin: var(--ngp-popover-transform-origin);
    }

    [ngpPopover][data-exit] {
      animation: popover-hide 0.1s ease-out;
    }

    [ngpPopoverArrow] {
      position: absolute;
      pointer-events: none;
    }

    [ngpPopoverArrow][data-placement='top'] {
      bottom: 0;
    }

    [ngpPopoverArrow][data-placement='bottom'] {
      top: 0;
    }

    [ngpPopoverArrow]:before {
      content: '';
      display: block;
      position: absolute;
      left: 0;
      bottom: 100%;
      width: 0;
      height: 0;
      border: 6px solid transparent;
      border-bottom-color: var(--ngp-background-inverse);
    }

    [ngpPopoverArrow]:after {
      content: '';
      display: block;
      position: absolute;
      left: 0;
      bottom: 100%;
      width: 0;
      height: 0;
      border: 6px solid transparent;
      border-bottom-color: var(--ngp-background);
    }

    [ngpPopover] h3 {
      font-size: 13px;
      font-weight: 500;
      margin: 0;
      color: var(--ngp-text-primary);
    }

    [ngpPopover] p {
      font-size: 13px;
      margin: 0;
      color: var(--ngp-text-secondary);
    }

    [ngpPopover] a {
      font-size: 13px;
      color: var(--ngp-text-blue);
      text-decoration: none;
    }

    @keyframes popover-show {
      0% {
        opacity: 0;
        transform: scale(0.9);
      }
      100% {
        opacity: 1;
        transform: scale(1);
      }
    }

    @keyframes popover-hide {
      0% {
        opacity: 1;
        transform: scale(1);
      }
      100% {
        opacity: 0;
        transform: scale(0.9);
      }
    }
  `,
})
export default class PopoverExample {}

```

## Import

Import the Popover primitives from `ng-primitives/popover`.

```ts
import { NgpPopover, NgpPopoverTrigger, NgpPopoverArrow } from 'ng-primitives/popover';
```

## Usage

Assemble the popover directives in your template.

```html
<button [ngpPopoverTrigger]="popover" (ngpPopoverTriggerOpenChange)="onPopoverStateChange($event)">
  Click me
</button>

<ng-template #popover>
  <div ngpPopover>Popover content</div>
</ng-template>
```

You can listen to the `ngpPopoverTriggerOpenChange` event to perform actions when the popover state changes. The event emits a boolean value indicating whether the popover is open or closed:

## Examples

### Custom Offset

You can customize the offset using either a simple number or an object for more precise control:

```html
<!-- Simple number offset -->
<button [ngpPopoverTrigger]="popover" ngpPopoverTriggerOffset="12">Popover with 12px offset</button>

<!-- Object offset for precise control -->
<button
  [ngpPopoverTrigger]="popover"
  [ngpPopoverTriggerOffset]="{mainAxis: 8, crossAxis: 4, alignmentAxis: 2}"
>
  Popover with custom offset
</button>
```

### Custom Shift

You can customize the shift behavior to control how the popover stays within the viewport:

```html
<!-- Disable shift -->
<button [ngpPopoverTrigger]="popover" [ngpPopoverTriggerShift]="false">
  Popover without shift
</button>

<!-- Object shift for precise control -->
<button [ngpPopoverTrigger]="popover" [ngpPopoverTriggerShift]="{padding: 8}">
  Popover with custom shift padding
</button>
```

## Reusable Component

Create a popover component that uses the `NgpPopover` directive.

## Reusable Component

```typescript
import { Component } from '@angular/core';
import { injectPopoverContext, NgpPopover } from 'ng-primitives/popover';

@Component({
  selector: 'app-popover',
  hostDirectives: [NgpPopover],
  template: `
    {{ content() }}
  `,
  styles: `
    :host {
      position: absolute;
      max-width: 16rem;
      border-radius: 0.5rem;
      background-color: var(--ngp-background-inverse);
      padding: 0.5rem 0.75rem;
      border: none;
      font-size: 0.75rem;
      font-weight: 500;
      color: var(--ngp-text-inverse);
      transform-origin: var(--ngp-popover-transform-origin);
    }

    :host[data-enter] {
      animation: popover-show 200ms ease-in-out;
    }

    :host[data-exit] {
      animation: popover-hide 200ms ease-in-out;
    }

    @keyframes popover-show {
      0% {
        opacity: 0;
        transform: scale(0.5);
      }
      100% {
        opacity: 1;
        transform: scale(1);
      }
    }

    @keyframes popover-hide {
      0% {
        opacity: 1;
        transform: scale(1);
      }
      100% {
        opacity: 0;
        transform: scale(0.5);
      }
    }
  `,
})
export class Popover {
  readonly content = injectPopoverContext();
}

```

## Schematics

Generate a reusable tooltip component using the Angular CLI.

```bash npm
ng g ng-primitives:primitive popover
```

### Options

- `path`: The path at which to create the component file.
- `prefix`: The prefix to apply to the generated component selector.
- `componentSuffix`: The suffix to apply to the generated component class name.
- `fileSuffix`: The suffix to apply to the generated component file name. Defaults to `component`.
- `exampleStyles`: Whether to include example styles in the generated component file. Defaults to `true`

## Examples

### Popover with anchor

The popover can be anchored to a different element than the trigger.

## Example

```typescript
import { Component } from '@angular/core';
import { NgpButton } from 'ng-primitives/button';
import { NgpInput } from 'ng-primitives/input';
import { NgpPopover, NgpPopoverArrow, NgpPopoverTrigger } from 'ng-primitives/popover';

@Component({
  selector: 'app-popover-anchor',
  imports: [NgpPopoverTrigger, NgpPopover, NgpPopoverArrow, NgpButton, NgpInput],
  template: `
    <div class="input-group">
      <input #emailInput ngpInput type="email" placeholder="Enter your email address" />
      <button
        class="help-button"
        [ngpPopoverTrigger]="popover"
        [ngpPopoverTriggerAnchor]="emailInput"
        ngpPopoverTriggerPlacement="bottom"
        ngpButton
        type="button"
        aria-label="Email format help"
      >
        ?
      </button>
    </div>

    <ng-template #popover>
      <div ngpPopover>
        <h3>Email Format</h3>
        <p>Please enter a valid email address in the format: name&#64;domain.com</p>
        <p>
          Examples:
          <br />
          • john.doe&#64;company.com
          <br />
          • user123&#64;example.org
          <br />
          • contact&#64;website.co.uk
        </p>

        <div ngpPopoverArrow></div>
      </div>
    </ng-template>
  `,
  styles: `
    :host {
      display: contents;
    }

    .input-group {
      display: flex;
      align-items: center;
      gap: 8px;
      width: 100%;
    }

    [ngpInput] {
      height: 36px;
      flex: 1;
      border-radius: 8px;
      padding: 0 16px;
      border: none;
      box-shadow: var(--ngp-input-shadow);
      outline: none;
    }

    [ngpInput]:focus {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 2px;
    }

    [ngpInput]::placeholder {
      color: var(--ngp-text-placeholder);
    }

    .help-button {
      width: 36px;
      height: 36px;
      padding: 0;
      border-radius: 50%;
      color: var(--ngp-text-primary);
      outline: none;
      font-weight: 500;
      background-color: var(--ngp-background);
      transition: background-color 300ms cubic-bezier(0.4, 0, 0.2, 1);
      box-shadow: var(--ngp-button-shadow);
      display: flex;
      align-items: center;
      justify-content: center;
      font-size: 14px;
    }

    .help-button[data-hover] {
      background-color: var(--ngp-background-hover);
    }

    .help-button[data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
    }

    .help-button[data-press] {
      background-color: var(--ngp-background-active);
    }

    [ngpPopover] {
      position: absolute;
      display: flex;
      flex-direction: column;
      row-gap: 4px;
      max-width: 280px;
      border-radius: 0.75rem;
      background: var(--ngp-background);
      padding: 0.75rem 1rem;
      box-shadow: var(--ngp-shadow);
      border: 1px solid var(--ngp-border);
      outline: none;
      animation: popover-show 0.1s ease-out;
      transform-origin: var(--ngp-popover-transform-origin);
    }

    [ngpPopover][data-exit] {
      animation: popover-hide 0.1s ease-out;
    }

    [ngpPopoverArrow] {
      position: absolute;
      pointer-events: none;
    }

    [ngpPopoverArrow][data-placement='top'] {
      bottom: 0;
    }

    [ngpPopoverArrow][data-placement='bottom'] {
      top: 0;
    }

    [ngpPopoverArrow]:before {
      content: '';
      display: block;
      position: absolute;
      left: 0;
      bottom: 100%;
      width: 0;
      height: 0;
      border: 6px solid transparent;
      border-bottom-color: var(--ngp-background-inverse);
    }

    [ngpPopoverArrow]:after {
      content: '';
      display: block;
      position: absolute;
      left: 0;
      bottom: 100%;
      width: 0;
      height: 0;
      border: 6px solid transparent;
      border-bottom-color: var(--ngp-background);
    }

    [ngpPopover] h3 {
      font-size: 13px;
      font-weight: 500;
      margin: 0;
      color: var(--ngp-text-primary);
    }

    [ngpPopover] p {
      font-size: 13px;
      margin: 0;
      color: var(--ngp-text-secondary);
    }

    @keyframes popover-show {
      0% {
        opacity: 0;
        transform: scale(0.9);
      }
      100% {
        opacity: 1;
        transform: scale(1);
      }
    }

    @keyframes popover-hide {
      0% {
        opacity: 1;
        transform: scale(1);
      }
      100% {
        opacity: 0;
        transform: scale(0.9);
      }
    }
  `,
})
export default class PopoverAnchorExample {}

```

## API Reference

The following directives are available to import from the `ng-primitives/popover` package:

### NgpPopover

## API Reference

### NgpPopover

Apply the `ngpPopover` directive to an element that represents the popover. This typically would be a `div` inside an `ng-template`.

**Selector:** `[ngpPopover]`

#### Export As

`ngpPopover`



#### Data Attributes

| Attribute        | Description                                                                                     |
| ---------------- | ----------------------------------------------------------------------------------------------- |
| `data-enter`     | Applied when the popover is being added to the DOM. This can be used to trigger animations.     |
| `data-exit`      | Applied when the popover is being removed from the DOM. This can be used to trigger animations. |
| `data-placement` | The final rendered placement of the popover.                                                    |

The following CSS custom properties are applied to the `ngpPopover` directive:

| Property                         | Description                                         |
| -------------------------------- | --------------------------------------------------- |
| `--ngp-popover-transform-origin` | The transform origin of the popover for animations. |
| `--ngp-popover-trigger-width`    | The width of the trigger element.                   |

### NgpPopoverTrigger

## API Reference

### NgpPopoverTrigger

Apply the `ngpPopoverTrigger` directive to an element that triggers the popover to show.

**Selector:** `[ngpPopoverTrigger]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpPopoverTrigger` | `NgpOverlayContent<T> | undefined` | `-` | Access the popover template ref. |
| `ngpPopoverTriggerDisabled` | `boolean` | `false` | Define if the trigger should be disabled. |
| `ngpPopoverTriggerPlacement` | `NgpPopoverPlacement` | `'top'` | Define the placement of the popover relative to the trigger. |
| `ngpPopoverTriggerOffset` | `NgpOffset` | `0` | Define the offset of the popover relative to the trigger.
Can be a number (applies to mainAxis) or an object with mainAxis, crossAxis, and alignmentAxis. |
| `ngpPopoverTriggerShowDelay` | `number` | `0` | Define the delay before the popover is displayed. |
| `ngpPopoverTriggerHideDelay` | `number` | `0` | Define the delay before the popover is hidden. |
| `ngpPopoverTriggerFlip` | `boolean` | `true` | Define whether the popover should flip when there is not enough space for the popover. |
| `ngpPopoverTriggerShift` | `NgpShift` | `undefined (enabled by default in overlay)` | Configure shift behavior to keep the popover in view.
Can be a boolean to enable/disable, or an object with padding and limiter options. |
| `ngpPopoverTriggerContainer` | `string | HTMLElement | null` | `document.body` | Define the container in which the popover should be attached. |
| `ngpPopoverTriggerCloseOnOutsideClick` | `boolean` | `true` | Define whether the popover should close when clicking outside of it. |
| `ngpPopoverTriggerCloseOnEscape` | `boolean` | `true` | Define whether the popover should close when the escape key is pressed. |
| `ngpPopoverTriggerScrollBehavior` | `"reposition" | "block"` | `'reposition'` | Defines how the popover behaves when the window is scrolled. |
| `ngpPopoverTriggerContext` | `T | undefined` | `-` | Provide context to the popover. This can be used to pass data to the popover content. |
| `ngpPopoverTriggerAnchor` | `HTMLElement | null` | `-` | Define an anchor element for positioning the popover.
If provided, the popover will be positioned relative to this element instead of the trigger. |
| `ngpPopoverTriggerTrackPosition` | `boolean` | `false` | Define whether to track the trigger element position on every animation frame.
Useful for moving elements like slider thumbs. |

#### Outputs

| Event | Type | Description |
|-------|------|-------------|
| `ngpPopoverTriggerOpenChange` | `boolean` | Event emitted when the popover open state changes. |

#### Export As

`ngpPopoverTrigger`



#### Data Attributes

| Attribute       | Description                           |
| --------------- | ------------------------------------- |
| `data-open`     | Applied when the popover is open.     |
| `data-disabled` | Applied when the popover is disabled. |

### NgpPopoverArrow

The `NgpPopoverArrow` directive is used to add an arrow to the popover. It should be placed inside the popover content. It will receive `inset-inline-start` or `inset-block-start` styles to position the arrow based on the popover's placement. As a result it should be positioned absolutely within the popover content.

The arrow can be styled conditionally based on the popover's final placement using the `data-placement` attribute:

```css
[ngpPopoverArrow][data-placement='top'] {
  /* Arrow styles when popover is positioned on top */
}

[ngpPopoverArrow][data-placement='bottom'] {
  /* Arrow styles when popover is positioned on bottom */
}
```

## API Reference

### NgpPopoverArrow



**Selector:** `[ngpPopoverArrow]`

#### Export As

`ngpPopoverArrow`



### Data Attributes

| Attribute        | Description                                  |
| ---------------- | -------------------------------------------- |
| `data-placement` | The final rendered placement of the popover. |

## Styling

For the popover to be positioned correctly relative to the trigger element, it must use absolute or fixed positioning. For example, you can use the following CSS:

```css
[ngpPopover] {
  position: absolute;
}
```

## Animations

The `ngpPopover` primitive adds a CSS custom property `--ngp-popover-transform-origin` to the element that can be used to animate the popover from the trigger element.

The `ngpPopover` will also add the `data-enter` and `data-exit` attributes to the element when it is being added or removed from the DOM. This can be used to trigger animations.

```css
:host[data-enter] {
  animation: fade-in 0.2s ease-in-out;
}

:host[data-exit] {
  animation: fade-out 0.2s ease-in-out;
}
```

## Global Configuration

You can configure the default options for all popovers in your application by using the `providePopoverConfig` function in a providers array.

```ts
import { providePopoverConfig } from 'ng-primitives/popover';

bootstrapApplication(AppComponent, {
  providers: [
    providePopoverConfig({
      offset: 4,
      placement: 'top',
      showDelay: 0,
      hideDelay: 0,
      flip: true,
      container: document.body,
      closeOnOutsideClick: true,
      scrollBehavior: 'reposition',
    }),
  ],
});
```

### NgpPopoverConfig

<prop-details name="offset" type="number | NgpOffsetOptions">
  Define the offset from the trigger element. Can be a number (applies to mainAxis) or an object with mainAxis, crossAxis, and alignmentAxis properties.
  
  **Number format:** `offset: 8` - Applies to mainAxis (distance from trigger)
  
  **Object format:** 
  ```ts
  offset: {
    mainAxis: 8,     // Distance between popover and trigger element
    crossAxis: 4,    // Skidding along the alignment axis  
    alignmentAxis: 2 // Same as crossAxis but for aligned placements
  }
  ```
</prop-details>

<prop-details name="shift" type="boolean | NgpShiftOptions" default="true">
  Define the shift behavior to keep the popover in view. When enabled (default), the popover will shift along its axis to stay visible when it would otherwise overflow the viewport. Set to `false` to disable.
  
  **Boolean format:** `shift: false` - Disables shift behavior
  
  **Object format:** 
  ```ts
  shift: {
    padding: 8,     // Minimum padding between popover and viewport edges
    limiter: {      // Optional limiter to control shifting behavior
      fn: limitShift,
      options: { /* limiter options */ }
    }
  }
  ```
</prop-details>

<prop-details name="placement" type="'top' | 'right' | 'bottom' | 'left'">
  Define the placement of the popover.
</prop-details>

<prop-details name="showDelay" type="number">
  Define the delay before the popover shows.
</prop-details>

<prop-details name="hideDelay" type="number">
  Define the delay before the popover hides.
</prop-details>

<prop-details name="flip" type="boolean">
  Define if the popover should flip when it reaches the edge of the viewport.
</prop-details>

<prop-details name="container" type="HTMLElement">
  Define the container element for the popover. This is the document body by default.
</prop-details>

<prop-details name="closeOnOutsideClick" type="boolean">
  Define whether the popover should close when clicking outside of it.
</prop-details>

<prop-details name="scrollBehavior" type="reposition | block">
Defines how the popover behaves when the window is scrolled. If set to `reposition`, the popover will adjust its position automatically during scrolling. Make sure the popover uses `position: absolute` in this mode. If set to `block`, scrolling will be disabled while the popover is open. In this case, the popover should use `position: fixed`.
</prop-details>


---

### Progress

File: primitives/progress.md
URL: https://angularprimitives.com/primitives/progress

# Progress

Display an indicator representing the progress of a task.

## Example

```typescript
import { Component, signal } from '@angular/core';
import {
  NgpProgress,
  NgpProgressIndicator,
  NgpProgressLabel,
  NgpProgressTrack,
  NgpProgressValue,
} from 'ng-primitives/progress';
import { injectDisposables } from 'ng-primitives/utils';

@Component({
  selector: 'app-progress',
  imports: [
    NgpProgress,
    NgpProgressIndicator,
    NgpProgressTrack,
    NgpProgressLabel,
    NgpProgressValue,
  ],
  styles: `
    [ngpProgress] {
      display: grid;
      grid-template-columns: 1fr 1fr;
      grid-row-gap: 0.5rem;
      width: 200px;
      box-sizing: border-box;
      padding: 0.5rem;
    }

    [ngpProgressLabel] {
      color: var(--ngp-text-emphasis);
      font-size: 14px;
      font-weight: 600;
    }

    [ngpProgressValue] {
      color: var(--ngp-text-secondary);
      font-size: 14px;
      font-weight: 500;
      text-align: right;
      grid-column-start: 2;
      text-align: end;
    }

    [ngpProgressTrack] {
      grid-column: 1 / 3;
      position: relative;
      height: 12px;
      width: 100%;
      max-width: 320px;
      overflow: hidden;
      border-radius: 0.5rem;
      border: 1px solid var(--ngp-border);
      background-color: var(--ngp-background);
    }

    [ngpProgressIndicator] {
      height: 100%;
      border-radius: 0.5rem;
      background-color: var(--ngp-background-inverse);
      transition: width 150ms cubic-bezier(0.4, 0, 0.2, 1);
    }
  `,
  template: `
    <div [ngpProgressValue]="value()" ngpProgress>
      <label ngpProgressLabel>Loading</label>
      <span ngpProgressValue>{{ value() }}%</span>

      <div ngpProgressTrack>
        <div ngpProgressIndicator></div>
      </div>
    </div>
  `,
})
export default class ProgressExample {
  /**
   * The value of the progress bar.
   */
  readonly value = signal(0);

  /**
   * Use the disposable helpers to ensure the interval is cleared when the component is destroyed.
   */
  readonly disposables = injectDisposables();

  constructor() {
    this.disposables.setInterval(
      () => this.value.update(value => (value > 100 ? 0 : value + 1)),
      50,
    );
  }
}

```

## Import

Import the Progress primitives from `ng-primitives/progress`.

```ts
import {
  NgpProgress,
  NgpProgressTrack,
  NgpProgressLabel,
  NgpProgressValue,
  NgpProgressIndicator,
} from 'ng-primitives/progress';
```

## Usage

Assemble the avatar directives in your template.

```html
<div ngpProgress [ngpProgressValue]="percentage">
  <label ngpProgressLabel></label>
  <span ngpProgressValue></span>

  <div ngpProgressTrack>
    <div ngpProgressIndicator></div>
  </div>
</div>
```

## Reusable Component

Create a reusable component that uses the progress directives.

## Reusable Component

```typescript
import { NumberInput } from '@angular/cdk/coercion';
import { Component, input, numberAttribute } from '@angular/core';
import {
  NgpProgress,
  NgpProgressIndicator,
  NgpProgressLabel,
  NgpProgressTrack,
  NgpProgressValue,
} from 'ng-primitives/progress';

@Component({
  selector: 'app-progress',
  hostDirectives: [
    {
      directive: NgpProgress,
      inputs: ['ngpProgressValue:value', 'ngpProgressMax:max', 'ngpProgressValueLabel:valueLabel'],
    },
  ],
  imports: [NgpProgressIndicator, NgpProgressTrack, NgpProgressLabel, NgpProgressValue],
  template: `
    <label ngpProgressLabel>{{ label() }}</label>
    <span ngpProgressValue>{{ value() }}%</span>

    <div ngpProgressTrack>
      <div ngpProgressIndicator></div>
    </div>
  `,
  styles: `
    :host {
      display: grid;
      grid-template-columns: 1fr 1fr;
      grid-row-gap: 0.5rem;
      width: 200px;
      box-sizing: border-box;
      padding: 0.5rem;
    }

    [ngpProgressLabel] {
      color: var(--ngp-text-emphasis);
      font-size: 14px;
      font-weight: 600;
    }

    [ngpProgressValue] {
      color: var(--ngp-text-secondary);
      font-size: 14px;
      font-weight: 500;
      text-align: right;
      grid-column-start: 2;
      text-align: end;
    }

    [ngpProgressTrack] {
      grid-column: 1 / 3;
      position: relative;
      height: 12px;
      width: 100%;
      max-width: 320px;
      overflow: hidden;
      border-radius: 0.5rem;
      border: 1px solid var(--ngp-border);
      background-color: var(--ngp-background);
    }

    [ngpProgressIndicator] {
      height: 100%;
      border-radius: 0.5rem;
      background-color: var(--ngp-background-inverse);
      transition: width 150ms cubic-bezier(0.4, 0, 0.2, 1);
    }
  `,
})
export class Progress {
  /** The value of the progress. */
  readonly value = input<number, NumberInput>(0, {
    transform: numberAttribute,
  });

  /** The label of the progress. */
  readonly label = input.required<string>();
}

```

## Schematics

Generate a reusable progress component using the Angular CLI.

```bash npm
ng g ng-primitives:primitive progress
```

### Options

- `path`: The path at which to create the component file.
- `prefix`: The prefix to apply to the generated component selector.
- `componentSuffix`: The suffix to apply to the generated component class name.
- `fileSuffix`: The suffix to apply to the generated component file name. Defaults to `component`.
- `exampleStyles`: Whether to include example styles in the generated component file. Defaults to `true`.

## API Reference

The following directives are available to import from the `ng-primitives/progress` package:

### NgpProgress

## API Reference

### NgpProgress

Apply the `ngpProgress` directive to an element that represents the progress bar.

**Selector:** `[ngpProgress]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpProgressValue` | `number | null` | `-` | Define the progress value. |
| `ngpProgressMin` | `number` | `'0'` | Define the progress min value. |
| `ngpProgressMax` | `number` | `100` | Define the progress max value. |
| `ngpProgressValueLabel` | `NgpProgressValueTextFn` | `-` | Define a function that returns the progress value label. |



#### Data Attributes

The following data attributes are applied to the `ngpProgress` directive:

| Attribute            | Description                                   |
| -------------------- | --------------------------------------------- |
| `data-progressing`   | Indicates that the progress is in progress.   |
| `data-indeterminate` | Indicates that the progress is indeterminate. |
| `data-complete`      | Indicates that the progress is complete.      |

### NgpProgressIndicator

## API Reference

### NgpProgressIndicator

Apply the `ngpProgressIndicator` directive to an element that represents the current progress.
The width of this element can be set to the percentage of the progress value.

**Selector:** `[ngpProgressIndicator]`



#### Data Attributes

The following data attributes are applied to the `ngpProgress` directive:

| Attribute            | Description                                   |
| -------------------- | --------------------------------------------- |
| `data-progressing`   | Indicates that the progress is in progress.   |
| `data-indeterminate` | Indicates that the progress is indeterminate. |
| `data-complete`      | Indicates that the progress is complete.      |

### NgpProgressTrack

## API Reference

### NgpProgressTrack



**Selector:** `[ngpProgressTrack]`

#### Export As

`ngpProgressTrack`



#### Data Attributes

The following data attributes are applied to the `ngpProgressTrack` directive:

| Attribute            | Description                                   |
| -------------------- | --------------------------------------------- |
| `data-progressing`   | Indicates that the progress is in progress.   |
| `data-indeterminate` | Indicates that the progress is indeterminate. |
| `data-complete`      | Indicates that the progress is complete.      |

### NgpProgressLabel

## API Reference

### NgpProgressLabel



**Selector:** `[ngpProgressLabel]`

#### Export As

`ngpProgressLabel`



#### Data Attributes

The following data attributes are applied to the `ngpProgressLabel` directive:

| Attribute            | Description                                   |
| -------------------- | --------------------------------------------- |
| `data-progressing`   | Indicates that the progress is in progress.   |
| `data-indeterminate` | Indicates that the progress is indeterminate. |
| `data-complete`      | Indicates that the progress is complete.      |

### NgpProgressValue

## API Reference

### NgpProgressValue



**Selector:** `[ngpProgressValue]`

#### Export As

`ngpProgressValue`



#### Data Attributes

The following data attributes are applied to the `ngpProgressValue` directive:

| Attribute            | Description                                   |
| -------------------- | --------------------------------------------- |
| `data-progressing`   | Indicates that the progress is in progress.   |
| `data-indeterminate` | Indicates that the progress is indeterminate. |
| `data-complete`      | Indicates that the progress is complete.      |

## Accessibility

Adheres to the [WAI-ARIA Progressbar](https://www.w3.org/WAI/ARIA/apg/patterns/progressbar/) pattern.


---

### Radio

File: primitives/radio.md
URL: https://angularprimitives.com/primitives/radio

# Radio

Selection within a group.

## Example

```typescript
import { Component, signal } from '@angular/core';
import { NgpRadioGroup, NgpRadioIndicator, NgpRadioItem } from 'ng-primitives/radio';

@Component({
  selector: 'app-radio',
  imports: [NgpRadioGroup, NgpRadioItem, NgpRadioIndicator],
  styles: `
    [ngpRadioGroup] {
      display: flex;
      flex-direction: column;
      row-gap: 1rem;
    }

    [ngpRadioItem] {
      display: grid;
      cursor: pointer;
      grid-template-columns: auto 1fr;
      grid-template-rows: repeat(2, auto);
      column-gap: 0.625rem;
      row-gap: 0.125rem;
      border-radius: 0.5rem;
      background-color: var(--ngp-background);
      padding: 0.75rem 1rem;
      box-shadow: var(--ngp-button-shadow);
      outline: none;
    }

    [ngpRadioItem][data-hover] {
      background-color: var(--ngp-background-hover);
    }

    [ngpRadioItem][data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 2px;
    }

    [ngpRadioItem][data-press] {
      background-color: var(--ngp-background-active);
    }

    [ngpRadioItem][data-checked] {
      background-color: var(--ngp-background-inverse);
    }

    [ngpRadioIndicator] {
      display: inline-flex;
      grid-column-start: 1;
      grid-row-start: 1;
      justify-content: center;
      align-items: center;
      align-self: center;
      border-radius: 9999px;
      width: 1rem;
      height: 1rem;
      border: 1px solid var(--ngp-border);
    }

    .indicator-dot {
      width: 0.5rem;
      height: 0.5rem;
      border-radius: 9999px;
      background-color: transparent;
    }

    [ngpRadioItem][data-checked] .indicator-dot {
      background-color: var(--ngp-background);
    }

    .title {
      grid-column-start: 2;
      grid-row-start: 1;
      font-weight: 500;
      color: var(--ngp-text-primary);
      margin: 0;
    }

    [ngpRadioItem][data-checked] .title {
      color: var(--ngp-text-inverse);
    }

    .description {
      grid-column-start: 2;
      grid-row-start: 2;
      font-size: 0.75rem;
      color: var(--ngp-text-secondary);
      line-height: 1rem;
      margin: 0;
    }

    [ngpRadioItem][data-checked] .description {
      color: var(--ngp-text-inverse);
    }
  `,
  template: `
    <div [(ngpRadioGroupValue)]="plan" ngpRadioGroup ngpRadioGroupOrientation="vertical">
      <div ngpRadioItem ngpRadioItemValue="indie">
        <div ngpRadioIndicator>
          <span class="indicator-dot"></span>
        </div>

        <p class="title">Indie Plan</p>
        <p class="description">For those who want to are just starting out</p>
      </div>

      <div ngpRadioItem ngpRadioItemValue="growth">
        <div ngpRadioIndicator>
          <span class="indicator-dot"></span>
        </div>

        <p class="title">Growth Plan</p>
        <p class="description">For those who want to grow their business</p>
      </div>

      <div ngpRadioItem ngpRadioItemValue="unicorn">
        <div ngpRadioIndicator>
          <span class="indicator-dot"></span>
        </div>

        <p class="title">Unicorn Plan</p>
        <p class="description">For those who are going to the moon</p>
      </div>
    </div>
  `,
})
export default class RadioExample {
  /**
   * Store the selected plan.
   */
  readonly plan = signal<Plan>('indie');
}

type Plan = 'indie' | 'growth' | 'unicorn';

```

## Import

Import the Radio primitives from `ng-primitives/radio`.

```ts
import { NgpRadioGroup, NgpRadioItem, NgpRadioIndicator } from 'ng-primitives/radio';
```

## Usage

Assemble the radio directives in your template.

```html
<div ngpRadioGroup [(ngpRadioGroupValue)]="value">
  <button ngpRadioItem ngpRadioItemValue="Option 1">
    <ng-icon ngpRadioIndicator name="dot" />
    Option 1
  </button>

  <button ngpRadioItem ngpRadioItemValue="Option 2">
    <ng-icon ngpRadioIndicator name="dot" />
    Option 2
  </button>

  <button ngpRadioItem ngpRadioItemValue="Option 3">
    <ng-icon ngpRadioIndicator name="dot" />
    Option 3
  </button>
</div>
```

## Reusable Component

Create a reusable component that uses the radio directives.

_Snippet "radio" not found_

## Schematics

Generate a reusable radio component using the Angular CLI.

```bash npm
ng g ng-primitives:primitive radio
```

### Options

- `path`: The path at which to create the component file.
- `prefix`: The prefix to apply to the generated component selector.
- `componentSuffix`: The suffix to apply to the generated component class name.
- `fileSuffix`: The suffix to apply to the generated component file name. Defaults to `component`.
- `exampleStyles`: Whether to include example styles in the generated component file. Defaults to `true`.

## API Reference

The following directives are available to import from the `ng-primitives/radio` package:

### NgpRadioGroup

## API Reference

### NgpRadioGroup

Apply the `ngpRadioGroup` directive to an element that represents the group of radio items.

**Selector:** `[ngpRadioGroup]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpRadioGroupValue` | `T | null` | `-` | The value of the radio group. |
| `ngpRadioGroupDisabled` | `boolean` | `-` | Whether the radio group is disabled. |
| `ngpRadioGroupOrientation` | `NgpOrientation` | `'horizontal'` | The orientation of the radio group. |
| `ngpRadioGroupCompareWith` | `(a: T | null, b: T | null) => boolean` | `(a, b) => a === b` | The comparator function for the radio group. This is useful if values are objects and you want to compare them by value, not by reference. |

#### Outputs

| Event | Type | Description |
|-------|------|-------------|
| `ngpRadioGroupValueChange` | `T | null` | Event emitted when the radio group value changes. |



#### Data Attributes

The following data attributes are applied to the `ngpRadioGroup` directive:

| Attribute          | Description                               | Value                      |
| ------------------ | ----------------------------------------- | -------------------------- |
| `data-orientation` | The orientation of the radio group.       | `vertical` \| `horizontal` |
| `data-disabled`    | Applied when the radio group is disabled. | `-`                        |

### NgpRadioItem

## API Reference

### NgpRadioItem

Apply the `ngpRadioItem` directive to an element that represents a radio item. This would typically be a `button` element.

**Selector:** `[ngpRadioItem]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpRadioItemValue` | `T | undefined` | `-` | The value of the radio item. |
| `ngpRadioItemDisabled` | `boolean` | `false` | Whether the radio item is disabled. |



#### Data Attributes

The following data attributes are applied to the `ngpRadioItem` directive:

| Attribute            | Description                              |
| -------------------- | ---------------------------------------- |
| `data-checked`       | Applied when the radio item is checked.  |
| `data-disabled`      | Applied when the radio item is disabled. |
| `data-hover`         | Applied when the radio item is hovered.  |
| `data-focus-visible` | Applied when the radio item is focused.  |
| `data-press`         | Applied when the radio item is pressed.  |

### NgpRadioIndicator

## API Reference

### NgpRadioIndicator

Apply the `ngpRadioIndicator` directive to an element that represents the radio indicator (i.e. the dot).

**Selector:** `[ngpRadioIndicator]`



#### Data Attributes

The following data attributes are applied to the `ngpRadioItem` directive:

| Attribute       | Description                              |
| --------------- | ---------------------------------------- |
| `data-checked`  | Applied when the radio item is checked.  |
| `data-disabled` | Applied when the radio item is disabled. |
| `data-hover`    | Applied when the radio item is hovered.  |
| `data-press`    | Applied when the radio item is pressed.  |

## Accessibility

Adheres to the [Radio Group WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/radio).

### Keyboard Interaction

- <kbd>Tab</kbd> - Moves focus to the first radio button.
- <kbd>Arrow Down</kbd> - Moves focus to the next radio button (vertical orientation).
- <kbd>Arrow Up</kbd> - Moves focus to the previous radio button (vertical orientation).
- <kbd>Arrow Right</kbd> - Moves focus to the next radio button (horizontal orientation).
- <kbd>Arrow Left</kbd> - Moves focus to the previous radio button (horizontal orientation).
- <kbd>Space</kbd> - Selects the focused radio button if not already selected.


---

### Range Slider

File: primitives/range-slider.md
URL: https://angularprimitives.com/primitives/range-slider

# Range Slider

Select a range of values within a defined range.

## Example

```typescript
import { Component, signal } from '@angular/core';
import {
  NgpRangeSlider,
  NgpRangeSliderRange,
  NgpRangeSliderThumb,
  NgpRangeSliderTrack,
} from 'ng-primitives/slider';

@Component({
  selector: 'app-range-slider',
  imports: [NgpRangeSlider, NgpRangeSliderRange, NgpRangeSliderThumb, NgpRangeSliderTrack],
  styles: `
    [ngpRangeSlider] {
      display: flex;
      position: relative;
      width: 200px;
      height: 20px;
      touch-action: none;
      user-select: none;
      align-items: center;
    }

    [ngpRangeSliderTrack] {
      position: relative;
      height: 5px;
      width: 100%;
      border-radius: 999px;
      background-color: var(--ngp-background-secondary);
    }

    /* Increase the click area of the track without changing its visual size */
    [ngpRangeSliderTrack]::before {
      content: '';
      position: absolute;
      top: 50%;
      left: 0;
      right: 0;
      height: 20px;
      transform: translateY(-50%);
    }

    [ngpRangeSliderRange] {
      position: absolute;
      height: 100%;
      border-radius: 999px;
      background-color: var(--ngp-background-inverse);
    }

    [ngpRangeSliderThumb] {
      position: absolute;
      display: block;
      height: 20px;
      width: 20px;
      border-radius: 10px;
      background-color: white;
      box-shadow: var(--ngp-button-shadow);
      outline: none;
      transform: translateX(-50%);
      z-index: 1;
    }

    [ngpRangeSliderThumb][data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 0;
    }

    [ngpRangeSliderThumb][data-thumb='high'] {
      z-index: 2;
    }
  `,
  template: `
    <div
      [ngpRangeSliderLow]="low()"
      [ngpRangeSliderHigh]="high()"
      (ngpRangeSliderLowChange)="low.set($event)"
      (ngpRangeSliderHighChange)="high.set($event)"
      ngpRangeSlider
    >
      <div ngpRangeSliderTrack>
        <div ngpRangeSliderRange></div>
      </div>
      <div ngpRangeSliderThumb></div>
      <div ngpRangeSliderThumb></div>
    </div>
  `,
})
export default class RangeSliderExample {
  low = signal(25);
  high = signal(75);
}

```

## Import

Import the Range Slider primitives from `ng-primitives/slider`.

```ts
import {
  NgpRangeSlider,
  NgpRangeSliderTrack,
  NgpRangeSliderRange,
  NgpRangeSliderThumb,
} from 'ng-primitives/slider';
```

## Usage

Assemble the range slider directives in your template.

```html
<div ngpRangeSlider>
  <div ngpRangeSliderTrack>
    <div ngpRangeSliderRange></div>
  </div>
  <div ngpRangeSliderThumb></div>
  <div ngpRangeSliderThumb></div>
</div>
```

## Examples

Here are some additional examples of how to use the Range Slider primitives.

### Vertical Range Slider

Display the range slider in a vertical orientation by setting `ngpRangeSliderOrientation="vertical"`.

## Example

```typescript
import { Component, signal } from '@angular/core';
import {
  NgpRangeSlider,
  NgpRangeSliderRange,
  NgpRangeSliderThumb,
  NgpRangeSliderTrack,
} from 'ng-primitives/slider';

@Component({
  selector: 'app-range-slider-vertical',
  imports: [NgpRangeSlider, NgpRangeSliderRange, NgpRangeSliderThumb, NgpRangeSliderTrack],
  styles: `
    [ngpRangeSlider] {
      display: flex;
      position: relative;
      width: 20px;
      height: 200px;
      touch-action: none;
      user-select: none;
      justify-content: center;
    }

    [ngpRangeSliderTrack] {
      position: relative;
      width: 5px;
      height: 100%;
      border-radius: 999px;
      background-color: var(--ngp-background-secondary);
    }

    /* Increase the click area of the track without changing its visual size */
    [ngpRangeSliderTrack]::before {
      content: '';
      position: absolute;
      left: 50%;
      top: 0;
      bottom: 0;
      width: 20px;
      transform: translateX(-50%);
    }

    [ngpRangeSliderRange] {
      position: absolute;
      width: 100%;
      border-radius: 999px;
      background-color: var(--ngp-background-inverse);
    }

    [ngpRangeSliderThumb] {
      position: absolute;
      display: block;
      height: 20px;
      width: 20px;
      border-radius: 10px;
      background-color: white;
      box-shadow: var(--ngp-button-shadow);
      outline: none;
      transform: translateY(-50%);
      z-index: 1;
    }

    [ngpRangeSliderThumb][data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 0;
    }

    [ngpRangeSliderThumb][data-thumb='high'] {
      z-index: 2;
    }
  `,
  template: `
    <div
      [ngpRangeSliderLow]="low()"
      [ngpRangeSliderHigh]="high()"
      (ngpRangeSliderLowChange)="low.set($event)"
      (ngpRangeSliderHighChange)="high.set($event)"
      ngpRangeSlider
      ngpRangeSliderOrientation="vertical"
    >
      <div ngpRangeSliderTrack>
        <div ngpRangeSliderRange></div>
      </div>
      <div ngpRangeSliderThumb></div>
      <div ngpRangeSliderThumb></div>
    </div>
  `,
})
export default class RangeSliderVerticalExample {
  low = signal(25);
  high = signal(75);
}

```

## API Reference

The following directives are available to import from the `ng-primitives/slider` package:

### NgpRangeSlider

## API Reference

### NgpRangeSlider

Apply the `ngpRangeSlider` directive to an element that represents the range slider and contains the track, range, and thumbs.

**Selector:** `[ngpRangeSlider]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpRangeSliderLow` | `number` | `-` | The low value of the range slider. |
| `ngpRangeSliderHigh` | `number` | `-` | The high value of the range slider. |
| `ngpRangeSliderMin` | `number` | `-` | The minimum value of the range slider. |
| `ngpRangeSliderMax` | `number` | `-` | The maximum value of the range slider. |
| `ngpRangeSliderStep` | `number` | `-` | The step value of the range slider. |
| `ngpRangeSliderOrientation` | `NgpOrientation` | `-` | The orientation of the range slider. |
| `ngpRangeSliderDisabled` | `boolean` | `-` | The disabled state of the range slider. |

#### Outputs

| Event | Type | Description |
|-------|------|-------------|
| `ngpRangeSliderLowChange` | `number` | Emits when the low value changes. |
| `ngpRangeSliderHighChange` | `number` | Emits when the high value changes. |

#### Export As

`ngpRangeSlider`



#### Data Attributes

The following data attributes are available to style the range slider:

| Attribute          | Description                                | Value                      |
| ------------------ | ------------------------------------------ | -------------------------- |
| `data-disabled`    | Applied when the range slider is disabled. | `-`                        |
| `data-orientation` | The orientation of the range slider.       | `horizontal` \| `vertical` |

### NgpRangeSliderTrack

## API Reference

### NgpRangeSliderTrack

Apply the `ngpRangeSliderTrack` directive to an element that represents the track of the range slider.

**Selector:** `[ngpRangeSliderTrack]`

#### Export As

`ngpRangeSliderTrack`



#### Data Attributes

The following data attributes are available to style the slider track:

| Attribute          | Description                                | Value                      |
| ------------------ | ------------------------------------------ | -------------------------- |
| `data-disabled`    | Applied when the range slider is disabled. | `-`                        |
| `data-orientation` | The orientation of the range slider.       | `horizontal` \| `vertical` |

### NgpRangeSliderRange

## API Reference

### NgpRangeSliderRange

Apply the `ngpRangeSliderRange` directive to an element that represents the range between the low and high values.

**Selector:** `[ngpRangeSliderRange]`

#### Export As

`ngpRangeSliderRange`



#### Data Attributes

The following data attributes are available to style the slider range:

| Attribute          | Description                                | Value                      |
| ------------------ | ------------------------------------------ | -------------------------- |
| `data-disabled`    | Applied when the range slider is disabled. | `-`                        |
| `data-orientation` | The orientation of the range slider.       | `horizontal` \| `vertical` |

### NgpRangeSliderThumb

## API Reference

### NgpRangeSliderThumb

Apply the `ngpRangeSliderThumb` directive to an element that represents a thumb of the range slider.
Each thumb can be configured to control either the 'low' or 'high' value.

**Selector:** `[ngpRangeSliderThumb]`

#### Outputs

| Event | Type | Description |
|-------|------|-------------|
| `ngpRangeSliderThumbDragStart` | `void` | Emits when the thumb drag starts. |
| `ngpRangeSliderThumbDragEnd` | `void` | Emits when the thumb drag ends. |

#### Export As

`ngpRangeSliderThumb`



#### Data Attributes

The following data attributes are available to style the thumb:

| Attribute            | Description                                | Value                      |
| -------------------- | ------------------------------------------ | -------------------------- |
| `data-orientation`   | The orientation of the range slider.       | `horizontal` \| `vertical` |
| `data-disabled`      | Applied when the range slider is disabled. | `-`                        |
| `data-hover`         | Applied when the slider thumb is hovered.  | `-`                        |
| `data-focus-visible` | Applied when the slider thumb is focused.  | `-`                        |
| `data-press`         | Applied when the slider thumb is pressed.  | `-`                        |
| `data-thumb`         | Indicates which value this thumb controls. | `low` \| `high`            |

## Accessibility

Adheres to the [Multi-Thumb Slider WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/slider-multithumb).

### Keyboard Interactions

Each thumb can be focused and controlled independently:

- <kbd>Left Arrow</kbd> or <kbd>Down Arrow</kbd>: Decrease the value by the step.
- <kbd>Right Arrow</kbd> or <kbd>Up Arrow</kbd>: Increase the value by the step.
- <kbd>Left Arrow</kbd> or <kbd>Down Arrow</kbd> + <kbd>Shift</kbd>: Decrease the value by the step by a larger amount.
- <kbd>Right Arrow</kbd> or <kbd>Up Arrow</kbd> + <kbd>Shift</kbd>: Increase the value by the step by a larger amount.
- <kbd>Home</kbd>: Set the value to the minimum.
- <kbd>End</kbd>: Set the value to the maximum.

### Mouse Interactions

- Clicking on the track moves the closest thumb to that position.
- Dragging a thumb updates its corresponding value while respecting the boundaries (low ≤ high).


---

### Resize

File: primitives/resize.md
URL: https://angularprimitives.com/primitives/resize

# Resize

Perform actions on element resize.

## Example

```typescript
import { Component, signal } from '@angular/core';
import { Dimensions, NgpResize } from 'ng-primitives/resize';

@Component({
  selector: 'app-resize',
  imports: [NgpResize],
  styles: `
    div {
      display: flex;
      height: 7rem;
      max-height: 200px;
      min-width: 7rem;
      resize: both;
      align-items: center;
      justify-content: center;
      overflow: hidden;
      border-radius: 0.25rem;
      border: 1px dashed var(--ngp-background-inverse);
      padding: 1rem;
    }
  `,
  template: `
    <div (ngpResize)="dimensions.set($event)">
      {{ dimensions().width }} x {{ dimensions().height }}
    </div>
  `,
})
export default class ResizeExample {
  /**
   * Store the current size of the element.
   */
  readonly dimensions = signal<Dimensions>({ width: 0, height: 0 });
}

```

## Import

Import the Resize primitive from `ng-primitives/resize`.

```ts
import { NgpResize } from 'ng-primitives/resize';
```

## Usage

Assemble the resize directives in your template.

```html
<div (ngpResize)="onResize($event)"></div>
```

## API Reference

The following directives are available to import from the `ng-primitives/resize` package:

### NgpResize

## API Reference

### NgpResize

Apply the `ngpResize` directive to an element to listen for resize events.

**Selector:** `[ngpResize]`

#### Outputs

| Event | Type | Description |
|-------|------|-------------|
| `ngpResize` | `Dimensions` | Emits when the element is resized. |




---

### Roving Focus

File: primitives/roving-focus.md
URL: https://angularprimitives.com/primitives/roving-focus

# Roving Focus

Handle focus for a group of elements.

## Example

```typescript
import { Component } from '@angular/core';
import { NgIcon, provideIcons } from '@ng-icons/core';
import {
  heroBars3,
  heroBars3BottomLeft,
  heroBars3BottomRight,
  heroCog6Tooth,
  heroDocument,
  heroFolder,
} from '@ng-icons/heroicons/outline';
import { NgpButton } from 'ng-primitives/button';
import { NgpRovingFocusGroup, NgpRovingFocusItem } from 'ng-primitives/roving-focus';
import { NgpSeparator } from 'ng-primitives/separator';

@Component({
  selector: 'app-roving-focus',
  imports: [NgpRovingFocusGroup, NgpRovingFocusItem, NgIcon, NgpButton, NgpSeparator],
  providers: [
    provideIcons({
      heroDocument,
      heroFolder,
      heroBars3BottomLeft,
      heroBars3,
      heroBars3BottomRight,
      heroCog6Tooth,
    }),
  ],
  styles: `
    [ngpRovingFocusGroup] {
      display: flex;
      column-gap: 0.25rem;
      align-items: center;
      border-radius: 0.375rem;
      background-color: var(--ngp-background);
      box-shadow: var(--ngp-button-shadow);
      padding: 0.25rem;
    }

    [ngpButton] {
      display: flex;
      width: 2rem;
      height: 2rem;
      align-items: center;
      justify-content: center;
      border-radius: 0.25rem;
      border: 1px solid transparent;
      background: transparent;
      outline: none;
      transition: background-color 150ms cubic-bezier(0.4, 0, 0.2, 1);
      box-sizing: border-box;
    }

    [ngpButton][data-hover] {
      background-color: var(--ngp-background-hover);
      border-color: var(--ngp-border);
    }

    [ngpButton][data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
    }

    [ngpButton][data-press] {
      background-color: var(--ngp-background-active);
    }

    ng-icon {
      font-size: 1.125rem;
      color: var(--ngp-text-primary);
    }

    .divider {
      width: 1px;
      height: 1.5rem;
      background-color: var(--ngp-border);
      margin: 0 0.25rem;
    }
  `,
  template: `
    <div
      ngpRovingFocusGroup
      ngpRovingFocusGroupOrientation="horizontal"
      ngpRovingFocusGroupWrap="true"
      ngpRovingFocusGroupHomeEnd="true"
    >
      <button type="button" ngpButton ngpRovingFocusItem>
        <ng-icon name="heroDocument" />
      </button>
      <button type="button" ngpButton ngpRovingFocusItem>
        <ng-icon name="heroFolder" />
      </button>

      <div class="divider" ngpSeparator></div>

      <button type="button" ngpButton ngpRovingFocusItem>
        <ng-icon name="heroBars3BottomLeft" />
      </button>

      <button type="button" ngpButton ngpRovingFocusItem>
        <ng-icon name="heroBars3" />
      </button>

      <button type="button" ngpButton ngpRovingFocusItem>
        <ng-icon name="heroBars3BottomRight" />
      </button>

      <div class="divider" ngpSeparator></div>

      <button type="button" ngpButton ngpRovingFocusItem>
        <ng-icon name="heroCog6Tooth" />
      </button>
    </div>
  `,
})
export default class RovingFocusExample {}

```

## Import

Import the Roving Focus primitives from `ng-primitives/roving-focus`.

```ts
import { NgpRovingFocusGroup, NgpRovingFocusItem } from 'ng-primitives/roving-focus';
```

## Usage

Assemble the roving focus directives in your template.

```html
<div ngpRovingFocusGroup>
  <button ngpRovingFocusItem>Item 1</button>
  <button ngpRovingFocusItem>Item 2</button>
  <button ngpRovingFocusItem>Item 3</button>
</div>
```

## API Reference

The following directives are available to import from the `ng-primitives/roving-focus` package:

### NgpRovingFocusGroup

## API Reference

### NgpRovingFocusGroup

Apply the `ngpRovingFocusGroup` directive to an element to manage focus for a group of child elements.

**Selector:** `[ngpRovingFocusGroup]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpRovingFocusGroupOrientation` | `NgpOrientation` | `'vertical'` | Determine the orientation of the roving focus group. |
| `ngpRovingFocusGroupWrap` | `boolean` | `-` | Determine if focus should wrap when the end or beginning is reached. |
| `ngpRovingFocusGroupHomeEnd` | `boolean` | `-` | Determine if the home and end keys should navigate to the first and last items. |
| `ngpRovingFocusGroupDisabled` | `boolean` | `-` | Determine if the roving focus group is disabled. |

#### Export As

`ngpRovingFocusGroup`



### NgpRovingFocusItem

## API Reference

### NgpRovingFocusItem

Apply the `ngpRovingFocusItem` directive to an element within a roving focus group to automatically manage focus.

**Selector:** `[ngpRovingFocusItem]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpRovingFocusItemDisabled` | `boolean` | `-` | Define if the item is disabled. |

#### Export As

`ngpRovingFocusItem`



## Accessibility

Adheres to the [WAI-ARIA Keyboard Interface Practices](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/).

### Keyboard Interactions

- <kbd>Tab</kbd> - Move focus to the first item.
- <kbd>ArrowLeft</kbd> - Move focus to the previous item (horizontal orientation).
- <kbd>ArrowUp</kbd> - Move focus to the previous item (vertical orientation).
- <kbd>ArrowRight</kbd> - Move focus to the next item (horizontal orientation).
- <kbd>ArrowDown</kbd> - Move focus to the next item (vertical orientation).
- <kbd>Home</kbd> - Move focus to the first item.
- <kbd>End</kbd> - Move focus to the last item.


---

### Search

File: primitives/search.md
URL: https://angularprimitives.com/primitives/search

# Search

The search primitive is a form control that allows users to enter a search query and clear the input.

## Example

```typescript
import { Component, signal } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { NgIcon, provideIcons } from '@ng-icons/core';
import { heroMagnifyingGlass } from '@ng-icons/heroicons/outline';
import { NgpButton } from 'ng-primitives/button';
import { NgpFormField, NgpLabel } from 'ng-primitives/form-field';
import { NgpInput } from 'ng-primitives/input';
import { NgpSearch, NgpSearchClear } from 'ng-primitives/search';

@Component({
  selector: 'app-search',
  imports: [
    NgpSearch,
    NgpLabel,
    NgpInput,
    NgIcon,
    NgpButton,
    NgpSearchClear,
    FormsModule,
    NgpFormField,
  ],
  providers: [provideIcons({ heroMagnifyingGlass })],
  template: `
    <div ngpFormField>
      <label ngpLabel>Find a customer</label>
      <div ngpSearch>
        <ng-icon name="heroMagnifyingGlass" />
        <input [(ngModel)]="query" ngpInput type="search" placeholder="Search for a customer" />
        <button ngpSearchClear ngpButton aria-label="Clear search">Clear</button>
      </div>
    </div>
  `,
  styles: `
    :host {
      display: contents;
    }

    [ngpFormField] {
      display: flex;
      flex-direction: column;
      gap: 6px;
      width: 90%;
    }

    [ngpInput] {
      height: 36px;
      width: 100%;
      border-radius: 8px;
      padding: 0 16px 0 40px;
      border: none;
      background: var(--ngp-background);
      box-shadow: var(--ngp-input-shadow);
      outline: none;
    }

    /* clears the 'X' from Chrome */
    [ngpInput]::-webkit-search-decoration,
    [ngpInput]::-webkit-search-cancel-button,
    [ngpInput]::-webkit-search-results-button,
    [ngpInput]::-webkit-search-results-decoration {
      display: none;
    }

    [ngpInput][data-focus] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 0px;
    }

    [ngpInput]::placeholder {
      color: var(--ngp-text-placeholder);
    }

    [ngpLabel] {
      color: var(--ngp-text-primary);
      font-size: 0.875rem;
      line-height: 1.25rem;
      font-weight: 500;
      margin: 0;
    }

    [ngpSearch] {
      position: relative;
    }

    [ngpButton] {
      position: absolute;
      top: 0;
      right: 0;
      height: 36px;
      padding: 0 16px;
      border: none;
      border-radius: 0 8px 8px 0;
      background-color: transparent;
      color: var(--ngp-text-blue);
      font-size: 0.875rem;
      line-height: 1.25rem;
      cursor: pointer;
      outline: none;
      display: none;
    }

    [ngpButton]:not([data-empty]) {
      display: block;
    }

    ng-icon {
      position: absolute;
      font-size: 1.25rem;
      top: 18px;
      left: 12px;
      transform: translateY(-50%);
      color: var(--ngp-text-tertiary);
    }
  `,
})
export default class SearchExample {
  /**
   * Store the search query.
   */
  readonly query = signal<string>('');
}

```

## Import

Import the Search primitives from `ng-primitives/search`.

```ts
import { NgpSearch, NgpSearchClear } from 'ng-primitives/search';
```

## Usage

Assemble the search directives in your template.

```html
<div ngpFormField>
  <label ngpLabel>Label</label>
  <div ngpSearch>
    <input ngpInput type="search" />
    <button ngpSearchClear ngpButton aria-label="Clear search">Clear</button>
  </div>
</div>
```

## Reusable Component

Create a search component that uses the `NgpSearch` directive.

## Reusable Component

```typescript
import { Component, input, model } from '@angular/core';
import { ControlValueAccessor } from '@angular/forms';
import { NgIcon, provideIcons } from '@ng-icons/core';
import { heroMagnifyingGlass } from '@ng-icons/heroicons/outline';
import { NgpButton } from 'ng-primitives/button';
import { NgpInput } from 'ng-primitives/input';
import { NgpSearch, NgpSearchClear } from 'ng-primitives/search';
import { ChangeFn, provideValueAccessor, TouchedFn } from 'ng-primitives/utils';

@Component({
  selector: 'app-search',
  hostDirectives: [NgpSearch],
  imports: [NgIcon, NgpSearchClear, NgpInput, NgpButton],
  providers: [provideValueAccessor(Search), provideIcons({ heroMagnifyingGlass })],
  template: `
    <ng-icon name="heroMagnifyingGlass" />
    <input
      [value]="query()"
      [placeholder]="placeholder()"
      (input)="onQueryChange($event)"
      ngpInput
      type="search"
    />
    <button ngpSearchClear ngpButton aria-label="Clear search">Clear</button>
  `,
  styles: `
    :host {
      display: block;
      position: relative;
    }

    [ngpInput] {
      height: 36px;
      width: 100%;
      border-radius: 8px;
      padding: 0 16px 0 40px;
      border: none;
      background: var(--ngp-background);
      box-shadow: var(--ngp-input-shadow);
      outline: none;
    }

    /* clears the 'X' from Chrome */
    [ngpInput]::-webkit-search-decoration,
    [ngpInput]::-webkit-search-cancel-button,
    [ngpInput]::-webkit-search-results-button,
    [ngpInput]::-webkit-search-results-decoration {
      display: none;
    }

    [ngpInput][data-focus] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 0px;
    }

    [ngpInput]::placeholder {
      color: var(--ngp-text-placeholder);
    }

    [ngpButton] {
      position: absolute;
      top: 0;
      right: 0;
      height: 36px;
      padding: 0 16px;
      border: none;
      border-radius: 0 8px 8px 0;
      background-color: transparent;
      color: var(--ngp-text-blue);
      font-size: 0.875rem;
      line-height: 1.25rem;
      cursor: pointer;
      outline: none;
      display: none;
    }

    [ngpButton]:not([data-empty]) {
      display: block;
    }

    ng-icon {
      position: absolute;
      font-size: 1.25rem;
      top: 18px;
      left: 12px;
      transform: translateY(-50%);
      color: var(--ngp-text-tertiary);
    }
  `,
  host: {
    '(focusout)': 'onTouched?.()',
  },
})
export class Search implements ControlValueAccessor {
  /** The search query */
  readonly query = model<string>('');

  /** The placeholder text */
  readonly placeholder = input<string>('');

  /** The function to call when the value changes */
  private onChange?: ChangeFn<string>;

  /** The function to call when the control is touched */
  protected onTouched?: TouchedFn;

  writeValue(value: string): void {
    this.query.set(value);
  }

  registerOnChange(fn: ChangeFn<string>): void {
    this.onChange = fn;
  }

  registerOnTouched(fn: TouchedFn): void {
    this.onTouched = fn;
  }

  protected onQueryChange(event: Event): void {
    const input = event.target as HTMLInputElement;
    this.query.set(input.value);
    this.onChange?.(input.value);
  }
}

```

## Schematics

Generate a reusable search component using the Angular CLI.

```bash npm
ng g ng-primitives:primitive search
```

### Options

- `path`: The path at which to create the component file.
- `prefix`: The prefix to apply to the generated component selector.
- `componentSuffix`: The suffix to apply to the generated component class name.
- `fileSuffix`: The suffix to apply to the generated component file name. Defaults to `component`.
- `exampleStyles`: Whether to include example styles in the generated component file. Defaults to `true`.

## API Reference

The following directives are available to import from the `ng-primitives/search` package:

### NgpSearch

## API Reference

### NgpSearch

The `NgpSearch` directive is a container for the search field components.

**Selector:** `[ngpSearch]`

#### Export As

`ngpSearch`



#### Data Attributes

| Attribute    | Description                      |
| ------------ | -------------------------------- |
| `data-empty` | Applied when the input is empty. |

### NgpSearchClear

## API Reference

### NgpSearchClear

The `NgpSearchClear` directive is can be added to a button to clear the search field on click.

**Selector:** `[ngpSearchClear]`

#### Export As

`ngpSearchClear`



| Attribute    | Description                             |
| ------------ | --------------------------------------- |
| `data-empty` | Applied when the search field is empty. |

## Accessibility

Adheres to the [Search WAI-ARIA design pattern](https://www.w3.org/TR/wai-aria-1.2/#searchbox).

### Keyboard Interaction

- <kbd>Esc</kbd> - Clears the search field.


---

### Select

File: primitives/select.md
URL: https://angularprimitives.com/primitives/select

# Select

A select is a form control that allows users to select options from a list.

## Example

```typescript
import { Component, signal } from '@angular/core';
import { NgIcon, provideIcons } from '@ng-icons/core';
import { heroChevronDown } from '@ng-icons/heroicons/outline';
import {
  NgpSelect,
  NgpSelectDropdown,
  NgpSelectOption,
  NgpSelectPortal,
} from 'ng-primitives/select';

@Component({
  selector: 'app-select',
  imports: [NgpSelect, NgpSelectDropdown, NgpSelectOption, NgpSelectPortal, NgIcon],
  providers: [provideIcons({ heroChevronDown })],
  template: `
    <div [(ngpSelectValue)]="value" ngpSelect>
      @if (value(); as value) {
        <span class="select-value">{{ value }}</span>
      } @else {
        <span class="select-placeholder">Select an option</span>
      }
      <ng-icon name="heroChevronDown" />

      <div *ngpSelectPortal ngpSelectDropdown>
        @for (option of options; track option) {
          <div [ngpSelectOptionValue]="option" ngpSelectOption>
            {{ option }}
          </div>
        } @empty {
          <div class="empty-message">No options found</div>
        }
      </div>
    </div>
  `,
  styles: `
    [ngpSelect] {
      display: flex;
      justify-content: space-between;
      align-items: center;
      height: 36px;
      width: 300px;
      border-radius: 8px;
      border: none;
      background-color: var(--ngp-background);
      box-shadow: var(--ngp-input-shadow);
      box-sizing: border-box;
    }

    [ngpSelect][data-focus] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 2px;
    }

    .select-value,
    .select-placeholder {
      display: flex;
      align-items: center;
      flex: 1;
      padding: 0 16px;
      background-color: transparent;
      color: var(--ngp-text-primary);
      font-family: inherit;
      font-size: 14px;
      padding: 0 16px;
      height: 100%;
    }

    .select-placeholder {
      color: var(--ngp-text-secondary);
    }

    ng-icon {
      display: inline-flex;
      justify-content: center;
      align-items: center;
      height: 100%;
      margin-inline: 8px;
      font-size: 14px;
    }

    [ngpSelectDropdown] {
      background-color: var(--ngp-background);
      border: 1px solid var(--ngp-border);
      padding: 0.25rem;
      border-radius: 0.75rem;
      outline: none;
      position: absolute;
      animation: popover-show 0.1s ease-out;
      width: var(--ngp-select-width);
      box-shadow: var(--ngp-shadow-lg);
      box-sizing: border-box;
      margin-top: 4px;
      max-height: 240px;
      overflow-y: auto;
      z-index: 1001;
    }

    [ngpSelectDropdown][data-enter] {
      animation: select-show 0.1s ease-out;
    }

    [ngpSelectDropdown][data-exit] {
      animation: select-hide 0.1s ease-out;
    }

    [ngpSelectOption] {
      display: flex;
      align-items: center;
      gap: 0.5rem;
      padding: 0.375rem 0.75rem;
      cursor: pointer;
      border-radius: 0.5rem;
      width: 100%;
      height: 36px;
      font-size: 14px;
      color: var(--ngp-text-primary);
      box-sizing: border-box;
    }

    [ngpSelectOption][data-hover] {
      background-color: var(--ngp-background-hover);
    }

    [ngpSelectOption][data-press] {
      background-color: var(--ngp-background-active);
    }

    [ngpSelectOption][data-active] {
      background-color: var(--ngp-background-active);
    }

    .empty-message {
      display: flex;
      justify-content: center;
      align-items: center;
      padding: 0.5rem;
      color: var(--ngp-text-secondary);
      font-size: 14px;
      font-weight: 500;
      text-align: center;
    }

    @keyframes select-show {
      0% {
        opacity: 0;
        transform: translateY(-10px) scale(0.9);
      }
      100% {
        opacity: 1;
        transform: translateY(0) scale(1);
      }
    }

    @keyframes select-hide {
      0% {
        opacity: 1;
        transform: translateY(0) scale(1);
      }
      100% {
        opacity: 0;
        transform: translateY(-10px) scale(0.9);
      }
    }
  `,
})
export default class SelectExample {
  /** The options for the select. */
  readonly options: string[] = [
    'Marty McFly',
    'Doc Brown',
    'Biff Tannen',
    'George McFly',
    'Jennifer Parker',
    'Emmett Brown',
    'Einstein',
    'Clara Clayton',
    'Needles',
    'Goldie Wilson',
    'Marvin Berry',
    'Lorraine Baines',
    'Strickland',
  ];

  /** The selected value. */
  readonly value = signal<string | undefined>(undefined);
}

```

## Import

Import the Select primitives from `ng-primitives/select`.

```ts
import {
  NgpSelect,
  NgpSelectDropdown,
  NgpSelectPortal,
  NgpSelectOption,
} from 'ng-primitives/select';
```

## Usage

Assemble the select directives in your template.

```html
<div ngpSelect>
  <div *ngpSelectPortal ngpSelectDropdown>
    <div ngpSelectOptionValue="option-1" ngpSelectOption>One</div>
    <div ngpSelectOptionValue="option-2" ngpSelectOption>Two</div>
    <div ngpSelectOptionValue="option-3" ngpSelectOption>Three</div>
  </div>
</div>
```

## Reusable Component

Create a reusable component that uses the `NgpSelect` directive.

## Reusable Component

```typescript
import { BooleanInput } from '@angular/cdk/coercion';
import { booleanAttribute, Component, input, model, signal } from '@angular/core';
import { ControlValueAccessor } from '@angular/forms';
import { NgIcon, provideIcons } from '@ng-icons/core';
import { heroChevronDown } from '@ng-icons/heroicons/outline';
import {
  NgpSelect,
  NgpSelectDropdown,
  NgpSelectOption,
  NgpSelectPortal,
} from 'ng-primitives/select';
import { ChangeFn, provideValueAccessor, TouchedFn } from 'ng-primitives/utils';

@Component({
  selector: 'app-select',
  imports: [NgpSelect, NgpSelectDropdown, NgpSelectOption, NgpSelectPortal, NgIcon],
  providers: [provideIcons({ heroChevronDown }), provideValueAccessor(Select)],
  template: `
    <div
      [(ngpSelectValue)]="value"
      [ngpSelectDisabled]="disabled() || formDisabled()"
      (ngpSelectValueChange)="onValueChange($event)"
      ngpSelect
    >
      @if (value(); as value) {
        <span class="select-value">{{ value }}</span>
      } @else {
        <span class="select-placeholder">{{ placeholder() }}</span>
      }

      <ng-icon name="heroChevronDown" />

      <div *ngpSelectPortal ngpSelectDropdown>
        @for (option of options(); track option) {
          <div [ngpSelectOptionValue]="option" ngpSelectOption>
            {{ option }}
          </div>
        } @empty {
          <div class="empty-message">No options found</div>
        }
      </div>
    </div>
  `,
  styles: `
    [ngpSelect] {
      display: flex;
      justify-content: space-between;
      align-items: center;
      height: 36px;
      width: 300px;
      border-radius: 8px;
      border: none;
      background-color: var(--ngp-background);
      box-shadow: var(--ngp-input-shadow);
      box-sizing: border-box;
    }

    [ngpSelect][data-focus] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 2px;
    }

    .select-value,
    .select-placeholder {
      display: flex;
      align-items: center;
      flex: 1;
      padding: 0 16px;
      background-color: transparent;
      color: var(--ngp-text-primary);
      font-family: inherit;
      font-size: 14px;
      padding: 0 16px;
      height: 100%;
    }

    .select-placeholder {
      color: var(--ngp-text-secondary);
    }

    ng-icon {
      display: inline-flex;
      justify-content: center;
      align-items: center;
      height: 100%;
      margin-inline: 8px;
      font-size: 14px;
    }

    [ngpSelectDropdown] {
      background-color: var(--ngp-background);
      border: 1px solid var(--ngp-border);
      padding: 0.25rem;
      border-radius: 0.75rem;
      outline: none;
      position: absolute;
      animation: popover-show 0.1s ease-out;
      width: var(--ngp-select-width);
      box-shadow: var(--ngp-shadow-lg);
      box-sizing: border-box;
      margin-top: 4px;
      max-height: 240px;
      overflow-y: auto;
      transform-origin: var(--ngp-select-transform-origin);
    }

    [ngpSelectDropdown][data-enter] {
      animation: select-show 0.1s ease-out;
    }

    [ngpSelectDropdown][data-exit] {
      animation: select-hide 0.1s ease-out;
    }

    [ngpSelectOption] {
      display: flex;
      align-items: center;
      gap: 0.5rem;
      padding: 0.375rem 0.75rem;
      cursor: pointer;
      border-radius: 0.5rem;
      width: 100%;
      height: 36px;
      font-size: 14px;
      color: var(--ngp-text-primary);
      box-sizing: border-box;
    }

    [ngpSelectOption][data-hover] {
      background-color: var(--ngp-background-hover);
    }

    [ngpSelectOption][data-press] {
      background-color: var(--ngp-background-active);
    }

    [ngpSelectOption][data-active] {
      background-color: var(--ngp-background-active);
    }

    .empty-message {
      display: flex;
      justify-content: center;
      align-items: center;
      padding: 0.5rem;
      color: var(--ngp-text-secondary);
      font-size: 14px;
      font-weight: 500;
      text-align: center;
    }

    @keyframes select-show {
      0% {
        opacity: 0;
        transform: translateY(-10px) scale(0.9);
      }
      100% {
        opacity: 1;
        transform: translateY(0) scale(1);
      }
    }

    @keyframes select-hide {
      0% {
        opacity: 1;
        transform: translateY(0) scale(1);
      }
      100% {
        opacity: 0;
        transform: translateY(-10px) scale(0.9);
      }
    }
  `,
})
export class Select implements ControlValueAccessor {
  /** The options for the select. */
  readonly options = input<string[]>([]);

  /** The selected value. */
  readonly value = model<string | undefined>();

  /** The placeholder for the input. */
  readonly placeholder = input<string>('');

  /** The disabled state of the select. */
  readonly disabled = input<boolean, BooleanInput>(false, {
    transform: booleanAttribute,
  });

  /** Store the form disabled state */
  protected readonly formDisabled = signal(false);

  /** The on change callback */
  private onChange?: ChangeFn<string>;

  /** The on touch callback */
  protected onTouched?: TouchedFn;

  writeValue(value: string | undefined): void {
    this.value.set(value);
  }

  registerOnChange(fn: ChangeFn<string | undefined>): void {
    this.onChange = fn;
  }

  registerOnTouched(fn: TouchedFn): void {
    this.onTouched = fn;
  }

  setDisabledState(isDisabled: boolean): void {
    this.formDisabled.set(isDisabled);
  }

  protected onValueChange(value: string): void {
    this.onChange?.(value);
  }
}

```

## Schematics

Generate a reusable select component using the Angular CLI.

```bash npm
ng g ng-primitives:primitive select
```

### Options

- `path`: The path at which to create the component file.
- `prefix`: The prefix to apply to the generated component selector.
- `componentSuffix`: The suffix to apply to the generated component class name.
- `fileSuffix`: The suffix to apply to the generated component file name. Defaults to `component`.
- `exampleStyles`: Whether to include example styles in the generated component file. Defaults to `true`.

## Examples

Here are some additional examples of how to use the Select primitives.

### Select Form Field

The select can be used within a form field for better integration with form controls.

## Example

```typescript
import { Component, signal } from '@angular/core';
import { NgIcon, provideIcons } from '@ng-icons/core';
import { heroChevronDown } from '@ng-icons/heroicons/outline';
import { NgpDescription, NgpFormField, NgpLabel } from 'ng-primitives/form-field';
import {
  NgpSelect,
  NgpSelectDropdown,
  NgpSelectOption,
  NgpSelectPortal,
} from 'ng-primitives/select';

@Component({
  selector: 'app-select-form-field',
  imports: [
    NgpSelect,
    NgpSelectDropdown,
    NgpSelectOption,
    NgpSelectPortal,
    NgIcon,
    NgpFormField,
    NgpLabel,
    NgpDescription,
  ],
  providers: [provideIcons({ heroChevronDown })],
  template: `
    <div ngpFormField>
      <label ngpLabel>Choose a character</label>
      <p ngpDescription>Which character is your favorite?</p>

      <div [(ngpSelectValue)]="value" ngpSelect>
        @if (value(); as value) {
          <span class="select-value">{{ value }}</span>
        } @else {
          <span class="select-placeholder">Select an option</span>
        }
        <ng-icon name="heroChevronDown" />

        <div *ngpSelectPortal ngpSelectDropdown>
          @for (option of options; track option) {
            <div [ngpSelectOptionValue]="option" ngpSelectOption>
              {{ option }}
            </div>
          } @empty {
            <div class="empty-message">No options found</div>
          }
        </div>
      </div>
    </div>
  `,
  styles: `
    [ngpFormField] {
      display: flex;
      flex-direction: column;
      gap: 6px;
      width: 90%;
    }

    [ngpLabel] {
      color: var(--ngp-text-primary);
      font-size: 0.875rem;
      line-height: 1.25rem;
      font-weight: 500;
      margin: 0;
    }

    [ngpDescription] {
      color: var(--ngp-text-secondary);
      font-size: 0.75rem;
      line-height: 1rem;
      margin: 0 0 4px;
    }

    [ngpSelect] {
      display: flex;
      justify-content: space-between;
      align-items: center;
      height: 36px;
      width: 300px;
      border-radius: 8px;
      border: none;
      background-color: var(--ngp-background);
      box-shadow: var(--ngp-input-shadow);
      box-sizing: border-box;
    }

    [ngpSelect][data-focus] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 2px;
    }

    .select-value,
    .select-placeholder {
      display: flex;
      align-items: center;
      flex: 1;
      padding: 0 16px;
      background-color: transparent;
      color: var(--ngp-text-primary);
      font-family: inherit;
      font-size: 14px;
      padding: 0 16px;
      height: 100%;
    }

    .select-placeholder {
      color: var(--ngp-text-secondary);
    }

    ng-icon {
      display: inline-flex;
      justify-content: center;
      align-items: center;
      height: 100%;
      margin-inline: 8px;
      font-size: 14px;
    }

    [ngpSelectDropdown] {
      background-color: var(--ngp-background);
      border: 1px solid var(--ngp-border);
      padding: 0.25rem;
      border-radius: 0.75rem;
      outline: none;
      position: absolute;
      animation: popover-show 0.1s ease-out;
      width: var(--ngp-select-width);
      box-shadow: var(--ngp-shadow-lg);
      box-sizing: border-box;
      margin-top: 4px;
      max-height: 240px;
      overflow-y: auto;
      z-index: 1001;
    }

    [ngpSelectDropdown][data-enter] {
      animation: select-show 0.1s ease-out;
    }

    [ngpSelectDropdown][data-exit] {
      animation: select-hide 0.1s ease-out;
    }

    [ngpSelectOption] {
      display: flex;
      align-items: center;
      gap: 0.5rem;
      padding: 0.375rem 0.75rem;
      cursor: pointer;
      border-radius: 0.5rem;
      width: 100%;
      height: 36px;
      font-size: 14px;
      color: var(--ngp-text-primary);
      box-sizing: border-box;
    }

    [ngpSelectOption][data-hover] {
      background-color: var(--ngp-background-hover);
    }

    [ngpSelectOption][data-press] {
      background-color: var(--ngp-background-active);
    }

    [ngpSelectOption][data-active] {
      background-color: var(--ngp-background-active);
    }

    .empty-message {
      display: flex;
      justify-content: center;
      align-items: center;
      padding: 0.5rem;
      color: var(--ngp-text-secondary);
      font-size: 14px;
      font-weight: 500;
      text-align: center;
    }

    @keyframes select-show {
      0% {
        opacity: 0;
        transform: translateY(-10px) scale(0.9);
      }
      100% {
        opacity: 1;
        transform: translateY(0) scale(1);
      }
    }

    @keyframes select-hide {
      0% {
        opacity: 1;
        transform: translateY(0) scale(1);
      }
      100% {
        opacity: 0;
        transform: translateY(-10px) scale(0.9);
      }
    }
  `,
})
export default class SelectFormFieldExample {
  /** The options for the select. */
  readonly options: string[] = [
    'Marty McFly',
    'Doc Brown',
    'Biff Tannen',
    'George McFly',
    'Jennifer Parker',
    'Emmett Brown',
    'Einstein',
    'Clara Clayton',
    'Needles',
    'Goldie Wilson',
    'Marvin Berry',
    'Lorraine Baines',
    'Strickland',
  ];

  /** The selected value. */
  readonly value = signal<string | undefined>(undefined);
}

```

### Native Select

The native select is a simple wrapper around the native `select` element.

## Example

```typescript
import { Component } from '@angular/core';
import { NgpNativeSelect } from 'ng-primitives/select';

@Component({
  selector: 'app-native-select',
  imports: [NgpNativeSelect],
  template: `
    <select ngpNativeSelect>
      <option value="24">24 hours</option>
      <option value="12">12 hours</option>
    </select>
  `,
  styles: `
    :host {
      display: contents;
    }

    select {
      all: unset;
      appearance: none;
      display: flex;
      width: 90%;
      align-items: center;
      height: 2.5rem;
      padding: 0 1rem;
      border-radius: 0.5rem;
      background-color: var(--ngp-background);
      text-align: start;
      box-shadow: var(--ngp-button-shadow);
      outline: none;
      background-position-x: calc(100% - 10px);
      background-position-y: 50%;
      background-image: url('data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyMCAyMCIgZmlsbD0iIzczNzM3MyI+PHBhdGggZmlsbC1ydWxlPSJldmVub2RkIiBkPSJNNS4yMiA4LjIyYS43NS43NSAwIDAgMSAxLjA2IDBMMTAgMTEuOTRsMy43Mi0zLjcyYS43NS43NSAwIDEgMSAxLjA2IDEuMDZsLTQuMjUgNC4yNWEuNzUuNzUgMCAwIDEtMS4wNiAwTDUuMjIgOS4yOGEuNzUuNzUgMCAwIDEgMC0xLjA2WiIgY2xpcC1ydWxlPSJldmVub2RkIj48L3BhdGg+PC9zdmc+');
      background-size: 1.25rem;
      background-repeat: no-repeat;
    }

    select[data-hover] {
      background-color: var(--ngp-background-hover);
    }

    select[data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 0;
    }

    select[data-press] {
      background-color: var(--ngp-background-active);
    }
  `,
})
export default class NativeSelectExample {}

```

### Native Select Form Field

The select automatically integrates with the form field primitives.

## Example

```typescript
import { Component } from '@angular/core';
import { NgpDescription, NgpFormField, NgpLabel } from 'ng-primitives/form-field';
import { NgpNativeSelect } from 'ng-primitives/select';

@Component({
  selector: 'app-native-select-form-field',
  imports: [NgpNativeSelect, NgpFormField, NgpLabel, NgpDescription],
  template: `
    <div ngpFormField>
      <label ngpLabel>Time Format</label>
      <p ngpDescription>Choose between 12-hour and 24-hour time formats.</p>
      <select ngpNativeSelect>
        <option value="24">24 hours</option>
        <option value="12">12 hours</option>
      </select>
    </div>
  `,
  styles: `
    :host {
      display: contents;
    }

    [ngpFormField] {
      display: flex;
      flex-direction: column;
      gap: 6px;
      width: 90%;
    }

    [ngpLabel] {
      color: var(--ngp-text-primary);
      font-size: 0.875rem;
      line-height: 1.25rem;
      font-weight: 500;
      margin: 0;
    }

    [ngpDescription] {
      color: var(--ngp-text-secondary);
      font-size: 0.75rem;
      line-height: 1rem;
      margin: 0 0 4px;
    }

    select {
      all: unset;
      appearance: none;
      display: flex;
      width: 90%;
      align-items: center;
      height: 2.5rem;
      padding: 0 1rem;
      border-radius: 0.5rem;
      background-color: var(--ngp-background);
      text-align: start;
      box-shadow: var(--ngp-button-shadow);
      outline: none;
      background-position-x: calc(100% - 10px);
      background-position-y: 50%;
      background-image: url('data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyMCAyMCIgZmlsbD0iIzczNzM3MyI+PHBhdGggZmlsbC1ydWxlPSJldmVub2RkIiBkPSJNNS4yMiA4LjIyYS43NS43NSAwIDAgMSAxLjA2IDBMMTAgMTEuOTRsMy43Mi0zLjcyYS43NS43NSAwIDEgMSAxLjA2IDEuMDZsLTQuMjUgNC4yNWEuNzUuNzUgMCAwIDEtMS4wNiAwTDUuMjIgOS4yOGEuNzUuNzUgMCAwIDEgMC0xLjA2WiIgY2xpcC1ydWxlPSJldmVub2RkIj48L3BhdGg+PC9zdmc+');
      background-size: 1.25rem;
      background-repeat: no-repeat;
    }

    select[data-hover] {
      background-color: var(--ngp-background-hover);
    }

    select[data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 0;
    }

    select[data-press] {
      background-color: var(--ngp-background-active);
    }
  `,
})
export default class NativeSelectFormFieldExample {}

```

### Select with Custom Container

The select component can be rendered inside a custom container. You can open DevTools and inspect the DOM to see it mounted within this container.

## Example

```typescript
import { Component, signal } from '@angular/core';
import { NgIcon, provideIcons } from '@ng-icons/core';
import { heroChevronDown } from '@ng-icons/heroicons/outline';
import {
  NgpSelect,
  NgpSelectDropdown,
  NgpSelectOption,
  NgpSelectPortal,
  provideSelectConfig,
} from 'ng-primitives/select';

@Component({
  selector: 'app-select-custom-container',
  imports: [NgpSelect, NgpSelectDropdown, NgpSelectOption, NgpSelectPortal, NgIcon],
  providers: [
    provideIcons({ heroChevronDown }),
    provideSelectConfig({
      container: '.select-container',
    }),
  ],
  template: `
    <div class="select-container"></div>

    <div [(ngpSelectValue)]="value" ngpSelect>
      @if (value(); as value) {
        <span class="select-value">{{ value }}</span>
      } @else {
        <span class="select-placeholder">Select an option</span>
      }
      <ng-icon name="heroChevronDown" />

      <div *ngpSelectPortal ngpSelectDropdown>
        @for (option of options; track option) {
          <div [ngpSelectOptionValue]="option" ngpSelectOption>
            {{ option }}
          </div>
        } @empty {
          <div class="empty-message">No options found</div>
        }
      </div>
    </div>
  `,
  styles: `
    .select-container {
      position: relative;
    }

    [ngpSelect] {
      display: flex;
      justify-content: space-between;
      align-items: center;
      height: 36px;
      width: 300px;
      border-radius: 8px;
      border: none;
      background-color: var(--ngp-background);
      box-shadow: var(--ngp-input-shadow);
      box-sizing: border-box;
    }

    [ngpSelect][data-focus] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 2px;
    }

    .select-value,
    .select-placeholder {
      display: flex;
      align-items: center;
      flex: 1;
      padding: 0 16px;
      background-color: transparent;
      color: var(--ngp-text-primary);
      font-family: inherit;
      font-size: 14px;
      padding: 0 16px;
      height: 100%;
    }

    .select-placeholder {
      color: var(--ngp-text-secondary);
    }

    ng-icon {
      display: inline-flex;
      justify-content: center;
      align-items: center;
      height: 100%;
      margin-inline: 8px;
      font-size: 14px;
    }

    [ngpSelectDropdown] {
      background-color: var(--ngp-background);
      border: 1px solid var(--ngp-border);
      padding: 0.25rem;
      border-radius: 0.75rem;
      outline: none;
      position: absolute;
      animation: popover-show 0.1s ease-out;
      width: var(--ngp-select-width);
      box-shadow: var(--ngp-shadow-lg);
      box-sizing: border-box;
      margin-top: 4px;
      max-height: 240px;
      overflow-y: auto;
      z-index: 1001;
    }

    [ngpSelectDropdown][data-enter] {
      animation: select-show 0.1s ease-out;
    }

    [ngpSelectDropdown][data-exit] {
      animation: select-hide 0.1s ease-out;
    }

    [ngpSelectOption] {
      display: flex;
      align-items: center;
      gap: 0.5rem;
      padding: 0.375rem 0.75rem;
      cursor: pointer;
      border-radius: 0.5rem;
      width: 100%;
      height: 36px;
      font-size: 14px;
      color: var(--ngp-text-primary);
      box-sizing: border-box;
    }

    [ngpSelectOption][data-hover] {
      background-color: var(--ngp-background-hover);
    }

    [ngpSelectOption][data-press] {
      background-color: var(--ngp-background-active);
    }

    [ngpSelectOption][data-active] {
      background-color: var(--ngp-background-active);
    }

    .empty-message {
      display: flex;
      justify-content: center;
      align-items: center;
      padding: 0.5rem;
      color: var(--ngp-text-secondary);
      font-size: 14px;
      font-weight: 500;
      text-align: center;
    }

    @keyframes select-show {
      0% {
        opacity: 0;
        transform: translateY(-10px) scale(0.9);
      }
      100% {
        opacity: 1;
        transform: translateY(0) scale(1);
      }
    }

    @keyframes select-hide {
      0% {
        opacity: 1;
        transform: translateY(0) scale(1);
      }
      100% {
        opacity: 0;
        transform: translateY(-10px) scale(0.9);
      }
    }
  `,
})
export default class SelectCustomContainerExample {
  /** The options for the select. */
  readonly options: string[] = [
    'Marty McFly',
    'Doc Brown',
    'Biff Tannen',
    'George McFly',
    'Jennifer Parker',
    'Emmett Brown',
    'Einstein',
    'Clara Clayton',
    'Needles',
    'Goldie Wilson',
    'Marvin Berry',
    'Lorraine Baines',
    'Strickland',
  ];

  /** The selected value. */
  readonly value = signal<string | undefined>(undefined);
}

```

### Virtualized Large Lists

When dealing with large datasets (thousands of items), you can use TanStack Virtual or other virtualization libraries to efficiently render only the visible options, improving performance:

## Example

```typescript
import { Component, ElementRef, signal, viewChild } from '@angular/core';
import { NgIcon, provideIcons } from '@ng-icons/core';
import { heroChevronDown } from '@ng-icons/heroicons/outline';
import { injectVirtualizer } from '@tanstack/angular-virtual';
import {
  NgpSelect,
  NgpSelectDropdown,
  NgpSelectOption,
  NgpSelectPortal,
} from 'ng-primitives/select';

@Component({
  selector: 'app-select-virtual',
  imports: [NgpSelect, NgpSelectDropdown, NgpSelectOption, NgpSelectPortal, NgIcon],
  providers: [provideIcons({ heroChevronDown })],
  template: `
    <div
      [(ngpSelectValue)]="value"
      [ngpSelectScrollToOption]="scrollToOption"
      [ngpSelectOptions]="options"
      ngpSelect
    >
      @if (value(); as selectedValue) {
        <span class="select-value">{{ selectedValue }}</span>
      } @else {
        <span class="select-placeholder">Select from 10,000 options</span>
      }
      <ng-icon name="heroChevronDown" />

      <div *ngpSelectPortal ngpSelectDropdown>
        <div class="virtual-container" #scrollContainer>
          <div
            class="virtual-list"
            [style.height.px]="virtualizer.getTotalSize()"
            [style.position]="'relative'"
          >
            @for (virtualRow of virtualizer.getVirtualItems(); track virtualRow.index) {
              <div
                class="virtual-item"
                [ngpSelectOptionValue]="options[virtualRow.index]"
                [style.position]="'absolute'"
                [style.top.px]="virtualRow.start"
                [style.left]="'0'"
                [style.width]="'100%'"
                [style.height.px]="virtualRow.size"
                [ngpSelectOptionIndex]="virtualRow.index"
                ngpSelectOption
              >
                {{ options[virtualRow.index] }}
              </div>
            }
          </div>
        </div>
      </div>
    </div>
  `,
  styles: `
    [ngpSelect] {
      display: flex;
      justify-content: space-between;
      align-items: center;
      height: 36px;
      width: 300px;
      border-radius: 8px;
      border: none;
      background-color: var(--ngp-background);
      box-shadow: var(--ngp-input-shadow);
      box-sizing: border-box;
      cursor: pointer;
    }

    [ngpSelect][data-focus] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 2px;
    }

    .select-value,
    .select-placeholder {
      display: flex;
      align-items: center;
      flex: 1;
      padding: 0 16px;
      background-color: transparent;
      color: var(--ngp-text-primary);
      font-family: inherit;
      font-size: 14px;
      height: 100%;
    }

    .select-placeholder {
      color: var(--ngp-text-tertiary);
    }

    ng-icon {
      display: inline-flex;
      justify-content: center;
      align-items: center;
      height: 100%;
      margin-inline: 8px;
      font-size: 14px;
    }

    [ngpSelectDropdown] {
      background-color: var(--ngp-background);
      border: 1px solid var(--ngp-border);
      padding: 0;
      border-radius: 0.75rem;
      outline: none;
      position: absolute;
      animation: popover-show 0.1s ease-out;
      width: var(--ngp-select-width);
      box-shadow: var(--ngp-shadow-lg);
      box-sizing: border-box;
      margin-top: 4px;
      max-height: 300px;
      overflow: hidden;
      z-index: 1001;
      display: flex;
      flex-direction: column;
    }

    [ngpSelectDropdown][data-enter] {
      animation: select-show 0.1s ease-out;
    }

    [ngpSelectDropdown][data-exit] {
      animation: select-hide 0.1s ease-out;
    }

    .virtual-container {
      flex: 1;
      min-height: 0;
      overflow: auto;
      padding: 0.25rem;
      position: relative;
      height: 250px;
    }

    .virtual-item {
      display: flex;
      align-items: center;
      gap: 0.5rem;
      padding: 0.375rem 0.75rem;
      cursor: pointer;
      border-radius: 0.5rem;
      width: 100%;
      height: 36px;
      font-size: 14px;
      color: var(--ngp-text-primary);
      box-sizing: border-box;
    }

    .virtual-item[data-hover] {
      background-color: var(--ngp-background-hover);
    }

    .virtual-item[data-press] {
      background-color: var(--ngp-background-active);
    }

    .virtual-item[data-active] {
      background-color: var(--ngp-background-active);
    }

    .virtual-item[data-selected] {
      background-color: var(--ngp-background-active);
    }

    .empty-message {
      display: flex;
      justify-content: center;
      align-items: center;
      padding: 1rem;
      color: var(--ngp-text-secondary);
      font-size: 14px;
      font-weight: 500;
      text-align: center;
    }

    .results-info {
      padding: 0.5rem 0.75rem;
      border-top: 1px solid var(--ngp-border);
      font-size: 12px;
      color: var(--ngp-text-secondary);
      background-color: var(--ngp-background-secondary);
      border-radius: 0 0 0.75rem 0.75rem;
    }

    @keyframes select-show {
      0% {
        opacity: 0;
        transform: translateY(-10px) scale(0.9);
      }
      100% {
        opacity: 1;
        transform: translateY(0) scale(1);
      }
    }

    @keyframes select-hide {
      0% {
        opacity: 1;
        transform: translateY(0) scale(1);
      }
      100% {
        opacity: 0;
        transform: translateY(-10px) scale(0.9);
      }
    }
  `,
})
export default class SelectVirtualExample {
  /** The options for the select - 10,000 generated names. */
  readonly options: string[] = generateLargeDataset(10000);

  /** The selected value. */
  readonly value = signal<string | undefined>(undefined);

  /** The scroll container element reference. */
  readonly scrollContainer = viewChild<ElementRef<HTMLDivElement>>('scrollContainer');

  /** The virtualizer instance. */
  readonly virtualizer = injectVirtualizer(() => ({
    count: this.options.length,
    scrollElement: this.scrollContainer(),
    estimateSize: () => 36,
    overscan: 5,
  }));

  /** A custom scroll to option function. */
  protected readonly scrollToOption = (index: number) => {
    this.virtualizer.scrollToIndex(index, { behavior: 'auto', align: 'auto' });
  };
}

// Generate a large dataset to showcase virtualization
function generateLargeDataset(count: number): string[] {
  const firstNames = [
    'James',
    'Mary',
    'John',
    'Patricia',
    'Robert',
    'Jennifer',
    'Michael',
    'Linda',
    'William',
    'Elizabeth',
    'David',
    'Barbara',
    'Richard',
    'Susan',
    'Joseph',
    'Jessica',
    'Thomas',
    'Sarah',
    'Christopher',
    'Karen',
    'Charles',
    'Nancy',
    'Daniel',
    'Lisa',
    'Matthew',
    'Betty',
    'Anthony',
    'Helen',
    'Mark',
    'Sandra',
    'Donald',
    'Donna',
    'Steven',
    'Carol',
    'Paul',
    'Ruth',
    'Andrew',
    'Sharon',
    'Joshua',
    'Michelle',
    'Kenneth',
    'Laura',
    'Kevin',
    'Emily',
    'Brian',
    'Kimberly',
    'George',
    'Deborah',
    'Edward',
    'Dorothy',
    'Ronald',
    'Amy',
    'Timothy',
    'Angela',
    'Jason',
    'Ashley',
    'Jeffrey',
    'Brenda',
    'Ryan',
    'Emma',
    'Jacob',
    'Olivia',
    'Gary',
    'Cynthia',
  ];

  const lastNames = [
    'Smith',
    'Johnson',
    'Williams',
    'Brown',
    'Jones',
    'Garcia',
    'Miller',
    'Davis',
    'Rodriguez',
    'Martinez',
    'Hernandez',
    'Lopez',
    'Gonzalez',
    'Wilson',
    'Anderson',
    'Thomas',
    'Taylor',
    'Moore',
    'Jackson',
    'Martin',
    'Lee',
    'Perez',
    'Thompson',
    'White',
    'Harris',
    'Sanchez',
    'Clark',
    'Ramirez',
    'Lewis',
    'Robinson',
    'Walker',
    'Young',
    'Allen',
    'King',
    'Wright',
    'Scott',
    'Torres',
    'Nguyen',
    'Hill',
    'Flores',
    'Green',
    'Adams',
    'Nelson',
    'Baker',
    'Hall',
    'Rivera',
    'Campbell',
    'Mitchell',
    'Carter',
    'Roberts',
    'Gomez',
    'Phillips',
    'Evans',
    'Turner',
    'Diaz',
    'Parker',
    'Cruz',
    'Edwards',
    'Collins',
    'Reyes',
    'Stewart',
    'Morris',
    'Morales',
    'Murphy',
  ];

  const options: string[] = [];
  for (let i = 0; i < count; i++) {
    const firstName = firstNames[i % firstNames.length];
    const lastName = lastNames[Math.floor(i / firstNames.length) % lastNames.length];
    const id = String(i + 1).padStart(4, '0');
    options.push(`${firstName} ${lastName} (#${id})`);
  }
  return options;
}

```

### Custom Option Behavior

Options without a value do not perform any selection by default. You can use this to implement custom behavior, such as clearing the selection. These options are still included in keyboard navigation.

## Example

```typescript
import { Component, signal } from '@angular/core';
import { NgIcon, provideIcons } from '@ng-icons/core';
import { heroChevronDown } from '@ng-icons/heroicons/outline';
import {
  NgpSelect,
  NgpSelectDropdown,
  NgpSelectOption,
  NgpSelectPortal,
} from 'ng-primitives/select';

@Component({
  selector: 'app-select-custom-option',
  imports: [NgpSelect, NgpSelectDropdown, NgpSelectOption, NgpSelectPortal, NgIcon],
  providers: [provideIcons({ heroChevronDown })],
  template: `
    <div [(ngpSelectValue)]="value" ngpSelect>
      @if (value(); as value) {
        <span class="select-value">{{ value }}</span>
      } @else {
        <span class="select-placeholder">Select an option</span>
      }
      <ng-icon name="heroChevronDown" />

      <div *ngpSelectPortal ngpSelectDropdown>
        <div class="clear-option" (ngpSelectOptionActivated)="clear()" ngpSelectOption>None</div>

        <div class="divider"></div>

        @for (option of options; track option) {
          <div [ngpSelectOptionValue]="option" ngpSelectOption>
            {{ option }}
          </div>
        } @empty {
          <div class="empty-message">No options found</div>
        }
      </div>
    </div>
  `,
  styles: `
    [ngpSelect] {
      display: flex;
      justify-content: space-between;
      align-items: center;
      height: 36px;
      width: 300px;
      border-radius: 8px;
      border: none;
      background-color: var(--ngp-background);
      box-shadow: var(--ngp-input-shadow);
      box-sizing: border-box;
    }

    [ngpSelect][data-focus] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 2px;
    }

    .select-value,
    .select-placeholder {
      display: flex;
      align-items: center;
      flex: 1;
      padding: 0 16px;
      background-color: transparent;
      color: var(--ngp-text-primary);
      font-family: inherit;
      font-size: 14px;
      padding: 0 16px;
      height: 100%;
    }

    .select-placeholder {
      color: var(--ngp-text-secondary);
    }

    ng-icon {
      display: inline-flex;
      justify-content: center;
      align-items: center;
      height: 100%;
      margin-inline: 8px;
      font-size: 14px;
    }

    [ngpSelectDropdown] {
      background-color: var(--ngp-background);
      border: 1px solid var(--ngp-border);
      padding: 0.25rem;
      border-radius: 0.75rem;
      outline: none;
      position: absolute;
      animation: popover-show 0.1s ease-out;
      width: var(--ngp-select-width);
      box-shadow: var(--ngp-shadow-lg);
      box-sizing: border-box;
      margin-top: 4px;
      max-height: 240px;
      overflow-y: auto;
      z-index: 1001;
    }

    [ngpSelectDropdown][data-enter] {
      animation: select-show 0.1s ease-out;
    }

    [ngpSelectDropdown][data-exit] {
      animation: select-hide 0.1s ease-out;
    }

    [ngpSelectOption] {
      display: flex;
      align-items: center;
      gap: 0.5rem;
      padding: 0.375rem 0.75rem;
      cursor: pointer;
      border-radius: 0.5rem;
      width: 100%;
      height: 36px;
      font-size: 14px;
      color: var(--ngp-text-primary);
      box-sizing: border-box;
    }

    [ngpSelectOption][data-hover] {
      background-color: var(--ngp-background-hover);
    }

    [ngpSelectOption][data-press] {
      background-color: var(--ngp-background-active);
    }

    [ngpSelectOption][data-active] {
      background-color: var(--ngp-background-active);
    }

    .clear-option {
      color: var(--ngp-text-secondary);
      font-style: italic;
    }

    .divider {
      height: 1px;
      background-color: var(--ngp-border);
      margin: 0.25rem 0;
    }

    .empty-message {
      display: flex;
      justify-content: center;
      align-items: center;
      padding: 0.5rem;
      color: var(--ngp-text-secondary);
      font-size: 14px;
      font-weight: 500;
      text-align: center;
    }

    @keyframes select-show {
      0% {
        opacity: 0;
        transform: translateY(-10px) scale(0.9);
      }
      100% {
        opacity: 1;
        transform: translateY(0) scale(1);
      }
    }

    @keyframes select-hide {
      0% {
        opacity: 1;
        transform: translateY(0) scale(1);
      }
      100% {
        opacity: 0;
        transform: translateY(-10px) scale(0.9);
      }
    }
  `,
})
export default class SelectCustomOptionExample {
  /** The options for the select. */
  readonly options: string[] = [
    'Marty McFly',
    'Doc Brown',
    'Biff Tannen',
    'George McFly',
    'Jennifer Parker',
    'Emmett Brown',
    'Einstein',
    'Clara Clayton',
    'Needles',
    'Goldie Wilson',
    'Marvin Berry',
    'Lorraine Baines',
    'Strickland',
  ];

  /** The selected value. */
  readonly value = signal<string | undefined>(undefined);

  /** Clear the selection. */
  clear(): void {
    this.value.set(undefined);
  }
}

```

## API Reference

The following directives are available to import from the `ng-primitives/select` package:

### NgpSelect

## API Reference

### NgpSelect



**Selector:** `[ngpSelect]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpSelectValue` | `any` | `-` | The value of the select. |
| `ngpSelectMultiple` | `boolean` | `-` | Whether the select is multiple selection. |
| `ngpSelectDisabled` | `boolean` | `-` | Whether the select is disabled. |
| `ngpSelectCompareWith` | `(a: any, b: any) => boolean` | `-` | The comparator function used to compare options. |
| `ngpSelectDropdownPlacement` | `Placement` | `-` | The position of the dropdown. |
| `ngpSelectDropdownContainer` | `string | HTMLElement | null` | `-` | The container for the dropdown. |
| `ngpSelectScrollToOption` | `((index: number) => void) | undefined` | `-` | A function that will scroll the active option into view. This can be overridden
for cases such as virtual scrolling where we cannot scroll the option directly because
it may not be rendered. |
| `ngpSelectOptions` | `any[] | undefined` | `-` | Provide all the option values to the select. This is useful for virtual scrolling scenarios
where not all options are rendered in the DOM. This is not an alternative to adding the options
in the DOM, it is only to provide the select with the full list of options. This list should match
the order of the options as they would appear in the DOM. |

#### Outputs

| Event | Type | Description |
|-------|------|-------------|
| `ngpSelectValueChange` | `any` | Event emitted when the value changes. |
| `ngpSelectOpenChange` | `boolean` | Emit when the dropdown open state changes. |

#### Export As

`ngpSelect`



### NgpSelectDropdown

## API Reference

### NgpSelectDropdown



**Selector:** `[ngpSelectDropdown]`

#### Export As

`ngpSelectDropdown`



### NgpSelectPortal

## API Reference

### NgpSelectPortal



**Selector:** `[ngpSelectPortal]`

#### Export As

`ngpSelectPortal`



### NgpSelectOption

## API Reference

### NgpSelectOption



**Selector:** `[ngpSelectOption]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpSelectOptionValue` | `any` | `-` | - |
| `ngpSelectOptionDisabled` | `boolean` | `-` | The disabled state of the option. |
| `ngpSelectOptionIndex` | `number | undefined` | `-` | The index of the option in the list. |

#### Outputs

| Event | Type | Description |
|-------|------|-------------|
| `ngpSelectOptionActivated` | `void` | Event emitted when the option is activated via click or keyboard.
This is useful for options without values that need custom behavior. |

#### Export As

`ngpSelectOption`



### NgpNativeSelect

## API Reference

### NgpNativeSelect

Apply the `ngpNativeSelect` directive to a select element that you want to enhance.

**Selector:** `select[ngpNativeSelect]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpNativeSelectDisabled` | `boolean` | `-` | Whether the select is disabled. |

#### Export As

`ngpNativeSelect`



#### Data Attributes

| Attribute            | Description                           |
| -------------------- | ------------------------------------- |
| `data-hover`         | Applied when the element is hovered.  |
| `data-focus-visible` | Applied when the element is focused.  |
| `data-disabled`      | Applied when the element is disabled. |


---

### Separator

File: primitives/separator.md
URL: https://angularprimitives.com/primitives/separator

# Separator

The separator primitive allow you to semantically separate content either horizontally or vertically.

## Example

```typescript
import { Component } from '@angular/core';
import { NgpSeparator } from 'ng-primitives/separator';

@Component({
  selector: 'app-separator',
  imports: [NgpSeparator],
  template: `
    <p>The separator primitive can be used to separate content in a layout.</p>
    <div ngpSeparator></div>
    <p>It supports both horizontal and vertical orientations.</p>
  `,
  styles: `
    :host {
      display: flex;
      flex-direction: column;
      gap: 1rem;
      max-width: 300px;
      background-color: var(--ngp-background);
      padding: 1rem;
      border-radius: 8px;
      box-shadow: var(--ngp-shadow);
      border: 1px solid var(--ngp-border);
    }

    p {
      color: var(--ngp-text-primary);
      margin: 0;
    }

    [ngpSeparator] {
      background-color: var(--ngp-border);
      height: 1px;
    }
  `,
})
export default class SeparatorExample {}

```

## Import

Import the Separator primitives from `ng-primitives/separator`.

```ts
import { NgpSeparator } from 'ng-primitives/separator';
```

## Usage

Assemble the separator directives in your template.

```html
<div ngpSeparator></div>
```

## Reusable Component

Create a reusable component that uses the `NgpSeparator` directive.

## Reusable Component

```typescript
import { Component } from '@angular/core';
import { NgpSeparator } from 'ng-primitives/separator';

@Component({
  selector: '[app-separator]',
  hostDirectives: [{ directive: NgpSeparator, inputs: ['ngpSeparatorOrientation:orientation'] }],
  template: ``,
  styles: `
    :host {
      background-color: var(--ngp-border);
      height: 1px;
    }
  `,
})
export class Separator {}

```

## Schematics

Generate a reusable separator component using the Angular CLI.

```bash npm
ng g ng-primitives:primitive separator
```

### Options

- `path`: The path at which to create the component file.
- `prefix`: The prefix to apply to the generated component selector.
- `componentSuffix`: The suffix to apply to the generated component class name.
- `fileSuffix`: The suffix to apply to the generated component file name. Defaults to `component`.
- `exampleStyles`: Whether to include example styles in the generated component file. Defaults to `true`.

## API Reference

The following directives are available to import from the `ng-primitives/separator` package:

### NgpSeparator

## API Reference

### NgpSeparator



**Selector:** `[ngpSeparator]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpSeparatorOrientation` | `NgpOrientation` | `-` | The orientation of the separator. |

#### Export As

`ngpSeparator`



#### Data Attributes

| Attribute          | Description                       |
| ------------------ | --------------------------------- |
| `data-orientation` | The orientation of the separator. |

## Global Configuration

You can configure the default options for all separators in your application by using the `provideSeparatorConfig` function in a providers array.

```ts
import { provideSeparatorConfig } from 'ng-primitives/tabs';

bootstrapApplication(AppComponent, {
  providers: [
    provideSeparatorConfig({
      orientation: 'horizontal',
    }),
  ],
});
```

### NgpSeparatorConfig

The following options are available to configure the default tab options:

<prop-details name="orientation" type="'horizontal' | 'vertical'" default="horizontal">
  Define the default orientation of the separator.
</prop-details

## Accessibility

Adheres to the [WAI-ARIA Separator Design Pattern](https://www.w3.org/TR/wai-aria-1.2/#separator).


---

### Slider

File: primitives/slider.md
URL: https://angularprimitives.com/primitives/slider

# Slider

Select a value within a range.

## Example

```typescript
import { Component } from '@angular/core';
import { NgpSlider, NgpSliderRange, NgpSliderThumb, NgpSliderTrack } from 'ng-primitives/slider';

@Component({
  selector: 'app-slider',
  imports: [NgpSlider, NgpSliderRange, NgpSliderThumb, NgpSliderTrack],
  styles: `
    [ngpSlider] {
      display: flex;
      position: relative;
      width: 200px;
      height: 20px;
      touch-action: none;
      user-select: none;
      align-items: center;
    }

    [ngpSliderTrack] {
      position: relative;
      height: 5px;
      width: 100%;
      border-radius: 999px;
      background-color: var(--ngp-background-secondary);
    }

    /* Increase the click area of the track without changing its visual size */
    [ngpSliderTrack]::before {
      content: '';
      position: absolute;
      top: 50%;
      left: 0;
      right: 0;
      height: 20px;
      transform: translateY(-50%);
    }

    [ngpSliderRange] {
      position: absolute;
      height: 100%;
      border-radius: 999px;
      background-color: var(--ngp-background-inverse);
    }

    [ngpSliderThumb] {
      position: absolute;
      display: block;
      height: 20px;
      width: 20px;
      border-radius: 10px;
      background-color: white;
      box-shadow: var(--ngp-button-shadow);
      outline: none;
      transform: translateX(-50%);
    }

    [ngpSliderThumb][data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 0;
    }
  `,
  template: `
    <div [(ngpSliderValue)]="value" ngpSlider>
      <div ngpSliderTrack>
        <div ngpSliderRange></div>
      </div>
      <div ngpSliderThumb></div>
    </div>
  `,
})
export default class SliderExample {
  value = 50;
}

```

## Import

Import the Slider primitives from `ng-primitives/slider`.

```ts
import { NgpSlider, NgpSliderTrack, NgpSliderRange, NgpSliderThumb } from 'ng-primitives/slider';
```

## Usage

Assemble the slider directives in your template.

```html
<div ngpSlider>
  <div ngpSliderTrack>
    <div ngpSliderRange></div>
  </div>
  <div ngpSliderThumb></div>
</div>
```

## Reusable Component

Create a reusable component that uses the slider directives.

## Reusable Component

```typescript
import { Component, input } from '@angular/core';
import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
import { ControlValueAccessor } from '@angular/forms';
import {
  injectSliderState,
  NgpSlider,
  NgpSliderRange,
  NgpSliderThumb,
  NgpSliderTrack,
} from 'ng-primitives/slider';
import { ChangeFn, provideValueAccessor, TouchedFn } from 'ng-primitives/utils';

@Component({
  selector: 'app-slider',
  hostDirectives: [
    {
      directive: NgpSlider,
      inputs: [
        'ngpSliderValue:value',
        'ngpSliderMin:min',
        'ngpSliderMax:max',
        'ngpSliderDisabled:disabled',
      ],
      outputs: ['ngpSliderValueChange:valueChange'],
    },
  ],
  imports: [NgpSliderTrack, NgpSliderRange, NgpSliderThumb],
  providers: [provideValueAccessor(Slider)],
  template: `
    <div ngpSliderTrack>
      <div ngpSliderRange></div>
    </div>
    <div [ariaLabel]="ariaLabel()" ngpSliderThumb></div>
  `,
  styles: `
    :host {
      display: flex;
      position: relative;
      width: 200px;
      height: 20px;
      touch-action: none;
      user-select: none;
      align-items: center;
    }

    [ngpSliderTrack] {
      position: relative;
      height: 5px;
      width: 100%;
      border-radius: 999px;
      background-color: var(--ngp-background-secondary);
    }

    [ngpSliderRange] {
      position: absolute;
      height: 100%;
      border-radius: 999px;
      background-color: var(--ngp-background-inverse);
    }

    [ngpSliderThumb] {
      position: absolute;
      display: block;
      height: 20px;
      width: 20px;
      border-radius: 10px;
      background-color: white;
      box-shadow: var(--ngp-button-shadow);
      outline: none;
      transform: translateX(-50%);
    }

    [ngpSliderThumb][data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 0;
    }
  `,
  host: {
    '(focusout)': 'onTouched?.()',
  },
})
export class Slider implements ControlValueAccessor {
  /** Access the slider state */
  private readonly state = injectSliderState();

  /** Forward the aria-label to the thumb */
  readonly ariaLabel = input<string | null>(null, {
    alias: 'aria-label',
  });

  /**
   * The onChange callback function.
   */
  private onChange?: ChangeFn<number>;

  /**
   * The onTouched callback function.
   */
  protected onTouched?: TouchedFn;

  constructor() {
    // Whenever the user interacts with the slider, call the onChange function with the new value.
    this.state()
      .valueChange.pipe(takeUntilDestroyed())
      .subscribe(value => this.onChange?.(value));
  }

  writeValue(value: number): void {
    this.state().setValue(value);
  }

  registerOnChange(fn: ChangeFn<number>): void {
    this.onChange = fn;
  }

  registerOnTouched(fn: TouchedFn): void {
    this.onTouched = fn;
  }

  setDisabledState(isDisabled: boolean): void {
    this.state().setDisabled(isDisabled);
  }
}

```

## Schematics

Generate a reusable slider component using the Angular CLI.

```bash npm
ng g ng-primitives:primitive slider
```

### Options

- `path`: The path at which to create the component file.
- `prefix`: The prefix to apply to the generated component selector.
- `componentSuffix`: The suffix to apply to the generated component class name.
- `fileSuffix`: The suffix to apply to the generated component file name. Defaults to `component`.
- `exampleStyles`: Whether to include example styles in the generated component file. Defaults to `true`.

## Examples

Here are some additional examples of how to use the Slider primitives.

### Vertical Slider

Display the slider in a vertical orientation by setting `ngpSliderOrientation="vertical"`.

## Example

```typescript
import { Component } from '@angular/core';
import { NgpSlider, NgpSliderRange, NgpSliderThumb, NgpSliderTrack } from 'ng-primitives/slider';

@Component({
  selector: 'app-slider-vertical',
  imports: [NgpSlider, NgpSliderRange, NgpSliderThumb, NgpSliderTrack],
  styles: `
    [ngpSlider] {
      display: flex;
      position: relative;
      width: 20px;
      height: 200px;
      touch-action: none;
      user-select: none;
      justify-content: center;
    }

    [ngpSliderTrack] {
      position: relative;
      width: 5px;
      height: 100%;
      border-radius: 999px;
      background-color: var(--ngp-background-secondary);
    }

    /* Increase the click area of the track without changing its visual size */
    [ngpSliderTrack]::before {
      content: '';
      position: absolute;
      left: 50%;
      top: 0;
      bottom: 0;
      width: 20px;
      height: 100%;
      transform: translateX(-50%);
    }

    [ngpSliderRange] {
      position: absolute;
      width: 100%;
      border-radius: 999px;
      background-color: var(--ngp-background-inverse);
    }

    [ngpSliderThumb] {
      position: absolute;
      display: block;
      height: 20px;
      width: 20px;
      border-radius: 10px;
      background-color: white;
      box-shadow: var(--ngp-button-shadow);
      outline: none;
      transform: translateY(-50%);
    }

    [ngpSliderThumb][data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 0;
    }
  `,
  template: `
    <div [(ngpSliderValue)]="value" ngpSlider ngpSliderOrientation="vertical">
      <div ngpSliderTrack>
        <div ngpSliderRange></div>
      </div>
      <div ngpSliderThumb></div>
    </div>
  `,
})
export default class SliderVerticalExample {
  value = 50;
}

```

### Slider Thumb Tooltip

Display the current value in a tooltip that follows the slider thumb. Use `ngpTooltipTriggerTrackPosition` to enable smooth position updates during drag.

## Example

```typescript
import { Component, viewChild } from '@angular/core';
import { NgpSlider, NgpSliderRange, NgpSliderThumb, NgpSliderTrack } from 'ng-primitives/slider';
import { NgpTooltip, NgpTooltipTrigger } from 'ng-primitives/tooltip';

@Component({
  selector: 'app-slider-tooltip',
  imports: [
    NgpSlider,
    NgpSliderRange,
    NgpSliderThumb,
    NgpSliderTrack,
    NgpTooltipTrigger,
    NgpTooltip,
  ],
  styles: `
    :host {
      display: block;
    }

    [ngpSlider] {
      display: flex;
      position: relative;
      width: 200px;
      height: 20px;
      touch-action: none;
      user-select: none;
      align-items: center;
    }

    [ngpSliderTrack] {
      position: relative;
      height: 5px;
      width: 100%;
      border-radius: 999px;
      background-color: var(--ngp-background-secondary);
    }

    /* Increase the click area of the track without changing its visual size */
    [ngpSliderTrack]::before {
      content: '';
      position: absolute;
      top: 50%;
      left: 0;
      right: 0;
      height: 20px;
      transform: translateY(-50%);
    }

    [ngpSliderRange] {
      position: absolute;
      height: 100%;
      border-radius: 999px;
      background-color: var(--ngp-background-inverse);
    }

    [ngpSliderThumb] {
      position: absolute;
      display: block;
      height: 20px;
      width: 20px;
      border-radius: 10px;
      background-color: white;
      box-shadow: var(--ngp-button-shadow);
      outline: none;
      transform: translateX(-50%);
    }

    [ngpSliderThumb][data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 0;
    }

    ::ng-deep .ngp-slider-tooltip {
      position: absolute;
      border-radius: 0.25rem;
      background-color: var(--ngp-background-inverse);
      padding: 0.25rem 0.5rem;
      border: none;
      font-size: 0.75rem;
      font-weight: 500;
      color: var(--ngp-text-inverse);
      white-space: nowrap;
    }
  `,
  template: `
    <div [(ngpSliderValue)]="value" ngpSlider>
      <div ngpSliderTrack>
        <div ngpSliderRange></div>
      </div>
      <div
        #tooltipTrigger="ngpTooltipTrigger"
        [ngpTooltipTrigger]="tooltip"
        (pointerenter)="onThumbPointerEnter()"
        (pointerleave)="onThumbPointerLeave()"
        (focus)="onThumbFocus()"
        (blur)="onThumbBlur()"
        (ngpSliderThumbDragStart)="onThumbDragStart()"
        (ngpSliderThumbDragEnd)="onThumbDragEnd()"
        ngpTooltipTriggerPlacement="top"
        ngpTooltipTriggerHideDelay="0"
        ngpTooltipTriggerTrackPosition="true"
        ngpTooltipTriggerDisabled="true"
        ngpSliderThumb
      ></div>
    </div>

    <ng-template #tooltip>
      <div class="ngp-slider-tooltip" ngpTooltip>{{ value }}</div>
    </ng-template>
  `,
})
export default class SliderTooltipExample {
  readonly tooltipTrigger = viewChild.required<NgpTooltipTrigger>('tooltipTrigger');

  value = 50;
  private isDragging = false;
  private isHovered = false;
  private isFocused = false;

  onThumbPointerEnter(): void {
    this.isHovered = true;
    this.tooltipTrigger().show();
  }

  onThumbPointerLeave(): void {
    this.isHovered = false;
    if (!this.isDragging && !this.isFocused) {
      this.tooltipTrigger().hide();
    }
  }

  onThumbFocus(): void {
    this.isFocused = true;
    this.tooltipTrigger().show();
  }

  onThumbBlur(): void {
    this.isFocused = false;
    if (!this.isDragging && !this.isHovered) {
      this.tooltipTrigger().hide();
    }
  }

  onThumbDragStart(): void {
    this.isDragging = true;
    this.tooltipTrigger().show();
  }

  onThumbDragEnd(): void {
    this.isDragging = false;
    if (!this.isHovered && !this.isFocused) {
      this.tooltipTrigger().hide();
    }
  }
}

```

### Slider Track Tooltip

Display a preview tooltip as you hover over the track, showing what value would be selected at that position. The tooltip also appears on the thumb during drag. Uses `ngpTooltipTriggerPosition` for programmatic positioning.

## Example

```typescript
import { Component, ElementRef, signal, viewChild } from '@angular/core';
import { NgpSlider, NgpSliderRange, NgpSliderThumb, NgpSliderTrack } from 'ng-primitives/slider';
import { NgpTooltip, NgpTooltipTrigger } from 'ng-primitives/tooltip';

@Component({
  selector: 'app-slider-track-tooltip',
  imports: [
    NgpSlider,
    NgpSliderRange,
    NgpSliderThumb,
    NgpSliderTrack,
    NgpTooltipTrigger,
    NgpTooltip,
  ],
  styles: `
    :host {
      display: block;
    }

    [ngpSlider] {
      display: flex;
      position: relative;
      width: 200px;
      height: 20px;
      touch-action: none;
      user-select: none;
      align-items: center;
    }

    [ngpSliderTrack] {
      position: relative;
      height: 5px;
      width: 100%;
      border-radius: 999px;
      background-color: var(--ngp-background-secondary);
    }

    /* Increase the click area of the track without changing its visual size */
    [ngpSliderTrack]::before {
      content: '';
      position: absolute;
      top: 50%;
      left: 0;
      right: 0;
      height: 20px;
      transform: translateY(-50%);
    }

    [ngpSliderRange] {
      position: absolute;
      height: 100%;
      border-radius: 999px;
      background-color: var(--ngp-background-inverse);
    }

    [ngpSliderThumb] {
      position: absolute;
      display: block;
      height: 20px;
      width: 20px;
      border-radius: 10px;
      background-color: white;
      box-shadow: var(--ngp-button-shadow);
      outline: none;
      transform: translateX(-50%);
    }

    [ngpSliderThumb][data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 0;
    }

    ::ng-deep .ngp-slider-track-tooltip {
      position: absolute;
      border-radius: 0.25rem;
      background-color: var(--ngp-background-inverse);
      padding: 0.25rem 0.5rem;
      border: none;
      font-size: 0.75rem;
      font-weight: 500;
      color: var(--ngp-text-inverse);
      white-space: nowrap;
    }

    ::ng-deep .ngp-slider-thumb-tooltip {
      position: absolute;
      border-radius: 0.25rem;
      background-color: var(--ngp-background-inverse);
      padding: 0.25rem 0.5rem;
      border: none;
      font-size: 0.75rem;
      font-weight: 500;
      color: var(--ngp-text-inverse);
      white-space: nowrap;
    }
  `,
  template: `
    <div [(ngpSliderValue)]="value" ngpSlider>
      <div
        #track
        #trackTooltipTrigger="ngpTooltipTrigger"
        [ngpTooltipTrigger]="trackTooltip"
        [ngpTooltipTriggerPosition]="trackTooltipPosition()"
        (pointerenter)="onTrackPointerEnter($event)"
        (pointermove)="onTrackPointerMove($event)"
        (pointerleave)="onTrackPointerLeave()"
        ngpTooltipTriggerTrackPosition="true"
        ngpTooltipTriggerDisabled="true"
        ngpTooltipTriggerPlacement="top"
        ngpTooltipTriggerOffset="14"
        ngpTooltipTriggerShowDelay="0"
        ngpTooltipTriggerHideDelay="0"
        ngpSliderTrack
      >
        <div ngpSliderRange></div>
      </div>
      <div
        #thumbTooltipTrigger="ngpTooltipTrigger"
        [ngpTooltipTrigger]="thumbTooltip"
        (pointerenter)="onThumbPointerEnter()"
        (pointerleave)="onThumbPointerLeave()"
        (focus)="onThumbFocus()"
        (blur)="onThumbBlur()"
        (ngpSliderThumbDragStart)="onThumbDragStart()"
        (ngpSliderThumbDragEnd)="onThumbDragEnd()"
        ngpTooltipTriggerPlacement="top"
        ngpTooltipTriggerHideDelay="0"
        ngpTooltipTriggerTrackPosition="true"
        ngpTooltipTriggerDisabled="true"
        ngpSliderThumb
      ></div>
    </div>

    <ng-template #trackTooltip>
      <div class="ngp-slider-track-tooltip" ngpTooltip>{{ previewValue() }}</div>
    </ng-template>

    <ng-template #thumbTooltip>
      <div class="ngp-slider-thumb-tooltip" ngpTooltip>{{ value }}</div>
    </ng-template>
  `,
})
export default class SliderTrackTooltipExample {
  readonly track = viewChild.required<ElementRef<HTMLElement>>('track');
  readonly trackTooltipTrigger = viewChild.required<NgpTooltipTrigger>('trackTooltipTrigger');
  readonly thumbTooltipTrigger = viewChild.required<NgpTooltipTrigger>('thumbTooltipTrigger');

  readonly trackTooltipPosition = signal<{ x: number; y: number } | null>(null);
  readonly previewValue = signal(0);

  value = 50;
  private readonly min = 0;
  private readonly max = 100;
  private isDragging = false;
  private isThumbHovered = false;
  private isThumbFocused = false;

  onTrackPointerEnter(event: PointerEvent): void {
    if (!this.isThumbActive()) {
      this.updateTrackTooltip(event);
      this.trackTooltipTrigger().show();
    }
  }

  onTrackPointerMove(event: PointerEvent): void {
    if (this.isThumbActive()) {
      return;
    }
    this.updateTrackTooltip(event);
  }

  private updateTrackTooltip(event: PointerEvent): void {
    const trackElement = this.track().nativeElement;
    const rect = trackElement.getBoundingClientRect();

    // Calculate percentage position along the track
    const percentage = Math.max(0, Math.min(1, (event.clientX - rect.left) / rect.width));

    // Calculate the preview value
    const previewValue = Math.round(this.min + percentage * (this.max - this.min));
    this.previewValue.set(previewValue);

    // Update tooltip position - X follows cursor, Y fixed at track center
    const trackCenterY = rect.top + rect.height / 2;
    this.trackTooltipPosition.set({ x: event.clientX, y: trackCenterY });
  }

  onTrackPointerLeave(): void {
    if (!this.isThumbActive()) {
      this.trackTooltipTrigger().hide();
    }
  }

  onThumbPointerEnter(): void {
    this.isThumbHovered = true;
    this.trackTooltipTrigger().hide();
    this.thumbTooltipTrigger().show();
  }

  onThumbPointerLeave(): void {
    this.isThumbHovered = false;
    if (!this.isDragging && !this.isThumbFocused) {
      this.thumbTooltipTrigger().hide();
    }
  }

  onThumbFocus(): void {
    this.isThumbFocused = true;
    this.trackTooltipTrigger().hide();
    this.thumbTooltipTrigger().show();
  }

  onThumbBlur(): void {
    this.isThumbFocused = false;
    if (!this.isDragging && !this.isThumbHovered) {
      this.thumbTooltipTrigger().hide();
    }
  }

  onThumbDragStart(): void {
    this.isDragging = true;
    this.trackTooltipTrigger().hide();
    this.thumbTooltipTrigger().show();
  }

  onThumbDragEnd(): void {
    this.isDragging = false;
    if (!this.isThumbHovered && !this.isThumbFocused) {
      this.thumbTooltipTrigger().hide();
    }
  }

  private isThumbActive(): boolean {
    return this.isDragging || this.isThumbHovered || this.isThumbFocused;
  }
}

```

### Slider Form Field

The slider automatically integrates with the form field primitives.

## Example

```typescript
import { Component } from '@angular/core';
import { NgpDescription, NgpFormField, NgpLabel } from 'ng-primitives/form-field';
import { NgpSlider, NgpSliderRange, NgpSliderThumb, NgpSliderTrack } from 'ng-primitives/slider';

@Component({
  selector: 'app-slider-form-field',
  imports: [
    NgpFormField,
    NgpLabel,
    NgpDescription,
    NgpSlider,
    NgpSliderRange,
    NgpSliderThumb,
    NgpSliderTrack,
  ],
  styles: `
    :host {
      display: contents;
    }

    [ngpFormField] {
      display: flex;
      flex-direction: column;
      gap: 6px;
    }

    [ngpLabel] {
      color: var(--ngp-text-primary);
      font-size: 0.875rem;
      line-height: 1.25rem;
      font-weight: 500;
      margin: 0;
    }

    [ngpDescription] {
      color: var(--ngp-text-secondary);
      font-size: 0.75rem;
      line-height: 1rem;
      margin: 0 0 4px;
    }

    [ngpSlider] {
      display: flex;
      position: relative;
      width: 200px;
      height: 20px;
      touch-action: none;
      user-select: none;
      align-items: center;
    }

    [ngpSliderTrack] {
      position: relative;
      height: 5px;
      width: 100%;
      border-radius: 999px;
      background-color: var(--ngp-background-secondary);
    }

    /* Increase the click area of the track without changing its visual size */
    [ngpSliderTrack]::before {
      content: '';
      position: absolute;
      top: 50%;
      left: 0;
      right: 0;
      height: 20px;
      transform: translateY(-50%);
    }

    [ngpSliderRange] {
      position: absolute;
      height: 100%;
      border-radius: 999px;
      background-color: var(--ngp-background-inverse);
    }

    [ngpSliderThumb] {
      position: absolute;
      display: block;
      height: 20px;
      width: 20px;
      border-radius: 10px;
      background-color: white;
      box-shadow: var(--ngp-button-shadow);
      outline: none;
      transform: translateX(-50%);
    }

    [ngpSliderThumb][data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 0;
    }
  `,
  template: `
    <div ngpFormField>
      <label ngpLabel>Volume</label>
      <p ngpDescription>Adjust the volume of the speaker.</p>

      <div [(ngpSliderValue)]="value" ngpSlider>
        <div ngpSliderTrack>
          <div ngpSliderRange></div>
        </div>
        <div ngpSliderThumb></div>
      </div>
    </div>
  `,
})
export default class SliderFormFieldExample {
  value = 50;
}

```

## API Reference

The following directives are available to import from the `ng-primitives/slider` package:

### NgpSlider

## API Reference

### NgpSlider

Apply the `ngpSlider` directive to an element that represents the slider and contains the track, range, and thumb.

**Selector:** `[ngpSlider]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpSliderValue` | `number` | `-` | The value of the slider. |
| `ngpSliderMin` | `number` | `-` | The minimum value of the slider. |
| `ngpSliderMax` | `number` | `-` | The maximum value of the slider. |
| `ngpSliderStep` | `number` | `-` | The step value of the slider. |
| `ngpSliderOrientation` | `NgpOrientation` | `-` | The orientation of the slider. |
| `ngpSliderDisabled` | `boolean` | `-` | The disabled state of the slider. |

#### Outputs

| Event | Type | Description |
|-------|------|-------------|
| `ngpSliderValueChange` | `number` | Emits when the value changes. |

#### Export As

`ngpSlider`



#### Data Attributes

The following data attributes are available to style the slider:

| Attribute          | Description                          | Value                      |
| ------------------ | ------------------------------------ | -------------------------- |
| `data-disabled`    | Applied when the slider is disabled. | `-`                        |
| `data-orientation` | The orientation of the slider.       | `horizontal` \| `vertical` |

### NgpSliderTrack

## API Reference

### NgpSliderTrack

Apply the `ngpSliderTrack` directive to an element that represents the track of the slider.

**Selector:** `[ngpSliderTrack]`

#### Export As

`ngpSliderTrack`



#### Data Attributes

The following data attributes are available to style the slider track:

| Attribute          | Description                          | Value                      |
| ------------------ | ------------------------------------ | -------------------------- |
| `data-disabled`    | Applied when the slider is disabled. | `-`                        |
| `data-orientation` | The orientation of the slider.       | `horizontal` \| `vertical` |

### NgpSliderRange

## API Reference

### NgpSliderRange

Apply the `ngpSliderRange` directive to an element that represents the range of the slider.

**Selector:** `[ngpSliderRange]`

#### Export As

`ngpSliderRange`



#### Data Attributes

The following data attributes are available to style the slider range:

| Attribute          | Description                          | Value                      |
| ------------------ | ------------------------------------ | -------------------------- |
| `data-disabled`    | Applied when the slider is disabled. | `-`                        |
| `data-orientation` | The orientation of the slider.       | `horizontal` \| `vertical` |

### NgpSliderThumb

## API Reference

### NgpSliderThumb

Apply the `ngpSliderThumb` directive to an element that represents the thumb of the slider.

**Selector:** `[ngpSliderThumb]`

#### Outputs

| Event | Type | Description |
|-------|------|-------------|
| `ngpSliderThumbDragStart` | `void` | Emits when the thumb drag starts. |
| `ngpSliderThumbDragEnd` | `void` | Emits when the thumb drag ends. |

#### Export As

`ngpSliderThumb`



#### Data Attributes

The following data attributes are available to style the thumb:

| Attribute            | Description                               | Value                      |
| -------------------- | ----------------------------------------- | -------------------------- |
| `data-orientation`   | The orientation of the slider.            | `horizontal` \| `vertical` |
| `data-disabled`      | Applied when the slider is disabled.      | `-`                        |
| `data-hover`         | Applied when the slider thumb is hovered. | `-`                        |
| `data-focus-visible` | Applied when the slider thumb is focused. | `-`                        |
| `data-press`         | Applied when the slider thumb is pressed. | `-`                        |

## API Reference

The following directives are available to import from the `ng-primitives/slider` package:

## Accessibility

Adheres to the [Slider WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/slider-multithumb).

### Keyboard Interactions

- <kbd>Left Arrow</kbd> or <kbd>Down Arrow</kbd>: Decrease the value by the step.
- <kbd>Right Arrow</kbd> or <kbd>Up Arrow</kbd>: Increase the value by the step.
- <kbd>Left Arrow</kbd> or <kbd>Down Arrow</kbd> + <kbd>Shift</kbd>: Decrease the value by the step by a larger amount.
- <kbd>Right Arrow</kbd> or <kbd>Up Arrow</kbd> + <kbd>Shift</kbd>: Increase the value by the step by a larger amount.
- <kbd>Home</kbd>: Set the value to the minimum.
- <kbd>End</kbd>: Set the value to the maximum.


---

### Switch

File: primitives/switch.md
URL: https://angularprimitives.com/primitives/switch

# Switch

Perform state toggling.

## Example

```typescript
import { Component } from '@angular/core';
import { NgpSwitch, NgpSwitchThumb } from 'ng-primitives/switch';

@Component({
  selector: 'app-switch',
  imports: [NgpSwitch, NgpSwitchThumb],
  styles: `
    [ngpSwitch] {
      position: relative;
      width: 2.5rem;
      height: 1.5rem;
      border-radius: 999px;
      background-color: var(--ngp-background-secondary);
      border: 1px solid var(--ngp-border);
      padding: 0;
      outline: none;
      transition-property:
        color, background-color, border-color, text-decoration-color, fill, stroke;
      transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
      transition-duration: 150ms;
    }

    [ngpSwitch][data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
    }

    [ngpSwitch][data-checked] {
      background-color: var(--ngp-background-blue);
      border-color: var(--ngp-border-blue);
    }

    [ngpSwitchThumb] {
      display: block;
      height: 1.25rem;
      width: 1.25rem;
      border-radius: 999px;
      background-color: white;
      box-shadow: var(--ngp-button-shadow);
      outline: none;
      transition: transform 150ms cubic-bezier(0.4, 0, 0.2, 1);
      transform: translateX(1px);
    }

    [ngpSwitchThumb][data-checked] {
      transform: translateX(17px);
    }
  `,
  template: `
    <button ngpSwitch>
      <span ngpSwitchThumb></span>
    </button>
  `,
})
export default class SwitchExample {}

```

## Import

Import the Switch primitives from `ng-primitives/switch`.

```ts
import { NgpSwitch, NgpSwitchThumb } from 'ng-primitives/switch';
```

## Usage

Assemble the switch directives in your template.

```html
<button ngpSwitch [(ngpSwitchChecked)]="checked">
  <span ngpSwitchThumb></span>
</button>
```

## Reusable Component

Create a reusable component that uses the switch directives.

## Reusable Component

```typescript
import { Component } from '@angular/core';
import { ControlValueAccessor } from '@angular/forms';
import { injectSwitchState, NgpSwitch, NgpSwitchThumb } from 'ng-primitives/switch';
import { ChangeFn, provideValueAccessor, TouchedFn } from 'ng-primitives/utils';

@Component({
  selector: 'app-switch',
  hostDirectives: [
    {
      directive: NgpSwitch,
      inputs: ['ngpSwitchChecked:checked', 'ngpSwitchDisabled:disabled'],
      outputs: ['ngpSwitchCheckedChange:checkedChange'],
    },
  ],
  imports: [NgpSwitchThumb],
  template: `
    <span ngpSwitchThumb></span>
  `,
  styles: `
    :host {
      display: inline-flex;
      align-items: center;
      position: relative;
      width: 2.5rem;
      height: 1.5rem;
      border-radius: 999px;
      background-color: var(--ngp-background-secondary);
      border: 1px solid var(--ngp-border);
      padding: 0;
      outline: none;
      transition-property:
        color, background-color, border-color, text-decoration-color, fill, stroke;
      transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
      transition-duration: 150ms;
      box-sizing: border-box;
    }

    :host[data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
    }

    :host[data-checked] {
      background-color: var(--ngp-background-blue);
      border-color: var(--ngp-border-blue);
    }

    [ngpSwitchThumb] {
      display: block;
      height: 1.25rem;
      width: 1.25rem;
      border-radius: 999px;
      background-color: white;
      box-shadow: var(--ngp-button-shadow);
      outline: none;
      transition: transform 150ms cubic-bezier(0.4, 0, 0.2, 1);
      transform: translateX(1px);
      box-sizing: border-box;
    }

    [ngpSwitchThumb][data-checked] {
      transform: translateX(17px);
    }
  `,
  providers: [provideValueAccessor(Switch)],
  host: {
    '(focusout)': 'onTouched?.()',
  },
})
export class Switch implements ControlValueAccessor {
  /** Access the switch state. */
  private readonly switch = injectSwitchState();

  /** The on change callback */
  private onChange?: ChangeFn<boolean>;

  /** The on touched callback */
  protected onTouched?: TouchedFn;

  constructor() {
    // Any time the switch changes, update the form value.
    this.switch().checkedChange.subscribe(value => this.onChange?.(value));
  }

  /** Write a new value to the switch. */
  writeValue(value: boolean): void {
    this.switch().setChecked(value);
  }

  /** Register a callback function to be called when the value changes. */
  registerOnChange(fn: ChangeFn<boolean>): void {
    this.onChange = fn;
  }

  /** Register a callback function to be called when the switch is touched. */
  registerOnTouched(fn: TouchedFn): void {
    this.onTouched = fn;
  }

  /** Set the disabled state of the switch. */
  setDisabledState(isDisabled: boolean): void {
    this.switch().setDisabled(isDisabled);
  }
}

```

## Schematics

Generate a reusable switch component using the Angular CLI.

```bash npm
ng g ng-primitives:primitive switch
```

### Options

- `path`: The path at which to create the component file.
- `prefix`: The prefix to apply to the generated component selector.
- `componentSuffix`: The suffix to apply to the generated component class name.
- `fileSuffix`: The suffix to apply to the generated component file name. Defaults to `component`.
- `exampleStyles`: Whether to include example styles in the generated component file. Defaults to `true`.

## Examples

Here are some additional examples of how to use the Switch primitives.

### Switch Form Field

The switch automatically integrates with the form field primitives.

## Example

```typescript
import { Component } from '@angular/core';
import { NgpFormField, NgpLabel } from 'ng-primitives/form-field';
import { NgpSwitch, NgpSwitchThumb } from 'ng-primitives/switch';

@Component({
  selector: 'app-switch-form-field',
  imports: [NgpSwitch, NgpSwitchThumb, NgpFormField, NgpLabel],
  styles: `
    [ngpFormField] {
      display: flex;
      align-items: center;
      gap: 1rem;
    }

    [ngpLabel] {
      font-weight: 500;
      color: var(--ngp-text-primary);
    }

    [ngpSwitch] {
      position: relative;
      width: 2.5rem;
      height: 1.5rem;
      border-radius: 999px;
      background-color: var(--ngp-background-secondary);
      border: 1px solid var(--ngp-border);
      padding: 0;
      outline: none;
      transition-property:
        color, background-color, border-color, text-decoration-color, fill, stroke;
      transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
      transition-duration: 150ms;
    }

    [ngpSwitch][data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
    }

    [ngpSwitch][data-checked] {
      background-color: var(--ngp-background-blue);
      border-color: var(--ngp-border-blue);
    }

    [ngpSwitchThumb] {
      display: block;
      height: 1.25rem;
      width: 1.25rem;
      border-radius: 999px;
      background-color: white;
      box-shadow: var(--ngp-button-shadow);
      outline: none;
      transition: transform 150ms cubic-bezier(0.4, 0, 0.2, 1);
      transform: translateX(1px);
    }

    [ngpSwitchThumb][data-checked] {
      transform: translateX(17px);
    }
  `,
  template: `
    <div ngpFormField>
      <label ngpLabel>Mobile Data</label>
      <button ngpSwitch>
        <span ngpSwitchThumb></span>
      </button>
    </div>
  `,
})
export default class SwitchFormFieldExample {}

```

## API Reference

The following directives are available to import from the `ng-primitives/switch` package:

### NgpSwitch

## API Reference

### NgpSwitch

Apply the `ngpSwitch` directive to an element to manage the checked state.

**Selector:** `[ngpSwitch]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpSwitchChecked` | `boolean` | `false` | Determine if the switch is checked. |
| `ngpSwitchDisabled` | `boolean` | `false` | Determine if the switch is disabled. |

#### Outputs

| Event | Type | Description |
|-------|------|-------------|
| `ngpSwitchCheckedChange` | `boolean` | Emits when the checked state changes. |

#### Export As

`ngpSwitch`



#### Data Attributes

The following data attributes are applied to the `ngpSwitch` directive:

| Attribute            | Description                          |
| -------------------- | ------------------------------------ |
| `data-checked`       | Applied when the switch is checked.  |
| `data-disabled`      | Applied when the switch is disabled. |
| `data-hover`         | Applied when the switch is hovered.  |
| `data-focus-visible` | Applied when the switch is focused.  |
| `data-press`         | Applied when the switch is pressed.  |

### NgpSwitchThumb

## API Reference

### NgpSwitchThumb

Apply the `ngpSwitchThumb` directive to an element within a switch to represent the thumb.

**Selector:** `[ngpSwitchThumb]`



#### Data Attributes

The following data attributes are available to style the thumb:

| Attribute            | Description                               |
| -------------------- | ----------------------------------------- |
| `data-checked`       | Applied when the switch is checked.       |
| `data-disabled`      | Applied when the switch is disabled.      |
| `data-hover`         | Applied when the switch thumb is hovered. |
| `data-focus-visible` | Applied when the switch thumb is focused. |
| `data-press`         | Applied when the switch thumb is pressed. |

## Accessibility

Adheres to the [WAI-ARIA switch design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/switch/).

### Keyboard Interactions

- <kbd>Space</kbd> - Toggle the switch state (when switch is a button).
- <kbd>Enter</kbd> - Toggle the switch state.


---

### Table

File: primitives/table.md
URL: https://angularprimitives.com/primitives/table

# Table

While tables are a very common UI element, we currently do not provide a dedicated table primitive in Angular Primitives.

The main reason is that building a flexible, accessible, and fully-featured table component is a large and complex undertaking. There is already an excellent, battle-tested solution available: [TanStack Table](https://tanstack.com/table/latest/docs/framework/angular/).

TanStack Table is a headless table library that works very well alongside Angular Primitives. It provides all the core functionality you need for rendering tables (sorting, filtering, pagination, virtualization, etc.) without forcing a specific UI style, making it a perfect complement to our approach, and you can use it in conjunction with any of our UI primitives such as pagination etc.

## Why we don't provide a table primitive

**Complexity**: A table primitive is a large, feature-rich component that requires significant ongoing maintenance.

**No clear advantage**: TanStack Table already provides a highly capable solution. At the moment, we don't see how we could offer a better alternative.

**Focus on other primitives**: Our time and efforts are better spent providing primitives that don't already have great solutions elsewhere.

We may revisit this decision in the future, but for now, we recommend using TanStack Table alongside Angular Primitives for any table needs.


---

### Tabs

File: primitives/tabs.md
URL: https://angularprimitives.com/primitives/tabs

# Tabs

Dynamically show and hide content based on an active tab.

## Example

```typescript
import { Component, signal } from '@angular/core';
import { NgpTabButton, NgpTabList, NgpTabPanel, NgpTabset } from 'ng-primitives/tabs';

@Component({
  selector: 'app-tabs',
  imports: [NgpTabset, NgpTabList, NgpTabButton, NgpTabPanel],
  styles: `
    :host {
      display: contents;
    }

    [ngpTabset] {
      width: 100%;
      max-width: 512px;
      border-radius: 0.75rem;
      background-color: var(--ngp-background);
      padding: 0.25rem 1rem;
      box-shadow: var(--ngp-button-shadow);
    }

    [ngpTabList] {
      display: flex;
      gap: 1.5rem;
      border-bottom: 1px solid var(--ngp-border);
    }

    [ngpTabButton] {
      border: none;
      background-color: transparent;
      margin-bottom: -1px;
      border-bottom: 2px solid transparent;
      padding: 0.5rem 0;
      outline: none;
      transition: background-color 150ms cubic-bezier(0.4, 0, 0.2, 1);
    }

    [ngpTabButton][data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 2px;
    }

    [ngpTabButton][data-active] {
      border-color: var(--ngp-background-inverse);
      color: var(--ngp-text-primary);
    }

    [ngpTabButton][data-disabled] {
      color: var(--ngp-text-disabled);
      cursor: not-allowed;
    }

    [ngpTabPanel] {
      padding: 0.5rem 0;
      outline: none;
    }

    [ngpTabPanel]:not([data-active]) {
      display: none;
    }
  `,
  template: `
    <div [(ngpTabsetValue)]="selectedTab" ngpTabset>
      <div ngpTabList>
        <button ngpTabButton ngpTabButtonValue="overview">Overview</button>
        <button ngpTabButton ngpTabButtonValue="features">Features</button>
        <button ngpTabButton ngpTabButtonValue="pricing">Pricing</button>
        <button ngpTabButton ngpTabButtonValue="disabled" ngpTabButtonDisabled>Disabled</button>
      </div>

      <div ngpTabPanel ngpTabPanelValue="overview">
        <p>
          Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam ultricies lacinia arcu,
          in dignissim magna mollis in. Proin ac faucibus sem. Aliquam sit amet augue non risus
          commodo volutpat id sit amet nisi. Integer posuere nisl in ligula faucibus vestibulum.
          Nulla facilisi. Aliquam erat volutpat.
        </p>
      </div>

      <div ngpTabPanel ngpTabPanelValue="features">
        <p>
          Cras eget sem ac velit pellentesque lobortis at in ex. Vestibulum nisl diam, eleifend eget
          malesuada a, cursus id ante. Morbi fringilla, metus nec consectetur maximus, leo purus
          gravida est, eu fringilla dui quam fermentum sapien. Vivamus tempus ullamcorper lectus,
          nec cursus sapien consectetur vel.
        </p>
      </div>

      <div ngpTabPanel ngpTabPanelValue="pricing">
        <p>
          Praesent vehicula erat ac massa egestas viverra. Pellentesque urna magna, consectetur
          convallis ante vel, posuere aliquet arcu. Duis eu nulla id sapien lobortis bibendum eget
          vel velit. Donec sed nisi ac lacus placerat iaculis. Donec blandit eros sit amet nibh
          accumsan cursus. Morbi sit amet ex et enim tempus porttitor non eu erat.
        </p>
      </div>

      <div ngpTabPanel ngpTabPanelValue="disabled">
        <p>Disabled content</p>
      </div>
    </div>
  `,
})
export default class TabsExample {
  /**
   * The selected tab
   */
  readonly selectedTab = signal<Tab>('overview');
}

type Tab = 'overview' | 'features' | 'pricing';

```

## Import

Import the Tabs primitives from `ng-primitives/tabs`.

```ts
import { NgpTabset, NgpTabList, NgpTabButton, NgpTabPanel } from 'ng-primitives/tabs';
```

## Usage

Assemble the tabs directives in your template.

```html
<div ngpTabset>
  <div ngpTabList>
    <button ngpTabButton ngpTabButtonValue="tab1">Tab 1</button>
    <button ngpTabButton ngpTabButtonValue="tab2">Tab 2</button>
    <button ngpTabButton ngpTabButtonValue="tab3">Tab 3</button>
  </div>
  <div ngpTabPanel ngpTabPanelValue="tab1">Tab 1 content</div>
  <div ngpTabPanel ngpTabPanelValue="tab2">Tab 2 content</div>
  <div ngpTabPanel ngpTabPanelValue="tab3">Tab 3 content</div>
</div>
```

## Reusable Component

Create reusable components that uses the tab directives.

## Reusable Component

```typescript
import { NgTemplateOutlet } from '@angular/common';
import { Component, contentChildren, model } from '@angular/core';
import { NgpTabButton, NgpTabList, NgpTabPanel, NgpTabset } from 'ng-primitives/tabs';
import { Tab } from './tab';

@Component({
  selector: 'app-tabs',
  imports: [NgpTabset, NgpTabButton, NgpTabList, NgpTabPanel, NgTemplateOutlet],
  template: `
    <div [(ngpTabsetValue)]="value" ngpTabset>
      <div ngpTabList>
        @for (tab of tabs(); track tab.label()) {
          <button [ngpTabButtonValue]="tab.value()" ngpTabButton>{{ tab.label() }}</button>
        }
      </div>

      @for (tab of tabs(); track tab.label()) {
        <div [ngpTabPanelValue]="tab.value()" ngpTabPanel>
          <ng-container [ngTemplateOutlet]="tab.content()" />
        </div>
      }
    </div>
  `,
  styles: `
    [ngpTabset] {
      width: 100%;
      max-width: 512px;
      border-radius: 0.75rem;
      background-color: var(--ngp-background);
      padding: 0.25rem 1rem;
      box-shadow: var(--ngp-button-shadow);
    }

    [ngpTabList] {
      display: flex;
      gap: 1.5rem;
      border-bottom: 1px solid var(--ngp-border);
    }

    [ngpTabButton] {
      border: none;
      background-color: transparent;
      margin-bottom: -1px;
      border-bottom: 2px solid transparent;
      padding: 0.5rem 0;
      outline: none;
      transition: background-color 150ms cubic-bezier(0.4, 0, 0.2, 1);
    }

    [ngpTabButton][data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 2px;
    }

    [ngpTabButton][data-active] {
      border-color: var(--ngp-background-inverse);
      color: var(--ngp-text-primary);
    }

    [ngpTabPanel] {
      padding: 0.5rem 0;
      outline: none;
    }

    [ngpTabPanel]:not([data-active]) {
      display: none;
    }
  `,
})
export class Tabs {
  /**
   * The value of the selected tab.
   */
  readonly value = model<string>();

  /**
   * The tabs in the group.
   */
  readonly tabs = contentChildren(Tab);
}

```

## Schematics

Generate a reusable tab components using the Angular CLI.

```bash npm
ng g ng-primitives:primitive tabs
```

### Options

- `path`: The path at which to create the component file.
- `prefix`: The prefix to apply to the generated component selector.
- `componentSuffix`: The suffix to apply to the generated component class name.
- `fileSuffix`: The suffix to apply to the generated component file name. Defaults to `component`.
- `exampleStyles`: Whether to include example styles in the generated component file. Defaults to `true`.

## API Reference

The following directives are available to import from the `ng-primitives/tabs` package:

### NgpTabset

## API Reference

### NgpTabset

Apply the `ngpTabset` directive to an element to manage the tabs.

**Selector:** `[ngpTabset]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpTabsetValue` | `string | undefined` | `-` | Define the active tab |
| `ngpTabsetOrientation` | `NgpOrientation` | `'horizontal'` | The orientation of the tabset |
| `ngpTabsetActivateOnFocus` | `boolean` | `-` | Whether tabs should activate on focus |

#### Outputs

| Event | Type | Description |
|-------|------|-------------|
| `ngpTabsetValueChange` | `string | undefined` | Emit the value of the selected tab when it changes |

#### Export As

`ngpTabset`



#### Data Attributes

The following data attributes are applied to the `ngpTabset` directive:

| Attribute          | Description                  | Value                      |
| ------------------ | ---------------------------- | -------------------------- |
| `data-orientation` | The orientation of the tabs. | `horizontal` \| `vertical` |

### NgpTabList

## API Reference

### NgpTabList

Apply the `ngpTabList` directive to an element that represents the list of tab buttons.

**Selector:** `[ngpTabList]`

#### Export As

`ngpTabList`



#### Data Attributes

The following data attributes are applied to the `ngpTabList` directive:

| Attribute          | Description                  | Value                      |
| ------------------ | ---------------------------- | -------------------------- |
| `data-orientation` | The orientation of the tabs. | `horizontal` \| `vertical` |

### NgpTabButton

## API Reference

### NgpTabButton

Apply the `ngpTabButton` directive to an element within a tab list to represent a tab button. This directive should be applied to a button element.

**Selector:** `[ngpTabButton]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpTabButtonValue` | `string | undefined` | `-` | The value of the tab this trigger controls |
| `ngpTabButtonDisabled` | `boolean` | `false` | Whether the tab is disabled |

#### Export As

`ngpTabButton`



#### Data Attributes

The following data attributes are applied to the `ngpTabButton` directive:

| Attribute            | Description                       | Value                      |
| -------------------- | --------------------------------- | -------------------------- |
| `data-orientation`   | The orientation of the tabs.      | `horizontal` \| `vertical` |
| `data-active`        | Applied when the tab is active.   | `-`                        |
| `data-disabled`      | Applied when the tab is disabled. | `-`                        |
| `data-hover`         | Applied when the tab is hovered.  | `-`                        |
| `data-focus-visible` | Applied when the tab is focused.  | `-`                        |
| `data-press`         | Applied when the tab is pressed.  | `-`                        |

### NgpTabPanel

## API Reference

### NgpTabPanel

Apply the `ngpTabPanel` directive to an element that represents the content of a tab.

**Selector:** `[ngpTabPanel]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpTabPanelValue` | `string | undefined` | `-` | The value of the tab |

#### Export As

`ngpTabPanel`



#### Data Attributes

The following data attributes are applied to the `ngpTabPanel` directive:

| Attribute          | Description                     | Value                      |
| ------------------ | ------------------------------- | -------------------------- |
| `data-active`      | Applied when the tab is active. | `-`                        |
| `data-orientation` | The orientation of the tabs.    | `horizontal` \| `vertical` |

## Global Configuration

You can configure the default options for all tabs in your application by using the `provideTabsConfig` function in a providers array.

```ts
import { provideTabsConfig } from 'ng-primitives/tabs';

bootstrapApplication(AppComponent, {
  providers: [
    provideTabsConfig({
      orientation: 'horizontal',
      activateOnFocus: false,
      wrap: false,
    }),
  ],
});
```

### NgpTabsConfig

The following options are available to configure the default tab options:

<prop-details name="orientation" type="'horizontal' | 'vertical'" default="horizontal">
  Define the default orientation of the tabs.
</prop-details>

<prop-details name="activateOnFocus" type="boolean" default="false">
  Define whether the tab should activate on focus.
</prop-details>

<prop-details name="wrap" type="boolean" default="false">
  Define whether the tabs should wrap around the tab list.
</prop-details>

## Accessibility

Adheres to the [Tabs WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs).

### Keyboard Interactions

- <kbd>ArrowLeft</kbd>: Move focus to the previous tab (horizontal orientation).
- <kbd>ArrowRight</kbd>: Move focus to the next tab (horizontal orientation).
- <kbd>ArrowUp</kbd>: Move focus to the previous tab (vertical orientation).
- <kbd>ArrowDown</kbd>: Move focus to the next tab (vertical orientation).
- <kbd>Home</kbd>: Move focus to the first tab.
- <kbd>End</kbd>: Move focus to the last tab.


---

### Textarea

File: primitives/textarea.md
URL: https://angularprimitives.com/primitives/textarea

# Textarea

The textarea primitive can be used to enhance the accessibility of a textarea element and provide consistent interaction handling for hover, focus and press states.

## Example

```typescript
import { Component } from '@angular/core';
import { NgpTextarea } from 'ng-primitives/textarea';

@Component({
  selector: 'app-textarea',
  imports: [NgpTextarea],
  template: `
    <textarea ngpTextarea placeholder="Enter your message"></textarea>
  `,
  styles: `
    :host {
      display: contents;
    }

    [ngpTextarea] {
      height: 72px;
      width: 90%;
      border-radius: 8px;
      padding: 8px 12px;
      border: none;
      box-shadow: var(--ngp-input-shadow);
      background-color: var(--ngp-background);
      outline: none;
    }

    [ngpTextarea][data-focus] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 0px;
    }

    [ngpTextarea]::placeholder {
      color: var(--ngp-text-placeholder);
    }
  `,
})
export default class TextareaExample {}

```

## Import

Import the Textarea primitives from `ng-primitives/textarea`.

```ts
import { NgpTextarea } from 'ng-primitives/textarea';
```

## Usage

Assemble the textarea directives in your template.

```html
<textarea ngpTextarea></textarea>
```

## Reusable Component

Create an textarea component that uses the `NgpTextarea` directive.

## Reusable Component

```typescript
import { Component } from '@angular/core';
import { NgpTextarea } from 'ng-primitives/textarea';

@Component({
  selector: 'textarea[app-textarea]',
  hostDirectives: [{ directive: NgpTextarea, inputs: ['disabled'] }],
  template: `
    <ng-content />
  `,
  styles: `
    :host {
      height: 72px;
      width: 90%;
      border-radius: 8px;
      padding: 8px 12px;
      border: none;
      box-shadow: var(--ngp-input-shadow);
      outline: none;
      font-family: inherit;
    }

    :host[data-focus] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 0;
    }

    :host::placeholder {
      color: var(--ngp-text-placeholder);
    }
  `,
})
export class Textarea {}

```

## Schematics

Generate a reusable textarea component using the Angular CLI.

```bash npm
ng g ng-primitives:primitive textarea
```

### Options

- `path`: The path at which to create the component file.
- `prefix`: The prefix to apply to the generated component selector.
- `componentSuffix`: The suffix to apply to the generated component class name.
- `fileSuffix`: The suffix to apply to the generated component file name. Defaults to `component`.
- `exampleStyles`: Whether to include example styles in the generated component file. Defaults to `true`.

## Examples

Here are some additional examples of how to use the Textarea primitive.

### Textarea Form Field

The textarea automatically integrates with the form field primitives.

## Example

```typescript
import { Component } from '@angular/core';
import { NgpDescription, NgpFormField, NgpLabel } from 'ng-primitives/form-field';
import { NgpTextarea } from 'ng-primitives/textarea';

@Component({
  selector: 'app-textarea-form-field',
  imports: [NgpTextarea, NgpLabel, NgpDescription, NgpFormField],
  template: `
    <div ngpFormField>
      <label ngpLabel>Message</label>
      <p ngpDescription>Tell us about your favorite sandwich.</p>
      <textarea ngpTextarea placeholder="Enter your message"></textarea>
    </div>
  `,
  styles: `
    :host {
      display: contents;
    }

    [ngpFormField] {
      display: flex;
      flex-direction: column;
      gap: 6px;
      width: 90%;
    }

    [ngpTextarea] {
      height: 72px;
      width: 90%;
      border-radius: 8px;
      padding: 8px 12px;
      border: none;
      box-shadow: var(--ngp-input-shadow);
      background-color: var(--ngp-background);
      outline: none;
    }

    [ngpTextarea][data-focus] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 0px;
    }

    [ngpTextarea]::placeholder {
      color: var(--ngp-text-placeholder);
    }

    [ngpLabel] {
      color: var(--ngp-text-primary);
      font-size: 0.875rem;
      line-height: 1.25rem;
      font-weight: 500;
      margin: 0;
    }

    [ngpDescription] {
      color: var(--ngp-text-secondary);
      font-size: 0.75rem;
      line-height: 1rem;
      margin: 0 0 4px;
    }
  `,
})
export default class TextareaFormFieldExample {}

```

## API Reference

The following directives are available to import from the `ng-primitives/textarea` package:

### NgpTextarea

## API Reference

### NgpTextarea



**Selector:** `[ngpTextarea]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `disabled` | `boolean` | `-` | Whether the element is disabled. |

#### Export As

`ngpTextarea`



#### Data Attributes

The following data attributes are applied to the `ngpTextarea` directive:

| Attribute       | Description                           |
| --------------- | ------------------------------------- |
| `data-hover`    | Applied when the element is hovered.  |
| `data-focus`    | Applied when the element is focused.  |
| `data-disabled` | Applied when the element is disabled. |


---

### Toast

File: primitives/toast.md
URL: https://angularprimitives.com/primitives/toast

# Toast

A toast is a non-modal, unobtrusive window element used to display brief, auto-expiring messages to the user.

## Example

```typescript
import { Component, inject, TemplateRef } from '@angular/core';
import { NgpToast, NgpToastManager } from 'ng-primitives/toast';

@Component({
  selector: 'app-toast',
  imports: [NgpToast],
  template: `
    <button class="toast-trigger" (click)="show(toast)" ngpButton>Show Toast</button>

    <ng-template #toast let-dismiss="dismiss">
      <div ngpToast animate.enter="toast-enter" animate.leave="toast-leave">
        <p class="toast-title">This is a toast message</p>
        <p class="toast-description">It will disappear in 3 seconds</p>
        <button class="toast-dismiss" (click)="dismiss()" ngpButton>Dismiss</button>
      </div>
    </ng-template>
  `,
  styles: `
    .toast-trigger {
      padding-left: 1rem;
      padding-right: 1rem;
      border-radius: 0.5rem;
      color: var(--ngp-text-primary);
      border: none;
      outline: none;
      height: 2.5rem;
      font-weight: 500;
      background-color: var(--ngp-background);
      transition: background-color 300ms cubic-bezier(0.4, 0, 0.2, 1);
      box-shadow: var(--ngp-button-shadow);
    }

    .toast-trigger[data-hover] {
      background-color: var(--ngp-background-hover);
    }

    .toast-trigger[data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 2px;
    }

    .toast-trigger[data-press] {
      background-color: var(--ngp-background-active);
    }

    [ngpToast] {
      position: absolute;
      touch-action: none;
      box-sizing: border-box;
      align-items: center;
      gap: 6px;
      display: inline-grid;
      background: var(--ngp-background);
      box-shadow: var(--ngp-shadow);
      border: 1px solid var(--ngp-border);
      padding: 12px 16px;
      opacity: 0;
      border-radius: 8px;
      z-index: var(--ngp-toast-z-index);
      grid-template-columns: 1fr auto;
      grid-template-rows: min-content min-content;
      column-gap: 12px;
      align-items: center;
      width: 350px;
      height: fit-content;
      transform: var(--y);
      transition: all 0.4s cubic-bezier(0.215, 0.61, 0.355, 1);
    }

    .toast-title {
      color: var(--ngp-text-primary);
      font-size: 0.75rem;
      font-weight: 600;
      margin: 0;
      grid-column: 1 / 2;
      grid-row: 1;
      line-height: 16px;
      user-select: none;
    }

    .toast-description {
      font-size: 0.75rem;
      margin: 0;
      color: var(--ngp-text-secondary);
      grid-column: 1 / 2;
      grid-row: 2;
      line-height: 16px;
      user-select: none;
    }

    .toast-dismiss {
      background: var(--ngp-background-inverse);
      color: var(--ngp-text-inverse);
      border: none;
      border-radius: 8px;
      padding: 4px 8px;
      font-weight: 600;
      font-size: 12px;
      cursor: pointer;
      grid-column: 2 / 3;
      grid-row: 1 / 3;
      max-height: 27px;
    }

    [ngpToast][data-position-x='end'] {
      right: 0;
    }

    [ngpToast][data-position-x='start'] {
      left: 0;
    }

    [ngpToast][data-position-y='top'] {
      top: 0;
      --lift: 1;
      --lift-amount: calc(var(--lift) * var(--ngp-toast-gap));
      --y: translateY(-100%);
    }

    [ngpToast][data-position-y='bottom'] {
      bottom: 0;
      --lift: -1;
      --lift-amount: calc(var(--lift) * var(--ngp-toast-gap));
      --y: translateY(100%);
    }

    [ngpToast][data-enter] {
      opacity: 1;
      --y: translateY(0);
    }

    [ngpToast][data-exit] {
      opacity: 0;
      --y: translateY(calc(calc(var(--lift) * var(--ngp-toast-gap)) * -1));
    }

    [ngpToast][data-visible='false'] {
      opacity: 0;
      pointer-events: none;
    }

    [ngpToast][data-expanded='true']::after {
      content: '';
      position: absolute;
      left: 0;
      height: calc(var(--ngp-toast-gap) + 1px);
      bottom: 100%;
      width: 100%;
    }

    [ngpToast][data-expanded='false'][data-front='false'] {
      --scale: var(--ngp-toasts-before) * 0.05 + 1;
      --y: translateY(calc(var(--lift-amount) * var(--ngp-toasts-before)))
        scale(calc(-1 * var(--scale)));
      height: var(--ngp-toast-front-height);
    }

    [ngpToast][data-expanded='true'] {
      --y: translateY(calc(var(--lift) * var(--ngp-toast-offset)));
      height: auto;
    }

    [ngpToast][data-swiping='true'] {
      transform: var(--y) translateY(var(--ngp-toast-swipe-amount-y, 0))
        translateX(var(--ngp-toast-swipe-amount-x, 0));
      transition: none;
    }

    [ngpToast][data-swiping='true'][data-swipe-direction='left'] {
      /* Fade out from -45px to -100px swipe */
      opacity: calc(1 - clamp(0, ((-1 * var(--ngp-toast-swipe-x, 0px)) - 45) / 55, 1));
    }

    [ngpToast][data-swiping='true'][data-swipe-direction='right'] {
      /* Fade out from 45px to 100px swipe */
      opacity: calc(1 - clamp(0, (var(--ngp-toast-swipe-x, 0px) - 45) / 55, 1));
    }

    [ngpToast][data-swiping='true'][data-swipe-direction='top'] {
      /* Fade out from -45px to -100px swipe */
      opacity: calc(1 - clamp(0, ((-1 * var(--ngp-toast-swipe-y, 0px)) - 45) / 55, 1));
    }

    [ngpToast][data-swiping='true'][data-swipe-direction='bottom'] {
      /* Fade out from 45px to 100px swipe */
      opacity: calc(1 - clamp(0, (var(--ngp-toast-swipe-y, 0px) - 45) / 55, 1));
    }

    /* Truncate text only when toast is not front AND not expanded */
    [ngpToast][data-front='false'][data-expanded='false'] .toast-title {
      overflow: hidden;
      text-overflow: ellipsis;
      white-space: nowrap;
    }

    [ngpToast][data-front='false'][data-expanded='false'] .toast-description {
      overflow: hidden;
      text-overflow: ellipsis;
      white-space: nowrap;
    }

    /* Angular animations using animate.enter and animate.leave */
    .toast-enter {
      animation: toast-slide-in 400ms cubic-bezier(0.215, 0.61, 0.355, 1);
    }

    .toast-leave {
      opacity: 0;
      transform: translateY(100%);
      transition:
        opacity 400ms cubic-bezier(0.215, 0.61, 0.355, 1),
        transform 400ms cubic-bezier(0.215, 0.61, 0.355, 1);
    }

    @keyframes toast-slide-in {
      from {
        opacity: 0;
        transform: translateY(100%);
      }
      to {
        opacity: 1;
        transform: translateY(0);
      }
    }
  `,
})
export default class ToastExample {
  private readonly toastManager = inject(NgpToastManager);

  show(toast: TemplateRef<void>): void {
    this.toastManager.show(toast, { placement: 'bottom-end' });
  }
}

```

## Import

Import the Toast primitives from `ng-primitives/toast`.

```ts
import { NgpToast } from 'ng-primitives/toast';
```

## Usage

Assemble the toast directives in your template.

```html
<ng-template #toast>
  <div ngpToast>...</div>
</ng-template>
```

To show a toast, inject the `NgpToastManager` service and call the `show` method passing the toast template or a component
class that uses the `NgpToast` directive as a Host Directive.

```ts
import { NgpToastManager } from 'ng-primitives/toast';

export class MyComponent {
  private readonly toastManager = inject(NgpToastManager);

  showToast(): void {
    this.toastManager.show(toastTemplate);
    // or
    this.toastManager.show(MyToastComponent);
  }
}
```

## Reusable Component

Create a toast component that uses the `NgpToast` directive.

## Reusable Component

```typescript
import { Component, inject } from '@angular/core';
import { NgpButton } from 'ng-primitives/button';
import { injectToastContext, NgpToast, NgpToastManager } from 'ng-primitives/toast';

@Component({
  selector: 'app-toast',
  imports: [NgpButton],
  hostDirectives: [NgpToast],
  host: {
    'animate.enter': 'toast-enter',
    'animate.leave': 'toast-leave',
  },
  template: `
    <p class="toast-title">{{ context.header }}</p>
    <p class="toast-description">{{ context.description }}</p>
    <button class="toast-dismiss" (click)="dismiss()" ngpButton>Dismiss</button>
  `,
  styles: `
    :host {
      position: absolute;
      touch-action: none;
      box-sizing: border-box;
      align-items: center;
      gap: 6px;
      display: inline-grid;
      background: var(--ngp-background);
      box-shadow: var(--ngp-shadow);
      border: 1px solid var(--ngp-border);
      padding: 12px 16px;
      opacity: 0;
      border-radius: 8px;
      z-index: var(--ngp-toast-z-index);
      grid-template-columns: 1fr auto;
      grid-template-rows: min-content min-content;
      column-gap: 12px;
      align-items: center;
      width: 350px;
      height: fit-content;
      transform: var(--y);
      transition: all 0.4s cubic-bezier(0.215, 0.61, 0.355, 1);
    }

    .toast-title {
      color: var(--ngp-text-primary);
      font-size: 0.75rem;
      font-weight: 600;
      margin: 0;
      grid-column: 1 / 2;
      grid-row: 1;
      line-height: 16px;
      user-select: none;
    }

    .toast-description {
      font-size: 0.75rem;
      margin: 0;
      color: var(--ngp-text-secondary);
      grid-column: 1 / 2;
      grid-row: 2;
      line-height: 16px;
      user-select: none;
    }

    .toast-dismiss {
      background: var(--ngp-background-inverse);
      color: var(--ngp-text-inverse);
      border: none;
      border-radius: 8px;
      padding: 4px 8px;
      font-weight: 600;
      font-size: 12px;
      cursor: pointer;
      grid-column: 2 / 3;
      grid-row: 1 / 3;
      max-height: 27px;
    }

    :host[data-position-x='end'] {
      right: 0;
    }

    :host[data-position-x='start'] {
      left: 0;
    }

    :host[data-position-y='top'] {
      top: 0;
      --lift: 1;
      --lift-amount: calc(var(--lift) * var(--ngp-toast-gap));
      --y: translateY(-100%);
    }

    :host[data-position-y='bottom'] {
      bottom: 0;
      --lift: -1;
      --lift-amount: calc(var(--lift) * var(--ngp-toast-gap));
      --y: translateY(100%);
    }

    :host[data-enter] {
      opacity: 1;
      --y: translateY(0);
    }

    :host[data-exit] {
      opacity: 0;
      --y: translateY(calc(calc(var(--lift) * var(--ngp-toast-gap)) * -1));
    }

    :host[data-visible='false'] {
      opacity: 0;
      pointer-events: none;
    }

    :host[data-expanded='true']::after {
      content: '';
      position: absolute;
      left: 0;
      height: calc(var(--ngp-toast-gap) + 1px);
      bottom: 100%;
      width: 100%;
    }

    :host[data-expanded='false'][data-front='false'] {
      --scale: var(--ngp-toasts-before) * 0.05 + 1;
      --y: translateY(calc(var(--lift-amount) * var(--ngp-toasts-before)))
        scale(calc(-1 * var(--scale)));
      height: var(--ngp-toast-front-height);
    }

    :host[data-expanded='true'] {
      --y: translateY(calc(var(--lift) * var(--ngp-toast-offset)));
      height: auto;
    }

    :host[data-swiping='true'] {
      transform: var(--y) translateY(var(--ngp-toast-swipe-amount-y, 0))
        translateX(var(--ngp-toast-swipe-amount-x, 0));
      transition: none;
    }

    :host[data-swiping='true'][data-swipe-direction='left'] {
      /* Fade out from -45px to -100px swipe */
      opacity: calc(1 - clamp(0, ((-1 * var(--ngp-toast-swipe-x, 0px)) - 45) / 55, 1));
    }

    :host[data-swiping='true'][data-swipe-direction='right'] {
      /* Fade out from 45px to 100px swipe */
      opacity: calc(1 - clamp(0, (var(--ngp-toast-swipe-x, 0px) - 45) / 55, 1));
    }

    :host[data-swiping='true'][data-swipe-direction='top'] {
      /* Fade out from -45px to -100px swipe */
      opacity: calc(1 - clamp(0, ((-1 * var(--ngp-toast-swipe-y, 0px)) - 45) / 55, 1));
    }

    :host[data-swiping='true'][data-swipe-direction='bottom'] {
      /* Fade out from 45px to 100px swipe */
      opacity: calc(1 - clamp(0, (var(--ngp-toast-swipe-y, 0px) - 45) / 55, 1));
    }

    /* Truncate text only when toast is not front AND not expanded */
    :host[data-front='false'][data-expanded='false'] .toast-title {
      overflow: hidden;
      text-overflow: ellipsis;
      white-space: nowrap;
    }

    :host[data-front='false'][data-expanded='false'] .toast-description {
      overflow: hidden;
      text-overflow: ellipsis;
      white-space: nowrap;
    }

    /* Angular animations based on position */

    /* Bottom position animations */
    :host[data-position-y='bottom'].toast-enter {
      animation: toast-slide-in-bottom 400ms cubic-bezier(0.215, 0.61, 0.355, 1);
    }

    :host[data-position-y='bottom'].toast-leave {
      opacity: 0;
      transform: translateY(100%);
      transition:
        opacity 400ms cubic-bezier(0.215, 0.61, 0.355, 1),
        transform 400ms cubic-bezier(0.215, 0.61, 0.355, 1);
    }

    /* Top position animations */
    :host[data-position-y='top'].toast-enter {
      animation: toast-slide-in-top 400ms cubic-bezier(0.215, 0.61, 0.355, 1);
    }

    :host[data-position-y='top'].toast-leave {
      opacity: 0;
      transform: translateY(-100%);
      transition:
        opacity 400ms cubic-bezier(0.215, 0.61, 0.355, 1),
        transform 400ms cubic-bezier(0.215, 0.61, 0.355, 1);
    }

    /* Keyframes for bottom position */
    @keyframes toast-slide-in-bottom {
      from {
        opacity: 0;
        transform: translateY(100%);
      }
      to {
        opacity: 1;
        transform: translateY(0);
      }
    }

    /* Keyframes for top position */
    @keyframes toast-slide-in-top {
      from {
        opacity: 0;
        transform: translateY(-100%);
      }
      to {
        opacity: 1;
        transform: translateY(0);
      }
    }
  `,
})
export class Toast {
  private readonly toastManager = inject(NgpToastManager);
  private readonly toast = inject(NgpToast);
  protected readonly context = injectToastContext<ToastContext>();

  dismiss(): void {
    this.toastManager.dismiss(this.toast);
  }
}

interface ToastContext {
  header: string;
  description: string;
}

```

## Schematics

Generate a reusable toast component using the Angular CLI.

```bash npm
ng g ng-primitives:primitive toast
```

### Options

- `path`: The path at which to create the component file.
- `prefix`: The prefix to apply to the generated component selector.
- `componentSuffix`: The suffix to apply to the generated component class name.
- `fileSuffix`: The suffix to apply to the generated component file name. Defaults to `component`.
- `exampleStyles`: Whether to include example styles in the generated component file. Defaults to `true`.

## Examples

Here are some additional examples of how to use the Toast primitive.

### Sequential Mode

The sequential mode prevents background toasts from auto-closing. Only the front-most toast's timer runs, and when that toast is dismissed, the timer starts on the next toast in the stack.

This is useful when you have multiple notifications in quick succession (e.g., health monitoring of external services) where you want to ensure users can see all notifications before they auto-close.

## Example

```typescript
import { Component, inject, TemplateRef } from '@angular/core';
import { NgpButton } from 'ng-primitives/button';
import { NgpToastManager, NgpToast } from 'ng-primitives/toast';

/**
 * This example demonstrates the sequential toast feature.
 * When sequential mode is enabled, only the front-most toast's timer runs.
 * When that toast is dismissed, the timer starts on the next toast.
 *
 * To enable sequential mode globally:
 *
 * bootstrapApplication(AppComponent, {
 *   providers: [
 *     provideToastConfig({
 *       sequential: true,
 *     }),
 *   ],
 * });
 */
@Component({
  selector: 'app-toast-sequential',
  imports: [NgpToast, NgpButton],
  template: `
    <div class="container">
      <h2>Sequential Toast Example</h2>
      <p>Click the button to show multiple toasts. Notice how only the front toast's timer runs.</p>
      <button class="toast-trigger" (click)="showMultipleToasts(toast)" ngpButton>
        Show 3 Toasts
      </button>

      <ng-template #toast let-dismiss="dismiss">
        <div ngpToast animate.enter="toast-enter" animate.leave="toast-leave">
          <p class="toast-title">Sequential Toast</p>
          <p class="toast-description">Only front toast timer runs in sequential mode.</p>
          <button class="toast-dismiss" (click)="dismiss()" ngpButton>Dismiss</button>
        </div>
      </ng-template>
    </div>
  `,
  styles: `
    .container {
      padding: 2rem;
    }

    h2 {
      margin-top: 0;
      margin-bottom: 0.5rem;
      font-size: 1.25rem;
      font-weight: 600;
    }

    p {
      margin: 0 0 1rem 0;
      font-size: 0.875rem;
      color: var(--ngp-text-secondary);
    }

    .toast-trigger {
      padding-left: 1rem;
      padding-right: 1rem;
      border-radius: 0.5rem;
      color: var(--ngp-text-primary);
      border: none;
      outline: none;
      height: 2.5rem;
      font-weight: 500;
      background-color: var(--ngp-background);
      transition: background-color 300ms cubic-bezier(0.4, 0, 0.2, 1);
      box-shadow: var(--ngp-button-shadow);
    }

    .toast-trigger[data-hover] {
      background-color: var(--ngp-background-hover);
    }

    .toast-trigger[data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 2px;
    }

    .toast-trigger[data-press] {
      background-color: var(--ngp-background-active);
    }

    [ngpToast] {
      position: absolute;
      touch-action: none;
      box-sizing: border-box;
      align-items: center;
      gap: 6px;
      display: inline-grid;
      background: var(--ngp-background);
      box-shadow: var(--ngp-shadow);
      border: 1px solid var(--ngp-border);
      padding: 12px 16px;
      opacity: 0;
      border-radius: 8px;
      z-index: var(--ngp-toast-z-index);
      grid-template-columns: 1fr auto;
      grid-template-rows: min-content min-content;
      column-gap: 12px;
      align-items: center;
      width: 350px;
      height: fit-content;
      transform: var(--y);
      transition: all 0.4s cubic-bezier(0.215, 0.61, 0.355, 1);
    }

    .toast-title {
      color: var(--ngp-text-primary);
      font-size: 0.75rem;
      font-weight: 600;
      margin: 0;
      grid-column: 1 / 2;
      grid-row: 1;
      line-height: 16px;
      user-select: none;
    }

    .toast-description {
      font-size: 0.75rem;
      margin: 0;
      color: var(--ngp-text-secondary);
      grid-column: 1 / 2;
      grid-row: 2;
      line-height: 16px;
      user-select: none;
    }

    .toast-dismiss {
      background: var(--ngp-background-inverse);
      color: var(--ngp-text-inverse);
      border: none;
      border-radius: 8px;
      padding: 4px 8px;
      font-weight: 600;
      font-size: 12px;
      cursor: pointer;
      grid-column: 2 / 3;
      grid-row: 1 / 3;
      max-height: 27px;
    }

    [ngpToast][data-position-x='end'] {
      right: 0;
    }

    [ngpToast][data-position-x='start'] {
      left: 0;
    }

    [ngpToast][data-position-y='top'] {
      top: 0;
      --lift: 1;
      --lift-amount: calc(var(--lift) * var(--ngp-toast-gap));
      --y: translateY(-100%);
    }

    [ngpToast][data-position-y='bottom'] {
      bottom: 0;
      --lift: -1;
      --lift-amount: calc(var(--lift) * var(--ngp-toast-gap));
      --y: translateY(100%);
    }

    [ngpToast][data-enter] {
      opacity: 1;
      --y: translateY(0);
    }

    [ngpToast][data-exit] {
      opacity: 0;
      --y: translateY(calc(calc(var(--lift) * var(--ngp-toast-gap)) * -1));
    }

    [ngpToast][data-visible='false'] {
      opacity: 0;
      pointer-events: none;
    }

    [ngpToast][data-expanded='true']::after {
      content: '';
      position: absolute;
      left: 0;
      height: calc(var(--ngp-toast-gap) + 1px);
      bottom: 100%;
      width: 100%;
    }

    [ngpToast][data-expanded='false'][data-front='false'] {
      --scale: var(--ngp-toasts-before) * 0.05 + 1;
      --y: translateY(calc(var(--lift-amount) * var(--ngp-toasts-before)))
        scale(calc(-1 * var(--scale)));
      height: var(--ngp-toast-front-height);
    }

    [ngpToast][data-expanded='true'] {
      --y: translateY(calc(var(--lift) * var(--ngp-toast-offset)));
      height: auto;
    }

    [ngpToast][data-swiping='true'] {
      transform: var(--y) translateY(var(--ngp-toast-swipe-amount-y, 0))
        translateX(var(--ngp-toast-swipe-amount-x, 0));
      transition: none;
    }

    [ngpToast][data-swiping='true'][data-swipe-direction='left'] {
      /* Fade out from -45px to -100px swipe */
      opacity: calc(1 - clamp(0, ((-1 * var(--ngp-toast-swipe-x, 0px)) - 45) / 55, 1));
    }

    [ngpToast][data-swiping='true'][data-swipe-direction='right'] {
      /* Fade out from 45px to 100px swipe */
      opacity: calc(1 - clamp(0, (var(--ngp-toast-swipe-x, 0px) - 45) / 55, 1));
    }

    [ngpToast][data-swiping='true'][data-swipe-direction='top'] {
      /* Fade out from -45px to -100px swipe */
      opacity: calc(1 - clamp(0, ((-1 * var(--ngp-toast-swipe-y, 0px)) - 45) / 55, 1));
    }

    [ngpToast][data-swiping='true'][data-swipe-direction='bottom'] {
      /* Fade out from 45px to 100px swipe */
      opacity: calc(1 - clamp(0, (var(--ngp-toast-swipe-y, 0px) - 45) / 55, 1));
    }

    /* Truncate text only when toast is not front AND not expanded */
    [ngpToast][data-front='false'][data-expanded='false'] .toast-title {
      overflow: hidden;
      text-overflow: ellipsis;
      white-space: nowrap;
    }

    [ngpToast][data-front='false'][data-expanded='false'] .toast-description {
      overflow: hidden;
      text-overflow: ellipsis;
      white-space: nowrap;
    }

    /* Angular animations using animate.enter and animate.leave */
    .toast-enter {
      animation: toast-slide-in 400ms cubic-bezier(0.215, 0.61, 0.355, 1);
    }

    .toast-leave {
      opacity: 0;
      transform: translateY(100%);
      transition:
        opacity 400ms cubic-bezier(0.215, 0.61, 0.355, 1),
        transform 400ms cubic-bezier(0.215, 0.61, 0.355, 1);
    }

    @keyframes toast-slide-in {
      from {
        opacity: 0;
        transform: translateY(100%);
      }
      to {
        opacity: 1;
        transform: translateY(0);
      }
    }
  `,
})
export default class ToastSequentialExample {
  private readonly toastManager = inject(NgpToastManager);

  showMultipleToasts(toast: TemplateRef<void>): void {
    // Show 3 toasts with a small delay between each
    // Each toast has sequential mode enabled
    for (let i = 0; i < 3; i++) {
      setTimeout(() => {
        this.toastManager.show(toast, {
          placement: 'bottom-end',
          sequential: true,
        });
      }, i * 300);
    }
  }
}

```

You can enable sequential mode in two ways:

**1. Globally via configuration:**

```ts
import { provideToastConfig } from 'ng-primitives/toast';

bootstrapApplication(AppComponent, {
  providers: [
    provideToastConfig({
      sequential: true,
      // ... other config options
    }),
  ],
});
```

**2. Per-toast via the show method:**

```ts
import { NgpToastManager } from 'ng-primitives/toast';

export class MyComponent {
  private readonly toastManager = inject(NgpToastManager);

  showToast(): void {
    this.toastManager.show(ToastComponent, {
      sequential: true,
    });
  }
}
```

## API Reference

The following directives are available to import from the `ng-primitives/toast` package:

### NgpToast

## API Reference

### NgpToast



**Selector:** `[ngpToast]`

#### Export As

`ngpToast`



#### Data Attributes

The following data attributes are applied to the first child of the `ngpToast` ng-template:

| Attribute              | Description                                                                                                                              | Value                         |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
| `data-position-x`      | The horizontal position of the toast                                                                                                     | `start`, `center`, `end`      |
| `data-position-y`      | The vertical position of the toast                                                                                                       | `top`, `bottom`               |
| `data-visible`         | Whether the toast is currently visible. This is based on how many toasts are shown compared to the `maxToasts` set in the global config. | `true`, `false`               |
| `data-front`           | Whether the toast is the front-most toast in the stack.                                                                                  | `true`, `false`               |
| `data-swiping`         | Whether the toast is currently being swiped.                                                                                             | `true`, `false`               |
| `data-swipe-direction` | The direction of the swipe gesture.                                                                                                      | `left`, `right`, `up`, `down` |
| `data-expanded`        | Whether the toast is currently expanded. This can be used to collapse or expand stacked toasts.                                          | `true`, `false`               |

The following CSS custom properties are available to the `ngpToast` directive:

| Property                     | Description                                   |
| ---------------------------- | --------------------------------------------- |
| `--ngp-toast-gap`            | The gap between each toast.                   |
| `--ngp-toast-z-index`        | The z-index of the toast.                     |
| `--ngp-toasts-before`        | The number of toasts before this one.         |
| `--ngp-toast-index`          | The index of the toast (1-based).             |
| `--ngp-toast-height`         | The height of the toast in pixels.            |
| `--ngp-toast-offset`         | The vertical offset position of the toast.    |
| `--ngp-toast-front-height`   | The height of the front-most toast.           |
| `--ngp-toast-swipe-amount-x` | The swipe amount on the X axis (pixel value). |
| `--ngp-toast-swipe-amount-y` | The swipe amount on the Y axis (pixel value). |
| `--ngp-toast-swipe-x`        | The swipe value on the X axis.                |
| `--ngp-toast-swipe-y`        | The swipe value on the Y axis.                |

## Global Configuration

You can configure the default options for all toasts in your application by using the `provideToastConfig` function in a providers array.

```ts
import { provideToastConfig } from 'ng-primitives/toast';

bootstrapApplication(AppComponent, {
  providers: [
    provideToastConfig({
      placement: 'top-end',
      duration: 5000,
      offsetTop: 16,
      offsetBottom: 16,
      offsetLeft: 16,
      offsetRight: 16,
      dismissible: true,
      maxToasts: 3,
      zIndex: 9999999,
      swipeDirections: ['left', 'right'],
      ariaLive: 'assertive',
      gap: 16,
    }),
  ],
});
```

### NgpToastConfig

<prop-details name="placement" type="NgpToastPlacement" default="top-end">
  The default placement of the toast. Can be one of `top-start`, `top-end`, `top-center`, `bottom-start`, `bottom-end`, or `bottom-center`.
</prop-details>

<prop-details name="duration" type="number" default="3000">
  The duration in milliseconds that the toast will be visible.
</prop-details>

<prop-details name="offsetTop" type="number" default="24">
  The offset from the top of the viewport in pixels.
</prop-details>

<prop-details name="offsetBottom" type="number" default="24">
  The offset from the bottom of the viewport in pixels.
</prop-details>

<prop-details name="offsetLeft" type="number" default="24">
  The offset from the left of the viewport in pixels.
</prop-details>

<prop-details name="offsetRight" type="number" default="24">
  The offset from the right of the viewport in pixels.
</prop-details>

<prop-details name="dismissible" type="boolean" default="true">
  Whether a toast can be dismissed by swiping.
</prop-details>

<prop-details name="swipeThreshold" type="number" default="45">
  The amount a toast must be swiped before it is considered dismissed.
</prop-details>

<prop-details name="swipeDirections" type="NgpToastSwipeDirection[]" default="['left', 'right', 'top', 'bottom']">
  The default swipe directions supported by the toast.
</prop-details>

<prop-details name="maxToasts" type="number" default="3">
  The maximum number of toasts that can be displayed at once.
</prop-details>

<prop-details name="ariaLive" type="string" default="'polite'">
  The aria live setting.
</prop-details>

<prop-details name="gap" type="number" default="14">
  The gap between each toast.
</prop-details>

<prop-details name="zIndex" type="number" default="9999999">
  The z-index of the toast container.
</prop-details>

<prop-details name="sequential" type="boolean" default="false">
  When enabled, only the front toast's timer will run. When a toast is dismissed, the timer will start on the next toast. Useful for scenarios with multiple notifications where you want to prevent background toasts from auto-closing.
</prop-details>


---

### Toggle Group

File: primitives/toggle-group.md
URL: https://angularprimitives.com/primitives/toggle-group

# Toggle Group

The toggle group primitive is a collection of toggle buttons that can be used to select one or more options.

## Example

```typescript
import { Component } from '@angular/core';
import { NgIcon, provideIcons } from '@ng-icons/core';
import { heroBars3, heroBars3BottomLeft, heroBars3BottomRight } from '@ng-icons/heroicons/outline';
import { NgpButton } from 'ng-primitives/button';
import { NgpToggleGroup, NgpToggleGroupItem } from 'ng-primitives/toggle-group';

@Component({
  selector: 'app-toggle-group',
  imports: [NgpToggleGroup, NgpToggleGroupItem, NgpButton, NgIcon],
  providers: [
    provideIcons({
      heroBars3BottomLeft,
      heroBars3,
      heroBars3BottomRight,
    }),
  ],
  template: `
    <div ngpToggleGroup aria-label="Text alignment">
      <button ngpButton ngpToggleGroupItem ngpToggleGroupItemValue="left" aria-label="Left align">
        <ng-icon name="heroBars3BottomLeft" />
      </button>

      <button
        ngpButton
        ngpToggleGroupItem
        ngpToggleGroupItemValue="center"
        aria-label="Center align"
      >
        <ng-icon name="heroBars3" />
      </button>

      <button ngpButton ngpToggleGroupItem ngpToggleGroupItemValue="right" aria-label="Right align">
        <ng-icon name="heroBars3BottomRight" />
      </button>
    </div>
  `,
  styles: `
    [ngpToggleGroup] {
      display: flex;
      column-gap: 0.25rem;
      align-items: center;
      border-radius: 0.375rem;
      background-color: var(--ngp-background);
      box-shadow: var(--ngp-button-shadow);
      padding: 0.25rem;
    }

    [ngpToggleGroupItem] {
      display: flex;
      width: 2rem;
      height: 2rem;
      align-items: center;
      justify-content: center;
      border-radius: 0.25rem;
      border: 1px solid transparent;
      background: transparent;
      outline: none;
      transition: background-color 150ms cubic-bezier(0.4, 0, 0.2, 1);
      box-sizing: border-box;
      color: var(--ngp-text-primary);
    }

    [ngpToggleGroupItem][data-hover] {
      background-color: var(--ngp-background-hover);
      border-color: var(--ngp-border);
    }

    [ngpToggleGroupItem][data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
    }

    [ngpToggleGroupItem][data-press] {
      background-color: var(--ngp-background-active);
    }

    [ngpToggleGroupItem][data-selected] {
      background-color: var(--ngp-background-inverse);
      color: var(--ngp-text-inverse);
      border-color: transparent;
    }

    ng-icon {
      font-size: 1.125rem;
    }
  `,
})
export default class ToggleGroupExample {}

```

## Import

Import the ToggleGroup primitives from `ng-primitives/toggle-group`.

```ts
import { NgpToggleGroup, NgpToggleGroupItem } from 'ng-primitives/toggle-group';
```

## Usage

Assemble the toggle-group directives in your template.

```html
<div ngpToggleGroup>
  <button ngpToggleGroupItem ngpToggleGroupItemValue="1">Option 1</button>
  <button ngpToggleGroupItem ngpToggleGroupItemValue="2">Option 2</button>
  <button ngpToggleGroupItem ngpToggleGroupItemValue="3">Option 3</button>
</div>
```

## Reusable Component

Create a reusable component that uses the toggle group directives.

## Reusable Component

```typescript
import { Component } from '@angular/core';
import { ControlValueAccessor } from '@angular/forms';
import { injectToggleGroupState, NgpToggleGroup } from 'ng-primitives/toggle-group';
import { ChangeFn, provideValueAccessor, TouchedFn } from 'ng-primitives/utils';

@Component({
  selector: 'app-toggle-group',
  hostDirectives: [
    {
      directive: NgpToggleGroup,
      inputs: [
        'ngpToggleGroupOrientation:orientation',
        'ngpToggleGroupType:type',
        'ngpToggleGroupValue:value',
        'ngpToggleGroupDisabled:disabled',
      ],
      outputs: ['ngpToggleGroupValueChange:valueChange'],
    },
  ],
  template: `
    <ng-content />
  `,
  styles: `
    :host {
      display: inline-flex;
      column-gap: 0.25rem;
      align-items: center;
      border-radius: 0.375rem;
      background-color: var(--ngp-background);
      box-shadow: var(--ngp-button-shadow);
      padding: 0.25rem;
    }
  `,
  providers: [provideValueAccessor(ToggleGroup)],
  host: {
    '(focusout)': 'onTouched?.()',
  },
})
export class ToggleGroup implements ControlValueAccessor {
  /** Access the toggle state. */
  private readonly toggleGroup = injectToggleGroupState();

  /** The on change callback */
  private onChange?: ChangeFn<string[]>;

  /** The on touched callback */
  protected onTouched?: TouchedFn;

  constructor() {
    // Any time the toggle group changes, update the form value.
    this.toggleGroup().valueChange.subscribe(value => this.onChange?.(value));
  }

  /** Write a new value to the toggle group. */
  writeValue(value: string[]): void {
    this.toggleGroup().setValue(value);
  }

  /** Register a callback function to be called when the value changes. */
  registerOnChange(fn: ChangeFn<string[]>): void {
    this.onChange = fn;
  }

  /** Register a callback function to be called when the toggle group is touched. */
  registerOnTouched(fn: TouchedFn): void {
    this.onTouched = fn;
  }

  /** Set the disabled state of the toggle group. */
  setDisabledState(isDisabled: boolean): void {
    this.toggleGroup().setDisabled(isDisabled);
  }
}

```

## Schematics

Generate a reusable toggle group component using the Angular CLI.

```bash npm
ng g ng-primitives:primitive toggle-group
```

### Options

- `path`: The path at which to create the component file.
- `prefix`: The prefix to apply to the generated component selector.
- `componentSuffix`: The suffix to apply to the generated component class name.
- `fileSuffix`: The suffix to apply to the generated component file name. Defaults to `component`.
- `exampleStyles`: Whether to include example styles in the generated component file. Defaults to `true`.

## Examples

Here are some additional examples of how to use the Toggle Group primitives.

### Multiple Selection

The toggle group can be configured to allow multiple selections by setting the `ngpToggleGroupType` input to `multiple`.

## Example

```typescript
import { Component } from '@angular/core';
import { NgIcon, provideIcons } from '@ng-icons/core';
import {
  heroBold,
  heroItalic,
  heroStrikethrough,
  heroUnderline,
} from '@ng-icons/heroicons/outline';
import { NgpButton } from 'ng-primitives/button';
import { NgpToggleGroup, NgpToggleGroupItem } from 'ng-primitives/toggle-group';

@Component({
  selector: 'app-toggle-group',
  imports: [NgpToggleGroup, NgpToggleGroupItem, NgpButton, NgIcon],
  providers: [provideIcons({ heroBold, heroItalic, heroStrikethrough, heroUnderline })],
  template: `
    <div ngpToggleGroup ngpToggleGroupType="multiple" aria-label="Text formatting">
      <button ngpButton ngpToggleGroupItem ngpToggleGroupItemValue="bold" aria-label="Bold">
        <ng-icon name="heroBold" />
      </button>

      <button ngpButton ngpToggleGroupItem ngpToggleGroupItemValue="italic" aria-label="Italic">
        <ng-icon name="heroItalic" />
      </button>

      <button
        ngpButton
        ngpToggleGroupItem
        ngpToggleGroupItemValue="underline"
        aria-label="Underline"
      >
        <ng-icon name="heroUnderline" />
      </button>

      <button
        ngpButton
        ngpToggleGroupItem
        ngpToggleGroupItemValue="strikethrough"
        aria-label="Strikethrough"
      >
        <ng-icon name="heroStrikethrough" />
      </button>
    </div>
  `,
  styles: `
    [ngpToggleGroup] {
      display: flex;
      column-gap: 0.25rem;
      align-items: center;
      border-radius: 0.375rem;
      background-color: var(--ngp-background);
      box-shadow: var(--ngp-button-shadow);
      padding: 0.25rem;
    }

    [ngpToggleGroupItem] {
      display: flex;
      width: 2rem;
      height: 2rem;
      align-items: center;
      justify-content: center;
      border-radius: 0.25rem;
      border: 1px solid transparent;
      background: transparent;
      outline: none;
      transition: background-color 150ms cubic-bezier(0.4, 0, 0.2, 1);
      box-sizing: border-box;
      color: var(--ngp-text-primary);
    }

    [ngpToggleGroupItem][data-hover] {
      background-color: var(--ngp-background-hover);
      border-color: var(--ngp-border);
    }

    [ngpToggleGroupItem][data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
    }

    [ngpToggleGroupItem][data-press] {
      background-color: var(--ngp-background-active);
    }

    [ngpToggleGroupItem][data-selected] {
      background-color: var(--ngp-background-inverse);
      color: var(--ngp-text-inverse);
      border-color: transparent;
    }

    ng-icon {
      font-size: 1.125rem;
    }
  `,
})
export default class ToggleGroupExample {}

```

## API Reference

The following directives are available to import from the `ng-primitives/toggle-group` package:

### NgpToggleGroup

## API Reference

### NgpToggleGroup



**Selector:** `[ngpToggleGroup]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpToggleGroupOrientation` | `NgpOrientation` | `-` | The orientation of the toggle group. |
| `ngpToggleGroupWrap` | `boolean` | `true` | Whether focus should wrap around when reaching the end of the toggle group. |
| `ngpToggleGroupAllowDeselection` | `boolean` | `true` | Whether toggle buttons can be deselected. If set to `false`, clicking a selected toggle button will not deselect it. |
| `ngpToggleGroupType` | `"single" | "multiple"` | `-` | The type of the toggle group, whether only one item can be selected or multiple. |
| `ngpToggleGroupValue` | `string[]` | `-` | The selected value(s) of the toggle group. |
| `ngpToggleGroupDisabled` | `boolean` | `-` | Whether the toggle group is disabled. |

#### Outputs

| Event | Type | Description |
|-------|------|-------------|
| `ngpToggleGroupValueChange` | `string[]` | Emits when the value of the toggle group changes. |

#### Export As

`ngpToggleGroup`



#### Data Attributes

The following data attributes are available to style the toggle group:

| Attribute          | Description                                | Value                      |
| ------------------ | ------------------------------------------ | -------------------------- |
| `data-disabled`    | Applied when the toggle group is disabled. | `-`                        |
| `data-orientation` | The orientation of the toggle group.       | `horizontal` \| `vertical` |
| `data-type`        | The type of the toggle group.              | `single` \| `multiple`     |

### NgpToggleGroupItem

## API Reference

### NgpToggleGroupItem



**Selector:** `[ngpToggleGroupItem]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpToggleGroupItemValue` | `string | undefined` | `-` | The value of the item. |
| `ngpToggleGroupItemDisabled` | `boolean` | `-` | Whether the item is disabled. |

#### Export As

`ngpToggleGroupItem`



#### Data Attributes

The following data attributes are available to style the toggle group item:

| Attribute       | Description                                     | Value |
| --------------- | ----------------------------------------------- | ----- |
| `data-disabled` | Applied when the toggle group item is disabled. | `-`   |
| `data-selected` | Applied when the toggle group item is selected. | `-`   |

## Global Configuration

You can configure the default options for all toggle-groups in your application by using the `provideToggleGroupConfig` function in a providers array.

```ts
import { provideToggleGroupConfig } from 'ng-primitives/toggle-group';

bootstrapApplication(AppComponent, {
  providers: [
    provideToggleGroupConfig({
      orientation: 'vertical',
      type: 'multiple',
    }),
  ],
});
```

### NgpToggleGroupConfig

<prop-details name="orientation" type="'horizontal' | 'vertical'" default="horizontal">
  The default orientation of the toggle group.
</prop-details>

<prop-details name="type" type="'single' | 'multiple'" default="single">
  The default type of the toggle group.
</prop-details>

### Keyboard Interaction

- <kbd>Tab</kbd> - Moves focus to the first toggle group item in the toolbar.
- <kbd>Arrow Down</kbd> - Moves focus to the next toggle group item (vertical orientation).
- <kbd>Arrow Up</kbd> - Moves focus to the previous toggle group item (vertical orientation).
- <kbd>Arrow Right</kbd> - Moves focus to the next toggle group item (horizontal orientation).
- <kbd>Arrow Left</kbd> - Moves focus to the previous toggle group item (horizontal orientation).
- <kbd>Home</kbd> - Moves focus to the first toggle group item.
- <kbd>End</kbd> - Moves focus to the last toggle group item.


---

### Toggle

File: primitives/toggle.md
URL: https://angularprimitives.com/primitives/toggle

# Toggle

Toggle a button on and off.

## Example

```typescript
import { Component, signal } from '@angular/core';
import { NgpButton } from 'ng-primitives/button';
import { NgpToggle } from 'ng-primitives/toggle';

@Component({
  selector: 'app-toggle',
  imports: [NgpToggle, NgpButton],
  template: `
    <button [(ngpToggleSelected)]="selected" ngpButton ngpToggle>Toggle</button>
  `,
  styles: `
    [ngpButton] {
      padding-left: 1rem;
      padding-right: 1rem;
      border-radius: 0.5rem;
      color: var(--ngp-text-primary);
      border: none;
      outline: none;
      height: 2.5rem;
      font-weight: 500;
      background-color: var(--ngp-background);
      transition: background-color 300ms cubic-bezier(0.4, 0, 0.2, 1);
      box-shadow: var(--ngp-button-shadow);
    }

    [ngpButton][data-hover] {
      background-color: var(--ngp-background-hover);
    }

    [ngpButton][data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 2px;
    }

    [ngpButton][data-press] {
      background-color: var(--ngp-background-active);
    }

    [ngpButton][data-selected] {
      background-color: var(--ngp-background-inverse);
      color: var(--ngp-text-inverse);
    }
  `,
})
export default class ToggleExample {
  /**
   * Whether the toggle is selected.
   */
  readonly selected = signal(false);
}

```

## Import

Import the Toggle primitives from `ng-primitives/toggle`.

```ts
import { NgpToggle } from 'ng-primitives/toggle';
```

## Usage

Assemble the toggle directives in your template.

```html
<button ngpToggle [(ngpToggleSelected)]="selected">Toggle</button>
```

## Reusable Component

Create a reusable component that uses the toggle directives.

## Reusable Component

```typescript
import { Component } from '@angular/core';
import { ControlValueAccessor } from '@angular/forms';
import { NgpButton } from 'ng-primitives/button';
import { injectToggleState, NgpToggle } from 'ng-primitives/toggle';
import { ChangeFn, provideValueAccessor, TouchedFn } from 'ng-primitives/utils';

@Component({
  selector: 'button[app-toggle]',
  hostDirectives: [
    {
      directive: NgpToggle,
      inputs: ['ngpToggleSelected:selected', 'ngpToggleDisabled:disabled'],
      outputs: ['ngpToggleSelectedChange:selectedChange'],
    },
    { directive: NgpButton, inputs: ['disabled'] },
  ],
  template: `
    <ng-content />
  `,
  styles: `
    :host {
      padding-left: 1rem;
      padding-right: 1rem;
      border-radius: 0.5rem;
      color: var(--ngp-text-primary);
      border: none;
      outline: none;
      height: 2.5rem;
      font-weight: 500;
      background-color: var(--ngp-background);
      transition: background-color 300ms cubic-bezier(0.4, 0, 0.2, 1);
      box-shadow: var(--ngp-button-shadow);
    }

    :host[data-hover] {
      background-color: var(--ngp-background-hover);
    }

    :host[data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 2px;
    }

    :host[data-press] {
      background-color: var(--ngp-background-active);
    }

    :host[data-selected] {
      background-color: var(--ngp-background-inverse);
      color: var(--ngp-text-inverse);
    }
  `,
  providers: [provideValueAccessor(Toggle)],
  host: {
    '(focusout)': 'onTouched?.()',
  },
})
export class Toggle implements ControlValueAccessor {
  /** Access the toggle state. */
  private readonly toggle = injectToggleState();

  /** The on change callback */
  private onChange?: ChangeFn<boolean>;

  /** The on touched callback */
  protected onTouched?: TouchedFn;

  constructor() {
    // Any time the toggle changes, update the form value.
    this.toggle().selectedChange.subscribe(value => this.onChange?.(value));
  }

  /** Write a new value to the toggle. */
  writeValue(value: boolean): void {
    this.toggle().setSelected(value);
  }

  /** Register a callback function to be called when the value changes. */
  registerOnChange(fn: ChangeFn<boolean>): void {
    this.onChange = fn;
  }

  /** Register a callback function to be called when the toggle is touched. */
  registerOnTouched(fn: TouchedFn): void {
    this.onTouched = fn;
  }

  /** Set the disabled state of the toggle. */
  setDisabledState(isDisabled: boolean): void {
    this.toggle().setDisabled(isDisabled);
  }
}

```

## Schematics

Generate a reusable toggle component using the Angular CLI.

```bash npm
ng g ng-primitives:primitive toggle
```

### Options

- `path`: The path at which to create the component file.
- `prefix`: The prefix to apply to the generated component selector.
- `componentSuffix`: The suffix to apply to the generated component class name.
- `fileSuffix`: The suffix to apply to the generated component file name. Defaults to `component`.
- `exampleStyles`: Whether to include example styles in the generated component file. Defaults to `true`.

## API Reference

The following directives are available to import from the `ng-primitives/toggle` package:

### NgpToggle

## API Reference

### NgpToggle

Apply the `ngpToggle` directive to an element to manage the toggle state. This must be applied to a `button` element.

**Selector:** `[ngpToggle]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpToggleSelected` | `boolean` | `false` | Whether the toggle is selected. |
| `ngpToggleDisabled` | `boolean` | `false` | Whether the toggle is disabled. |

#### Outputs

| Event | Type | Description |
|-------|------|-------------|
| `ngpToggleSelectedChange` | `boolean` | Emits when the selected state changes. |

#### Export As

`ngpToggle`



#### Data Attributes

The following data attributes are applied to the `ngpToggle` directive:

| Attribute       | Description                          |
| --------------- | ------------------------------------ |
| `data-selected` | Applied when the toggle is selected. |
| `data-disabled` | Applied when the toggle is disabled. |

## Accessibility

### Keyboard Interaction

- <kbd>Space</kbd>: Toggles the selected state.
- <kbd>Enter</kbd>: Toggles the selected state.


---

### Toolbar

File: primitives/toolbar.md
URL: https://angularprimitives.com/primitives/toolbar

# Toolbar

The Toolbar primitive is a container for grouping related controls.

## Example

```typescript
import { Component } from '@angular/core';
import { NgIcon, provideIcons } from '@ng-icons/core';
import {
  heroBars3,
  heroBars3BottomLeft,
  heroBars3BottomRight,
  heroCog6Tooth,
  heroDocument,
  heroFolder,
} from '@ng-icons/heroicons/outline';
import { NgpButton } from 'ng-primitives/button';
import { NgpRovingFocusItem } from 'ng-primitives/roving-focus';
import { NgpSeparator } from 'ng-primitives/separator';
import { NgpToggleGroup, NgpToggleGroupItem } from 'ng-primitives/toggle-group';
import { NgpToolbar } from 'ng-primitives/toolbar';

@Component({
  selector: 'app-toolbar',
  imports: [
    NgpRovingFocusItem,
    NgIcon,
    NgpButton,
    NgpToolbar,
    NgpToggleGroup,
    NgpToggleGroupItem,
    NgpSeparator,
  ],
  providers: [
    provideIcons({
      heroDocument,
      heroFolder,
      heroBars3BottomLeft,
      heroBars3,
      heroBars3BottomRight,
      heroCog6Tooth,
    }),
  ],
  styles: `
    [ngpToolbar] {
      display: flex;
      column-gap: 0.25rem;
      align-items: center;
      border-radius: 0.375rem;
      background-color: var(--ngp-background);
      box-shadow: var(--ngp-button-shadow);
      padding: 0.25rem;
    }

    [ngpButton] {
      display: flex;
      width: 2rem;
      height: 2rem;
      align-items: center;
      justify-content: center;
      border-radius: 0.25rem;
      border: 1px solid transparent;
      background: transparent;
      outline: none;
      transition: background-color 150ms cubic-bezier(0.4, 0, 0.2, 1);
      box-sizing: border-box;
      color: var(--ngp-text-primary);
    }

    [ngpButton][data-hover] {
      background-color: var(--ngp-background-hover);
      border-color: var(--ngp-border);
    }

    [ngpButton][data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
    }

    [ngpButton][data-press] {
      background-color: var(--ngp-background-active);
    }

    [ngpButton][data-selected] {
      background-color: var(--ngp-background-inverse);
      color: var(--ngp-text-inverse);
    }

    [ngpToggleGroup] {
      display: flex;
      column-gap: 0.25rem;
    }

    ng-icon {
      font-size: 1.125rem;
    }

    .divider {
      width: 1px;
      height: 1.5rem;
      background-color: var(--ngp-border);
      margin: 0 0.25rem;
    }
  `,
  template: `
    <div ngpToolbar>
      <button type="button" ngpButton ngpRovingFocusItem>
        <ng-icon name="heroDocument" />
      </button>
      <button type="button" ngpButton ngpRovingFocusItem>
        <ng-icon name="heroFolder" />
      </button>

      <div class="divider" ngpSeparator></div>

      <div ngpToggleGroup aria-label="Text alignment">
        <button
          type="button"
          ngpButton
          ngpToggleGroupItem
          ngpToggleGroupItemValue="left"
          aria-label="Align left"
        >
          <ng-icon name="heroBars3BottomLeft" />
        </button>

        <button
          type="button"
          ngpButton
          ngpToggleGroupItem
          ngpToggleGroupItemValue="center"
          aria-label="Align center"
        >
          <ng-icon name="heroBars3" />
        </button>

        <button
          type="button"
          ngpButton
          ngpToggleGroupItem
          ngpToggleGroupItemValue="right"
          aria-label="Align right"
        >
          <ng-icon name="heroBars3BottomRight" />
        </button>
      </div>

      <div class="divider" ngpSeparator></div>

      <button type="button" ngpButton ngpRovingFocusItem>
        <ng-icon name="heroCog6Tooth" />
      </button>
    </div>
  `,
})
export default class ToolbarExample {}

```

## Import

Import the Toolbar primitives from `ng-primitives/toolbar`.

```ts
import { NgpToolbar } from 'ng-primitives/toolbar';
```

## Usage

Assemble the toolbar directives in your template.

```html
<div ngpToolbar>
  <!-- Toolbar content -->
</div>
```

## Reusable Component

Create a reusable component that uses the `NgpToolbar` directive.

## Reusable Component

```typescript
import { Component } from '@angular/core';
import { injectToolbarState, NgpToolbar } from 'ng-primitives/toolbar';

@Component({
  selector: 'app-toolbar',
  hostDirectives: [{ directive: NgpToolbar, inputs: ['ngpToolbarOrientation:orientation'] }],
  template: `
    <ng-content />
  `,
  styles: `
    :host {
      display: flex;
      column-gap: 0.25rem;
      align-items: center;
      border-radius: 0.375rem;
      background-color: var(--ngp-background);
      box-shadow: var(--ngp-button-shadow);
      padding: 0.25rem;
    }

    :host[data-orientation='vertical'] {
      flex-direction: column;
      row-gap: 0.25rem;
    }
  `,
})
export class Toolbar {
  /** Access the toolbar state */
  private readonly toolbar = injectToolbarState();

  constructor() {
    // default to horizontal orientation
    this.toolbar().setOrientation('horizontal');
  }
}

```

## Schematics

Generate a reusable toolbar component using the Angular CLI.

```bash npm
ng g ng-primitives:primitive toolbar
```

### Options

- `path`: The path at which to create the component file.
- `prefix`: The prefix to apply to the generated component selector.
- `componentSuffix`: The suffix to apply to the generated component class name.
- `fileSuffix`: The suffix to apply to the generated component file name. Defaults to `component`.
- `exampleStyles`: Whether to include example styles in the generated component file. Defaults to `true`.

## API Reference

The following directives are available to import from the `ng-primitives/toolbar` package:

### NgpToolbar

## API Reference

### NgpToolbar



**Selector:** `[ngpToolbar]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpToolbarOrientation` | `NgpOrientation` | `-` | The orientation of the toolbar. |

#### Export As

`ngpToolbar`



#### Data Attributes

The following data attributes are applied to the `ngpToolbar` directive:

| Attribute          | Description                     | Value                      |
| ------------------ | ------------------------------- | -------------------------- |
| `data-orientation` | The orientation of the toolbar. | `horizontal` \| `vertical` |

## Accessibility

Adheres to the [WAI-ARIA Toolbar Design Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/toolbar).

### Keyboard Interaction

- <kbd>Tab</kbd> - Moves focus to the first interactive element in the toolbar.
- <kbd>Arrow Down</kbd> - Moves focus to the next interactive element (vertical orientation).
- <kbd>Arrow Up</kbd> - Moves focus to the previous interactive element (vertical orientation).
- <kbd>Arrow Right</kbd> - Moves focus to the next interactive element (horizontal orientation).
- <kbd>Arrow Left</kbd> - Moves focus to the previous interactive element (horizontal orientation).
- <kbd>Home</kbd> - Moves focus to the first interactive element in the toolbar.
- <kbd>End</kbd> - Moves focus to the last interactive element in the toolbar.


---

### Tooltip

File: primitives/tooltip.md
URL: https://angularprimitives.com/primitives/tooltip

# Tooltip

Display additional information on hover.

## Example

```typescript
import { Component, ViewEncapsulation } from '@angular/core';
import { NgpButton } from 'ng-primitives/button';
import { NgpTooltip, NgpTooltipArrow, NgpTooltipTrigger } from 'ng-primitives/tooltip';

@Component({
  selector: 'app-tooltip',
  imports: [NgpTooltipTrigger, NgpTooltip, NgpTooltipArrow, NgpButton],
  template: `
    <div class="examples">
      <button [ngpTooltipTrigger]="tooltip" ngpButton type="button">Custom Tooltip</button>

      <button class="ellipsis-text" ngpTooltipTrigger>
        This is a very long text that will be truncated with ellipsis and show the full content in a
        tooltip when you hover over it
      </button>
    </div>

    <ng-template #tooltip>
      <div ngpTooltip>
        Hover over items to reveal additional context or details. Tooltips provide quick insights
        without cluttering your screen.

        <div ngpTooltipArrow></div>
      </div>
    </ng-template>
  `,
  styles: `
    app-tooltip {
      .examples {
        display: flex;
        gap: 1rem;
        align-items: center;
        flex-wrap: wrap;
      }

      .ellipsis-text {
        max-width: 200px;
        white-space: nowrap;
        overflow: hidden;
        text-overflow: ellipsis;
        font-size: 0.875rem;
      }

      .ellipsis-text:hover {
        background-color: var(--ngp-background-hover);
      }

      button {
        padding-left: 1rem;
        padding-right: 1rem;
        border-radius: 0.5rem;
        color: var(--ngp-text-primary);
        outline: none;
        height: 2.5rem;
        font-weight: 500;
        background-color: var(--ngp-background);
        transition: background-color 300ms cubic-bezier(0.4, 0, 0.2, 1);
        box-shadow: var(--ngp-button-shadow);
      }

      button[data-hover] {
        background-color: var(--ngp-background-hover);
      }

      button[data-focus-visible] {
        outline: 2px solid var(--ngp-focus-ring);
      }

      button[data-press] {
        background-color: var(--ngp-background-active);
      }
    }

    [ngpTooltip] {
      position: absolute;
      max-width: 16rem;
      border-radius: 0.5rem;
      background-color: var(--ngp-background-inverse);
      padding: 0.5rem 0.75rem;
      border: none;
      font-size: 0.75rem;
      font-weight: 500;
      color: var(--ngp-text-inverse);
      animation: tooltip-show 200ms ease-in-out;
      transform-origin: var(--ngp-tooltip-transform-origin);
    }

    [ngpTooltip][data-exit] {
      animation: tooltip-hide 200ms ease-in-out;
    }

    [ngpTooltipArrow] {
      position: absolute;
      pointer-events: none;
      background-color: var(--ngp-background-inverse);
      width: 8px;
      height: 8px;
      border-radius: 2px;
      transform: rotate(45deg);
    }

    [ngpTooltipArrow][data-placement='top'] {
      top: calc(100% - 5px);
    }

    [ngpTooltipArrow][data-placement='bottom'] {
      bottom: calc(100% - 5px);
    }

    @keyframes tooltip-show {
      0% {
        opacity: 0;
        transform: scale(0.9);
      }
      100% {
        opacity: 1;
        transform: scale(1);
      }
    }

    @keyframes tooltip-hide {
      0% {
        opacity: 1;
        transform: scale(1);
      }
      100% {
        opacity: 0;
        transform: scale(0.9);
      }
    }
  `,
  encapsulation: ViewEncapsulation.None,
})
export default class TooltipExample {}

```

## Import

Import the Tooltip primitives from `ng-primitives/tooltip`.

```ts
import { NgpTooltip, NgpTooltipTrigger, NgpTooltipArrow } from 'ng-primitives/tooltip';
```

## Usage

Assemble the tooltip directives in your template.

```html
<button [ngpTooltipTrigger]="tooltip" ngpButton>Hover me</button>

<ng-template #tooltip>
  <div ngpTooltip>Tooltip content</div>
</ng-template>
```

## Reusable Component

Create a tooltip component that uses the `NgpTooltip` directive.

## Reusable Component

```typescript
import { Component } from '@angular/core';
import { injectTooltipContext, NgpTooltip } from 'ng-primitives/tooltip';

@Component({
  selector: 'app-tooltip',
  hostDirectives: [NgpTooltip],
  template: `
    {{ content() }}
  `,
  styles: `
    :host {
      position: absolute;
      max-width: 16rem;
      border-radius: 0.5rem;
      background-color: var(--ngp-background-inverse);
      padding: 0.5rem 0.75rem;
      border: none;
      font-size: 0.75rem;
      font-weight: 500;
      color: var(--ngp-text-inverse);
      transform-origin: var(--ngp-tooltip-transform-origin);
    }

    :host[data-enter] {
      animation: tooltip-show 200ms ease-in-out;
    }

    :host[data-exit] {
      animation: tooltip-hide 200ms ease-in-out;
    }

    @keyframes tooltip-show {
      0% {
        opacity: 0;
        transform: scale(0.9);
      }
      100% {
        opacity: 1;
        transform: scale(1);
      }
    }

    @keyframes tooltip-hide {
      0% {
        opacity: 1;
        transform: scale(1);
      }
      100% {
        opacity: 0;
        transform: scale(0.9);
      }
    }
  `,
})
export class Tooltip {
  /** Access the tooltip context where the content is stored. */
  protected readonly content = injectTooltipContext<string>();
}

```

## Schematics

Generate a reusable tooltip component using the Angular CLI.

```bash npm
ng g ng-primitives:primitive tooltip
```

### Options

- `path`: The path at which to create the component file.
- `prefix`: The prefix to apply to the generated component selector.
- `componentSuffix`: The suffix to apply to the generated component class name.
- `fileSuffix`: The suffix to apply to the generated component file name. Defaults to `component`.
- `exampleStyles`: Whether to include example styles in the generated component file. Defaults to `true`.

## Examples

### Tooltip with Custom Container

The tooltip can be rendered inside a custom container. You can open DevTools and inspect the DOM to see it mounted within this container.

## Example

```typescript
import { Component, ViewEncapsulation } from '@angular/core';
import { NgpButton } from 'ng-primitives/button';
import {
  NgpTooltip,
  NgpTooltipArrow,
  NgpTooltipTrigger,
  provideTooltipConfig,
} from 'ng-primitives/tooltip';

@Component({
  selector: 'app-tooltip-custom-container',
  imports: [NgpTooltipTrigger, NgpTooltip, NgpTooltipArrow, NgpButton],
  providers: [
    provideTooltipConfig({
      container: '.tooltip-container',
    }),
  ],
  template: `
    <div class="tooltip-container"></div>

    <div class="examples">
      <button [ngpTooltipTrigger]="tooltip1" ngpButton type="button">
        Custom Container Tooltip
      </button>

      <button class="ellipsis-text" [ngpTooltipTrigger]="tooltip2">
        This text uses custom container for tooltip rendering
      </button>
    </div>

    <!-- Tooltip templates -->
    <ng-template #tooltip1>
      <div ngpTooltip>
        This tooltip is rendered in a custom container! Check the DOM
        <div ngpTooltipArrow></div>
      </div>
    </ng-template>

    <ng-template #tooltip2>
      <div ngpTooltip>
        String selectors work great for SSR compatibility!
        <div ngpTooltipArrow></div>
      </div>
    </ng-template>
  `,
  styles: `
    app-tooltip-custom-container {
      .tooltip-container {
        position: relative;
      }

      .examples {
        display: flex;
        gap: 1rem;
        align-items: center;
        flex-wrap: wrap;
        margin: 20px 0;
      }

      .ellipsis-text {
        max-width: 200px;
        white-space: nowrap;
        overflow: hidden;
        text-overflow: ellipsis;
        font-size: 0.875rem;
      }

      .ellipsis-text:hover {
        background-color: var(--ngp-background-hover);
      }

      button {
        padding-left: 1rem;
        padding-right: 1rem;
        border-radius: 0.5rem;
        color: var(--ngp-text-primary);
        outline: none;
        height: 2.5rem;
        font-weight: 500;
        background-color: var(--ngp-background);
        transition: background-color 300ms cubic-bezier(0.4, 0, 0.2, 1);
        box-shadow: var(--ngp-button-shadow);
      }

      button[data-hover] {
        background-color: var(--ngp-background-hover);
      }

      button[data-focus-visible] {
        outline: 2px solid var(--ngp-focus-ring);
      }

      button[data-press] {
        background-color: var(--ngp-background-active);
      }
    }

    [ngpTooltip] {
      position: absolute;
      max-width: 16rem;
      border-radius: 0.5rem;
      background-color: var(--ngp-background-inverse);
      padding: 0.5rem 0.75rem;
      border: none;
      font-size: 0.75rem;
      font-weight: 500;
      color: var(--ngp-text-inverse);
      animation: tooltip-show 200ms ease-in-out;
      transform-origin: var(--ngp-tooltip-transform-origin);
    }

    [ngpTooltip][data-exit] {
      animation: tooltip-hide 200ms ease-in-out;
    }

    [ngpTooltipArrow] {
      position: absolute;
      pointer-events: none;
      background-color: var(--ngp-background-inverse);
      width: 8px;
      height: 8px;
      border-radius: 2px;
      transform: rotate(45deg);
    }

    [ngpTooltipArrow][data-placement='top'] {
      top: calc(100% - 5px);
    }

    [ngpTooltipArrow][data-placement='bottom'] {
      bottom: calc(100% - 5px);
    }

    @keyframes tooltip-show {
      0% {
        opacity: 0;
        transform: scale(0.9);
      }
      100% {
        opacity: 1;
        transform: scale(1);
      }
    }

    @keyframes tooltip-hide {
      0% {
        opacity: 1;
        transform: scale(1);
      }
      100% {
        opacity: 0;
        transform: scale(0.9);
      }
    }
  `,
  encapsulation: ViewEncapsulation.None,
})
export default class TooltipCustomContainerExample {}

```

### Cursor-Following Tooltip

You can position a tooltip at specific coordinates using the `ngpTooltipTriggerPosition` input. Combined with `ngpTooltipTriggerTrackPosition`, this enables smooth cursor-following tooltips.

## Example

```typescript
import { Component, signal, viewChild } from '@angular/core';
import { NgpTooltip, NgpTooltipTrigger } from 'ng-primitives/tooltip';

@Component({
  selector: 'app-tooltip-cursor',
  imports: [NgpTooltipTrigger, NgpTooltip],
  template: `
    <div
      class="hover-region"
      #tooltipTrigger="ngpTooltipTrigger"
      [ngpTooltipTrigger]="cursorTooltip"
      [ngpTooltipTriggerPosition]="cursorPosition()"
      (pointerenter)="onPointerEnter()"
      (pointermove)="onPointerMove($event)"
      (pointerleave)="onPointerLeave()"
      ngpTooltipTriggerTrackPosition="true"
      ngpTooltipTriggerDisabled="true"
      ngpTooltipTriggerPlacement="top"
      ngpTooltipTriggerOffset="12"
      ngpTooltipTriggerShowDelay="0"
      ngpTooltipTriggerHideDelay="0"
    >
      Hover anywhere in this region
    </div>

    <ng-template #cursorTooltip>
      <div class="ngp-tooltip-content" ngpTooltip>Position: {{ mouseX() }}, {{ mouseY() }}</div>
    </ng-template>
  `,
  styles: `
    .hover-region {
      display: flex;
      align-items: center;
      justify-content: center;
      height: 200px;
      padding: 1rem;
      border: 2px dashed var(--ngp-border);
      border-radius: 8px;
      color: var(--ngp-text-secondary);
      user-select: none;
    }

    ::ng-deep .ngp-tooltip-content {
      position: absolute;
      max-width: 16rem;
      border-radius: 0.5rem;
      background-color: var(--ngp-background-inverse);
      padding: 0.5rem 0.75rem;
      border: none;
      font-size: 0.75rem;
      font-weight: 500;
      color: var(--ngp-text-inverse);
      animation: tooltip-cursor-show 200ms ease-in-out;
      transform-origin: var(--ngp-tooltip-transform-origin);
    }

    ::ng-deep .ngp-tooltip-content[data-exit] {
      animation: tooltip-cursor-hide 200ms ease-in-out;
    }

    @keyframes tooltip-cursor-show {
      0% {
        opacity: 0;
        transform: scale(0.9);
      }
      100% {
        opacity: 1;
        transform: scale(1);
      }
    }

    @keyframes tooltip-cursor-hide {
      0% {
        opacity: 1;
        transform: scale(1);
      }
      100% {
        opacity: 0;
        transform: scale(0.9);
      }
    }
  `,
})
export default class TooltipCursorExample {
  readonly mouseX = signal(0);
  readonly mouseY = signal(0);
  readonly cursorPosition = signal<{ x: number; y: number } | null>(null);
  readonly tooltipTrigger = viewChild.required<NgpTooltipTrigger>('tooltipTrigger');

  onPointerEnter(): void {
    this.tooltipTrigger().show();
  }

  onPointerMove(event: PointerEvent): void {
    this.mouseX.set(Math.round(event.clientX));
    this.mouseY.set(Math.round(event.clientY));
    this.cursorPosition.set({ x: event.clientX, y: event.clientY });
  }

  onPointerLeave(): void {
    this.tooltipTrigger().hide();
  }
}

```

### Custom Offset

You can customize the offset using either a simple number or an object for more precise control:

```html
<!-- Simple number offset -->
<button [ngpTooltipTrigger]="tooltip" ngpTooltipTriggerOffset="12">Tooltip with 12px offset</button>

<!-- Object offset for precise control -->
<button
  [ngpTooltipTrigger]="tooltip"
  [ngpTooltipTriggerOffset]="{mainAxis: 8, crossAxis: 4, alignmentAxis: 2}"
>
  Tooltip with custom offset
</button>
```

### Custom Shift

You can customize the shift behavior to control how the tooltip stays within the viewport:

```html
<!-- Disable shift -->
<button [ngpTooltipTrigger]="tooltip" [ngpTooltipTriggerShift]="false">
  Tooltip without shift
</button>

<!-- Object shift for precise control -->
<button [ngpTooltipTrigger]="tooltip" [ngpTooltipTriggerShift]="{padding: 8}">
  Tooltip with custom shift padding
</button>
```

## API Reference

The following directives are available to import from the `ng-primitives/tooltip` package:

### NgpTooltip

## API Reference

### NgpTooltip

Apply the `ngpTooltip` directive to an element that represents the tooltip. This typically would be a `div` inside an `ng-template`.

**Selector:** `[ngpTooltip]`

#### Export As

`ngpTooltip`



#### Data Attributes

| Attribute        | Description                                                                                     |
| ---------------- | ----------------------------------------------------------------------------------------------- |
| `data-enter`     | Applied when the tooltip is being added to the DOM. This can be used to trigger animations.     |
| `data-exit`      | Applied when the tooltip is being removed from the DOM. This can be used to trigger animations. |
| `data-placement` | The final rendered placement of the tooltip.                                                    |

The following CSS custom properties are applied to the `ngpTooltip` directive:

| Property                         | Description                                         |
| -------------------------------- | --------------------------------------------------- |
| `--ngp-tooltip-transform-origin` | The transform origin of the tooltip for animations. |
| `--ngp-tooltip-trigger-width`    | The width of the trigger element.                   |

### NgpTooltipTrigger

## API Reference

### NgpTooltipTrigger

Apply the `ngpTooltipTrigger` directive to an element that triggers the tooltip to show.

**Selector:** `[ngpTooltipTrigger]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpTooltipTrigger` | `string | NgpOverlayContent<T> | null` | `-` | Access the tooltip template ref. |
| `ngpTooltipTriggerDisabled` | `boolean` | `false` | Define if the trigger should be disabled. This will prevent the tooltip from being shown or hidden from interactions. |
| `ngpTooltipTriggerPlacement` | `NgpTooltipPlacement` | `'top'` | Define the placement of the tooltip relative to the trigger. |
| `ngpTooltipTriggerOffset` | `NgpOffset` | `0` | Define the offset of the tooltip relative to the trigger.
Can be a number (applies to mainAxis) or an object with mainAxis, crossAxis, and alignmentAxis. |
| `ngpTooltipTriggerShowDelay` | `number` | `500` | Define the delay before the tooltip is displayed. |
| `ngpTooltipTriggerHideDelay` | `number` | `0` | Define the delay before the tooltip is hidden. |
| `ngpTooltipTriggerFlip` | `boolean` | `true` | Define whether the tooltip should flip when there is not enough space for the tooltip. |
| `ngpTooltipTriggerShift` | `NgpShift` | `undefined (enabled by default in overlay)` | Configure shift behavior to keep the tooltip in view.
Can be a boolean to enable/disable, or an object with padding and limiter options. |
| `ngpTooltipTriggerContainer` | `string | HTMLElement | null` | `document.body` | Define the container in which the tooltip should be attached. |
| `ngpTooltipTriggerShowOnOverflow` | `boolean` | `false` | Define whether the tooltip should only show when the trigger element overflows. |
| `ngpTooltipTriggerContext` | `T | undefined` | `-` | Provide context to the tooltip. This can be used to pass data to the tooltip content. |
| `ngpTooltipTriggerUseTextContent` | `boolean` | `true` | Define whether to use the text content of the trigger element as the tooltip content.
When enabled, the tooltip will display the text content of the trigger element. |
| `ngpTooltipTriggerTrackPosition` | `boolean` | `false` | Define whether to track the trigger element position on every animation frame.
Useful for moving elements like slider thumbs. |
| `ngpTooltipTriggerPosition` | `NgpPosition | null` | `-` | Programmatic position for the tooltip. When provided, the tooltip
will be positioned at these coordinates instead of the trigger element.
Use with trackPosition="true" for smooth cursor following. |

#### Export As

`ngpTooltipTrigger`



#### Data Attributes

| Attribute       | Description                           |
| --------------- | ------------------------------------- |
| `data-open`     | Applied when the tooltip is open.     |
| `data-disabled` | Applied when the tooltip is disabled. |

### NgpTooltipArrow

The `NgpTooltipArrow` directive is used to add an arrow to the tooltip. It should be placed inside the tooltip content. It will receive `inset-inline-start` or `inset-block-start` styles to position the arrow based on the tooltip's placement. As a result it should be positioned absolutely within the tooltip content.

The arrow can be styled conditionally based on the tooltip's final placement using the `data-placement` attribute:

```css
[ngpTooltipArrow][data-placement='top'] {
  /* Arrow styles when tooltip is positioned on top */
}

[ngpTooltipArrow][data-placement='bottom'] {
  /* Arrow styles when tooltip is positioned on bottom */
}
```

## API Reference

### NgpTooltipArrow



**Selector:** `[ngpTooltipArrow]`

#### Export As

`ngpTooltipArrow`



### Data Attributes

| Attribute        | Description                                  |
| ---------------- | -------------------------------------------- |
| `data-placement` | The final rendered placement of the tooltip. |

## Using Text Content as Tooltip

The `useTextContent` input (enabled by default) allows the tooltip to automatically use the text content of the trigger element as the tooltip content. This is particularly useful for displaying full text when content is truncated with ellipsis.

```html
<!-- Simple usage - uses text content automatically -->
<div class="truncated-text" ngpTooltipTrigger>
  This text might be truncated with ellipsis and show the full content in the tooltip
</div>

<!-- Passing content directly takes precedence -->
<button [ngpTooltipTrigger]="myToolip">This won't show a tooltip unless content is provided</button>
```

### Important: Global Styles Required

When using the `useTextContent` feature or string values, the tooltip styles **must be global** and not encapsulated to the component. This is because the tooltip content is rendered in a portal outside of your component's scope.

```css
/* ✅ Global styles (in styles.css or with ViewEncapsulation.None) */
[ngpTooltip] {
  position: absolute;
  background-color: #333;
  color: white;
  padding: 8px 12px;
  border-radius: 4px;
  font-size: 14px;
}

/* ❌ Encapsulated styles won't work with useTextContent */
.my-component [ngpTooltip] {
  /* This won't be applied to text content tooltips */
}
```

If you need component-scoped styles, use template-based or component-based tooltips instead of `useTextContent`.

## Conditional Tooltips

The `showOnOverflow` input allows you to show tooltips only when the trigger element has overflowing content. This is particularly useful for text that might be truncated with ellipsis.

```html
<div
  class="truncated-text"
  appTooltipTrigger="This tooltip only shows when text overflows"
  ngpTooltipTriggerShowOnOverflow
>
  This text might be truncated
</div>
```

## Styling

For the tooltip to be positioned correctly relative to the trigger element, it must use absolute or fixed positioning. For example, you can use the following CSS:

```css
[ngpTooltip] {
  position: absolute;
}
```

## Animations

The `ngpTooltip` primitive adds a CSS custom property `--ngp-tooltip-transform-origin` to the element that can be used to animate the tooltip from the trigger element.

The `ngpTooltip` will also add the `data-enter` and `data-exit` attributes to the element when it is being added or removed from the DOM. This can be used to trigger animations.

```css
:host[data-enter] {
  animation: fade-in 0.2s ease-in-out;
}

:host[data-exit] {
  animation: fade-out 0.2s ease-in-out;
}
```

## Global Configuration

You can configure the default options for all tooltips in your application by using the `provideTooltipConfig` function in a providers array.

```ts
import { provideTooltipConfig } from 'ng-primitives/tooltip';

bootstrapApplication(AppComponent, {
  providers: [
    provideTooltipConfig({
      offset: 4,
      placement: 'top',
      showDelay: 0,
      hideDelay: 500,
      flip: true,
      container: document.body,
      showOnOverflow: false,
      useTextContent: true,
    }),
  ],
});
```

### NgpTooltipConfig

<prop-details name="offset" type="number | NgpOffsetOptions" default="4">
Define the offset from the trigger element. Can be a number (applies to mainAxis) or an object with mainAxis, crossAxis, and alignmentAxis properties.

**Number format:** `offset: 8` - Applies to mainAxis (distance from trigger)

**Object format:**

```ts
offset: {
  mainAxis: 8,     // Distance between tooltip and trigger element
  crossAxis: 4,    // Skidding along the alignment axis
  alignmentAxis: 2 // Same as crossAxis but for aligned placements
}
```

</prop-details>

<prop-details name="shift" type="boolean | NgpShiftOptions" default="true">
Define the shift behavior to keep the tooltip in view. When enabled (default), the tooltip will shift along its axis to stay visible when it would otherwise overflow the viewport. Set to `false` to disable.

**Boolean format:** `shift: false` - Disables shift behavior

**Object format:**

```ts
shift: {
  padding: 8,     // Minimum padding between tooltip and viewport edges
  limiter: {      // Optional limiter to control shifting behavior
    fn: limitShift,
    options: { /* limiter options */ }
  }
}
```

</prop-details>

<prop-details name="placement" type="'top' | 'right' | 'bottom' | 'left'" default="top">
  Define the placement of the tooltip.
</prop-details>

<prop-details name="showDelay" type="number" default="0">
  Define the delay before the tooltip shows.
</prop-details>

<prop-details name="hideDelay" type="number" default="500">
  Define the delay before the tooltip hides.
</prop-details>

<prop-details name="flip" type="boolean" default="true">
  Define if the tooltip should flip when it reaches the edge of the viewport.
</prop-details>

<prop-details name="container" type="HTMLElement" default="document.body">
  Define the container element for the tooltip. This is the document body by default.
</prop-details>

<prop-details name="showOnOverflow" type="boolean" default="false">
  Define if the tooltip should only show when the trigger element has overflowing content. This is useful for showing tooltips only when content is truncated.
</prop-details>

<prop-details name="useTextContent" type="boolean" default="true">
  Define whether to use the text content of the trigger element as the tooltip content. When enabled, the tooltip will automatically display the text content of the trigger element. Note that this requires global styles to work properly since the tooltip is rendered in a portal.
</prop-details>


---

## Utilities

### Autofill

File: utilities/autofill.md
URL: https://angularprimitives.com/utilities/autofill

# Autofill

Detect autofill events on input elements. This can be useful for styling or behavior changes when the browser autofills an input.
Floating labels are a common use case for this directive.

## Example

```typescript
import { Component, signal } from '@angular/core';
import { NgpAutofill } from 'ng-primitives/autofill';
import { NgpLabel } from 'ng-primitives/form-field';

@Component({
  selector: 'app-autofill',
  imports: [NgpAutofill, NgpLabel],
  template: `
    <form>
      <label ngpLabel for="address-one">
        Address line

        @if (autofilled()) {
          <span>(Autofilled)</span>
        }
      </label>
      <input
        id="address-one"
        (ngpAutofill)="autofilled.set($event)"
        autocomplete="address-line1"
        required
        type="text"
        name="address-one"
        placeholder="Enter your address"
      />
    </form>
  `,
  styles: `
    :host {
      display: contents;
    }

    form {
      display: flex;
      flex-direction: column;
      gap: 6px;
      width: 90%;
    }

    [ngpLabel] {
      color: var(--ngp-text-primary);
      font-size: 0.875rem;
      line-height: 1.25rem;
      font-weight: 500;
      margin: 0;
    }

    input {
      height: 36px;
      width: 90%;
      border-radius: 8px;
      padding: 0 16px;
      border: 1px solid var(--ngp-border);
      box-shadow: var(--ngp-shadow);
      background-color: var(--ngp-background);
      outline: none;
    }

    input:focus {
      box-shadow: 0 0 0 2px rgb(59, 130, 246);
    }

    input::placeholder {
      color: var(--ngp-text-tertiary);
    }

    span {
      color: var(--ngp-text-tertiary);
    }
  `,
})
export default class AutofillExample {
  /**
   * Store the autofill state.
   */
  readonly autofilled = signal(false);
}

```

## Import

Import the Autofill primitives from `ng-primitives/autofill`.

```ts
import { NgpAutofill } from 'ng-primitives/autofill';
```

## Usage

Assemble the autofill directives in your template.

```html
<input ngpAutofill />
```

## API Reference

The following directives are available to import from the `ng-primitives/autofill` package:

### NgpAutofill

## API Reference

### NgpAutofill

Apply the `ngpAutofill` directive to an element to detect browser autofill.

**Selector:** `[ngpAutofill]`

#### Outputs

| Event | Type | Description |
|-------|------|-------------|
| `ngpAutofill` | `boolean` | Event emitted when the autofill state changes. |

#### Export As

`ngpAutofill`



#### Data Attributes

The following data attributes are applied to the `ngpAutofill` directive:

| Attribute       | Description                             |
| --------------- | --------------------------------------- |
| `data-autofill` | Applied when the element is autofilled. |


---

### Date Adapter

File: utilities/date-adapter.md
URL: https://angularprimitives.com/utilities/date-adapter

# Date Adapter

The Date Adapter is an abstraction layer that allows components to use date objects from any date library, ensuring compatibility and easy integration.

## Import

Import the DateAdapter from `ng-primitives/date-time`.

```ts
import { NgpLuxonDateAdapter } from 'ng-primitives/date-time-lucon';
import { NgpDateAdapter, NgpNativeDateAdapter } from 'ng-primitives/date-time-luxon';
```

## Usage

Angular Primitives ships with two date adapters out of the box: `NgpNativeDateAdapter` and `NgpLuxonDateAdapter`.
The `NgpNativeDateAdapter` uses the native JavaScript `Date` object, while the `NgpLuxonDateAdapter` uses the Luxon date library.

To use a date adapter, you need to provide it to Angular's dependency injection system. This can be done once at the root of your application or at a component/module level.

```ts
bootstrapApplication(AppComponent, {
  providers: [provideDateAdapter(NgpLuxonDateAdapter)],
});
```

If no date adapter is provided, the `NgpNativeDateAdapter` will be used by default.

Should you need to use a different date library, you can create your own date adapter by implementing the `NgpDateAdapter` interface.

Should you wish to use the adapter in a component, you can inject it into a component.

```ts
import { Component } from '@angular/core';
import { DateTime } from 'luxon';
import { injectDateAdapter } from 'ng-primitives/date-time';

@Component({
  selector: 'app-root',
  template: `
    ...
  `,
})
export class AppComponent {
  private readonly dateAdapter = injectDateAdapter<DateTime>();
}
```

## API Reference

All date adapters must implement the `NgpDateAdapter` interface.

```ts
interface NgpDateAdapter<T> {
  /**
   * Create a new date time object.
   */
  create(values: NgpDateUnits): T;

  /**
   * Create a new date with the current date and time.
   */
  now(): T;

  /**
   * Set the year of the date time object based on a duration.
   */
  set(date: T, values: NgpDateUnits): T;

  /**
   * Add a duration to the date time object.
   */
  add(date: T, duration: NgpDuration): T;

  /**
   * Subtract a duration from the date time object.
   */
  subtract(date: T, duration: NgpDuration): T;

  /**
   * Compare two date time objects.
   */
  compare(a: T, b: T): number;

  /**
   * Determine if two date time objects are equal.
   */
  isEqual(a: T, b: T): boolean;

  /**
   * Determine if a date time object is before another.
   */
  isBefore(a: T, b: T): boolean;

  /**
   * Determine if a date time object is after another.
   */
  isAfter(a: T, b: T): boolean;

  /**
   * Determine if two date objects are on the same day.
   */
  isSameDay(a: T, b: T): boolean;

  /**
   * Determine if two date objects are on the same month.
   */
  isSameMonth(a: T, b: T): boolean;

  /**
   * Determine if two date objects are on the same year.
   */
  isSameYear(a: T, b: T): boolean;

  /**
   * Get the year.
   */
  getYear(date: T): number;

  /**
   * Get the month.
   */
  getMonth(date: T): number;

  /**
   * Get the date.
   */
  getDate(date: T): number;

  /**
   * Get the day.
   */
  getDay(date: T): number;

  /**
   * Get the hours.
   */
  getHours(date: T): number;

  /**
   * Get the minutes.
   */
  getMinutes(date: T): number;

  /**
   * Get the seconds.
   */
  getSeconds(date: T): number;

  /**
   * Get the milliseconds.
   */
  getMilliseconds(date: T): number;

  /**
   * Get the first day of the month.
   */
  startOfMonth(date: T): T;

  /**
   * Get the last day of the month.
   */
  endOfMonth(date: T): T;

  /**
   * Get the start of the day.
   */
  startOfDay(date: T): T;

  /**
   * Get the end of the day.
   */
  endOfDay(date: T): T;
}
```


---

### Focus Trap

File: utilities/focus-trap.md
URL: https://angularprimitives.com/utilities/focus-trap

# Focus Trap

The Focus Trap utility is a directive that traps focus within a specified element. This is useful for modals, dropdowns, and other components that require focus to be contained within a specific area.

## Example

```typescript
import { Component, signal } from '@angular/core';
import { NgpButton } from 'ng-primitives/button';
import { NgpFocusTrap } from 'ng-primitives/focus-trap';

@Component({
  selector: 'app-focus-trap',
  imports: [NgpFocusTrap, NgpButton],
  template: `
    <div [ngpFocusTrapDisabled]="disabled()" ngpFocusTrap>
      <button (click)="disabled.set(false)" ngpButton>Enable Focus Trap</button>
      <button (click)="disabled.set(true)" ngpButton>Disable Focus Trap</button>
    </div>
  `,
  styles: `
    [ngpFocusTrap] {
      display: flex;
      flex-direction: column;
      align-items: center;
      gap: 1rem;
      padding: 1rem;
      border-radius: 0.5rem;
      background-color: var(--ngp-background-active);
      border: 1px dashed var(--ngp-border);
      position: relative;
    }

    [ngpFocusTrap]::before {
      position: absolute;
      top: -1.5rem;
      left: 1rem;
      font-size: 0.75rem;
      color: var(--ngp-text-secondary);
      content: 'Focus Trap Disabled';
    }

    [ngpFocusTrap][data-focus-trap]::before {
      content: 'Focus Trap Enabled';
    }

    [ngpButton] {
      padding-left: 1rem;
      padding-right: 1rem;
      border-radius: 0.5rem;
      color: var(--ngp-text-primary);
      border: 1px solid var(--ngp-border);
      outline: none;
      height: 2.5rem;
      font-weight: 500;
      background-color: var(--ngp-background);
      transition: background-color 300ms cubic-bezier(0.4, 0, 0.2, 1);
      box-shadow: var(--ngp-shadow);
    }

    [ngpButton][data-hover] {
      background-color: var(--ngp-background-hover);
    }

    [ngpButton][data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
      outline-offset: 2px;
    }

    [ngpButton][data-press] {
      background-color: var(--ngp-background-active);
    }
  `,
})
export default class FocusTrapExample {
  /**
   * Whether the focus trap is disabled.
   */
  disabled = signal(true);
}

```

## Import

Import the FocusTrap primitives from `ng-primitives/focus-trap`.

```ts
import { NgpFocusTrap } from 'ng-primitives/focus-trap';
```

## Usage

Assemble the focus-trap directives in your template.

```html
<div ngpFocusTrap></div>
```

## API Reference

The following directives are available to import from the `ng-primitives/focus-trap` package:

### NgpFocusTrap

## API Reference

### NgpFocusTrap

The `NgpFocusTrap` directive traps focus within the host element.

**Selector:** `[ngpFocusTrap]`

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ngpFocusTrapDisabled` | `boolean` | `-` | Whether the focus trap is disabled. |

#### Export As

`ngpFocusTrap`



#### Data Attributes

| Attribute         | Description                    |
| ----------------- | ------------------------------ |
| `data-focus-trap` | Applied when focus is trapped. |

## Accessibility

Adheres to the [WAI-ARIA design pattern](https://www.w3.org/TR/UNDERSTANDING-WCAG20/keyboard-operation-trapping.html).


---

### Visually Hidden

File: utilities/visually-hidden.md
URL: https://angularprimitives.com/utilities/visually-hidden

# Visually Hidden

Hide an element visually while keeping it present in the DOM. This is particularly useful for accessibility purposes, ensuring that screen readers and other assistive technologies can still interact with the hidden content.

## Import

Import the VisuallyHidden primitives from `ng-primitives/a11y`.

```ts
import { NgpVisuallyHidden } from 'ng-primitives/a11y';
```

## Usage

Assemble the visually-hidden directives in your template.

```html
<div ngpVisuallyHidden></div>
```

## API Reference

The following directives are available to import from the `ng-primitives/a11y` package:

### NgpVisuallyHidden

## API Reference

### NgpVisuallyHidden

Hide an element visually while keeping it present in the DOM.

**Selector:** `[ngpVisuallyHidden]`

#### Export As

`ngpVisuallyHidden`



## Accessibility

This directive can be useful for hiding content that is still important for screen readers and other assistive technologies.


---