Carousel | Neural UI v2

Usage

Pass items and render each one with neuCarouselItem. numVisible sets the visible count and numScroll sets the page step. responsiveOptions overrides these counts below each breakpoint. Use page for a controlled zero-based page, or leave it unset and choose initialPage for internal navigation. circular wraps at either end. autoplayInterval is measured in milliseconds; 0 disables it. Autoplay can be paused and respects reduced motion.

Examples

Try the interaction and open Code for the complete implementation.

Coastal light

A quiet horizon in blue.

Applied page: 1 · pageChange: 0

Try and configure

Change the options, try the result and see the template update. Code contains the full executable example.

Coastal light

A quiet horizon in blue.

Applied page: 1 · pageChange: 0

Advanced options · 7

Template generated from your current options. Open Code for the complete example.

<neu-carousel
  [items]="collections"
  [page]="page()"
  [numVisible]="1"
  [numScroll]="1"
  orientation="horizontal"
  [responsiveOptions]="responsiveOptions"
  [circular]="false"
  [autoplayInterval]="0"
  [showNavigators]="true"
  [showIndicators]="true"
  ariaLabel="Featured collections"
  (pageChange)="page.set($event.page)"
  [emptyLabel]="'No collections'"
  [indicatorLabel]="'Collection pages'"
  [nextLabel]="'Next collection'"
  [previousLabel]="'Previous collection'"
>
  <ng-template neuCarouselItem let-item>
    <neu-card [bordered]="true" [flat]="true" padding="md">
      <img [src]="item.src" [alt]="item.title" />
      <h3>{{ item.title }}</h3>
      <p>{{ item.description }}</p>
    </neu-card>
  </ng-template>
</neu-carousel>

State and data for this configuration

These values match the current preview. Complete handlers, Core imports and templates are in Source.

import { signal } from '@angular/core';

export const collections = [
  {
    "id": "coast",
    "title": "Coastal light",
    "description": "A quiet horizon in blue.",
    "src": "assets/media/coast.svg"
  },
  {
    "id": "forest",
    "title": "Forest walk",
    "description": "Layers of green and soft light.",
    "src": "assets/media/forest.svg"
  },
  {
    "id": "desert",
    "title": "Desert shapes",
    "description": "Warm sand and distant hills.",
    "src": "assets/media/desert.svg"
  },
  {
    "id": "night",
    "title": "Night sky",
    "description": "Stars above a mountain ridge.",
    "src": "assets/media/night.svg"
  }
];

export const page = signal(0);

export const responsiveOptions = [
  {
    "breakpoint": 640,
    "numVisible": 1,
    "numScroll": 1
  }
];

Data, callback and structured configuration inputs

Data and content

Accept pageChange by updating page. The event includes page and first, the first visible item index. Core does not mutate your collection. Use stable item identities with trackBy. Header and footer Templates stay outside the paged item region.

Accessibility and keyboard

Name the region and translate previousLabel, nextLabel, indicatorLabel and emptyLabel. Arrow keys, Home and End move between pages when focus is outside projected item controls. Left/right follow text direction. Vertical orientation uses up/down. Provide useful image alternatives and keep interactive item content keyboard accessible.

Key	Action
`Tab`	Reach navigation controls and focusable projected item content.
`ArrowLeft / ArrowRight`	In horizontal orientation, change page following text direction, outside projected controls.
`ArrowUp / ArrowDown`	In vertical orientation, move between pages outside projected controls.
`Home`	Go to the first page.
`End`	Go to the last page.
`Enter`	Activate the focused navigation or page-indicator button.
`Space`	Activate the focused navigation or page-indicator button.

API

Inputs and Outputs match the installed package. Named types link to definitions. Every available Template has a Demo and Code example.

Inputs

Configure the component with [property]="value". Your application supplies these values; the component does not replace the state you pass in.

Name	Type	Default	Template binding	Description
`ariaLabel`	`string`	`'Carousel'`	`[ariaLabel]`	Label for component region. Translate it for your application.
`autoplayInterval`	`number`	`0`	`[autoplayInterval]`	Autoplay delay in milliseconds; 0 disables it.
`circular`	`boolean`	`false`	`[circular]`	Wrap navigation between the first and last pages.
`emptyLabel`	`string`	`'No items'`	`[emptyLabel]`	Label for empty collection. Translate it for your application.
`indicatorLabel`	`string`	`'Carousel pages'`	`[indicatorLabel]`	Label for page indicators. Translate it for your application.
`initialPage`	`number`	`0`	`[initialPage]`	Initial zero-based page for uncontrolled navigation.
`items`	`readonly T[]`	`[]`	`[items]`	Read-only collection; render objects with neuCarouselItem.
`nextLabel`	`string`	`'Next items'`	`[nextLabel]`	Label for next navigation. Translate it for your application.
`numScroll`	`number`	`1`	`[numScroll]`	Positive item offset between consecutive pages.
`numVisible`	`number`	`1`	`[numVisible]`	Positive number of visible items per page.
`orientation`	`"horizontal" \| "vertical"`	`'horizontal'`	`[orientation]`	Arrange and navigate content horizontally or vertically.
`page`	`number \| null`	`null`	`[page]`	Applied zero-based page; null uses internal state.
`previousLabel`	`string`	`'Previous items'`	`[previousLabel]`	Label for previous navigation. Translate it for your application.
`responsiveOptions`	`readonly NeuCarouselResponsiveOption[]`	`[]`	`[responsiveOptions]`	Breakpoint overrides for numVisible and numScroll.
`showIndicators`	`boolean`	`true`	`[showIndicators]`	Show the page-indicator buttons.
`showNavigators`	`boolean`	`true`	`[showNavigators]`	Show previous and next controls.
`trackBy`	`(index: number, item: T) => unknown`	`(index) => index`Derived default	`[trackBy]`	Stable identity function receiving absolute index and item.
`verticalViewPortHeight`	`string`	`'20rem'`	`[verticalViewPortHeight]`	CSS viewport height for vertical orientation.

Outputs

Listen to an event with (event)="handler($event)". The table explains the data your handler receives and how to use it.

Name	Payload	Template binding	Description
`pageChange`	`NeuCarouselPageEvent`	`(pageChange)="onPageChange($event)"`	Proposed page plus its first visible item index.

Templates

ng-content projects content into the component. TemplateRef inputs receive a template; ng-template directives identify templates with a typed context. A directive shared by an entrypoint is not necessarily a slot of this component.

Name	Mechanism	Contract
`NeuCarouselFooterDirective`View example	Public template directive (entrypoint)	`ng-template[neuCarouselFooter]`
`NeuCarouselHeaderDirective`View example	Public template directive (entrypoint)	`ng-template[neuCarouselHeader]`
`NeuCarouselItemDirective`View example	Public template directive (entrypoint)	`ng-template[neuCarouselItem]`

NeuCarouselFooterDirectiveView example

Public template directive (entrypoint)

ng-template[neuCarouselFooter]

Declaration

Full context

NeuCarouselHeaderDirectiveView example

Public template directive (entrypoint)

ng-template[neuCarouselHeader]

Declaration

Full context

NeuCarouselItemDirectiveView example

Public template directive (entrypoint)

ng-template[neuCarouselItem]

Declaration

Full context

import type { NeuCarouselItemContext } from '@neural-ui/core/carousel';

import { NeuCarouselItemDirective } from '@neural-ui/core/carousel';

// Public declaration (reference only)
readonly templateRef: TemplateRef<NeuCarouselItemContext<T>>;

Each example demonstrates a different template. Switch between Demo and Code to inspect its implementation, imports and state.

Header

NeuCarouselHeaderDirective

Discover the collection

The header stays outside the moving items.

Coastal light

A quiet horizon in blue.

Applied page: 1 · pageChange: 0

Item content

NeuCarouselItemDirective

Coastal light

A quiet horizon in blue.

Item 1

Applied page: 1 · pageChange: 0

Public Types

Open a type to inspect its definition and interface fields.

NeuCarouselItemContextTypeScript

import type { NeuCarouselItemContext } from '@neural-ui/core/carousel';

// Public declaration (reference only)
export interface NeuCarouselItemContext<T> {
  $implicit: T;
  index: number;
}

NeuCarouselPageEventTypeScript

import type { NeuCarouselPageEvent } from '@neural-ui/core/carousel';

// Public declaration (reference only)
export interface NeuCarouselPageEvent {
  first: number;
  page: number;
}

NeuCarouselResponsiveOptionTypeScript

import type { NeuCarouselResponsiveOption } from '@neural-ui/core/carousel';

// Public declaration (reference only)
export interface NeuCarouselResponsiveOption {
  breakpoint: string | number;
  numScroll?: number;
  numVisible: number;
}

Styles and tokens

Customize supported public tokens and check both themes. Example illustrations and application state are not Core inputs.

Specific tokens

This component uses shared theme tokens rather than dedicated component hooks.

Shared tokens used

Override these on a local wrapper to affect this example. An override on :root affects other components that use the same token.

Token	Purpose here	Other impact	Default / fallback
`--neu-border`	Normal control and cell borders	Shared by other Core consumers; scope the override.	`rgba(15, 23, 42, 0.08)`
`--neu-focus-ring`	Normal keyboard-focus ring	Shared by other Core consumers; scope the override.	`0 0 0 var(--neu-focus-ring-width) rgba(0, 122, 255, 0.15)`
`--neu-primary`	Brand color for active controls and emphasis	Shared by other Core consumers; scope the override.	`#007aff`
`--neu-surface`	Main field, header or control surface	Shared by other Core consumers; scope the override.	`#ffffff`
`--neu-text`	Main text and inherited icon color	Shared by other Core consumers; scope the override.	`#0f172a`
`--neu-space-2`	Spacing between content and controls	Shared by other Core consumers; scope the override.	`0.5rem`
`--neu-space-3`	Spacing between content and controls	Shared by other Core consumers; scope the override.	`0.75rem`
`--neu-transition`	Timing of state changes	Shared by other Core consumers; scope the override.	`200ms ease`

Related components

Use related components to complete your interface.