Carousel | Neural Native

Import

component.ts

import { NeuCarouselComponent } from '@neural-ui/native/carousel';

Examples

Import ExampleComponent into its parent and place <app-example /> inside your application’s root neu-theme. The preview supplies the device frame and safe areas; use the root setup from Installation in your app.

A moment outside

Swipe through the collection or tap an image to open the viewer. Automatic playback pauses while the viewer is open.

View and copy the complete example

basic.component.ts

import { Component, signal } from '@angular/core';
import { NeuSwitchComponent } from '@neural-ui/native/switch';
import { NeuCarouselComponent } from '@neural-ui/native/carousel';
import { View, Text, ScrollView } from '@ng-native/components';
import type { NeuImageItem } from '@neural-ui/native';

@Component({
  selector: 'app-example',
  imports: [NeuSwitchComponent, NeuCarouselComponent, View, Text, ScrollView],
  template: `
    <scroll-view class="product-scroll" keyboardShouldPersistTaps="handled" [showsVerticalScrollIndicator]="false"><view class="product-stack"><view class="product-section"><text class="product-title" accessibilityRole="header">A moment outside</text><text class="product-caption">Landscape studies · Neural collection</text></view>
    <neu-carousel [items]="images" [(index)]="index" [(open)]="open" [loop]="loop()" [autoplay]="autoplay()" [autoplayInterval]="4000" />
    <view class="product-surface">
      <text class="product-heading">Slideshow preferences</text>
      <neu-switch label="Automatic playback" [(checked)]="autoplay" />
      <neu-switch label="Loop slides" [(checked)]="loop" />
      <text class="product-caption">Swipe to explore. Pause whenever you want to stay a little longer.</text>
    </view></view></scroll-view>
  `,
  styles: `
.actions { gap: 12px; align-items: flex-start; } text { color: var(--neu-text, #172033); font-size: 16px; }

:host { flex: 1; flex-shrink: 1; min-height: 0; }
.product-scroll { flex: 1; flex-shrink: 1; height: 0px; min-height: 0; }
.product-stack { gap: 24px; padding-bottom: 20px; }
.product-section { gap: 12px; }
.product-row { flex-direction: row; align-items: center; gap: 12px; }
.product-copy { flex: 1; min-width: 0; gap: 4px; }
.product-title { color: var(--neu-text, #172033); font-size: 24px; line-height: 30px; font-weight: 600; }
.product-heading { color: var(--neu-text, #172033); font-size: 17px; line-height: 23px; font-weight: 600; }
.product-caption { color: var(--neu-muted, #596477); font-size: 14px; line-height: 20px; }
.product-actions { flex-direction: row; flex-wrap: wrap; align-items: center; gap: 8px; }
.product-surface { gap: 16px; padding: 16px; border-radius: 16px; background-color: var(--neu-surface, #ffffff); border-width: 1px; border-color: var(--neu-border, #a5afbf); }

  `,
})
export class ExampleComponent {
  readonly images: readonly NeuImageItem[] = [
    {
      "id": "forest",
      "label": "Forest walk",
      "uri": "/assets/media/v2/forest.png"
    },
    {
      "id": "desert",
      "label": "Desert shapes",
      "uri": "/assets/media/v2/desert.png"
    },
    {
      "id": "night",
      "label": "Night sky",
      "uri": "/assets/media/v2/night.png"
    },
    {
      "id": "coast",
      "label": "Quiet horizon",
      "uri": "/assets/media/v2/coast.png"
    }
  ];
  readonly index = signal(0);
  readonly open = signal(false);
  readonly autoplay = signal(false);
  readonly loop = signal(true);
}

Interactive playground

Change the settings and try the result.

Device captures shown in English.

Carousel · android · native capture — **Android**Native screenshot

Carousel · ios · native capture — **iOS**Native screenshot

API reference

Inputs

Name	Type	Default	Binding	Description
items	readonly NeuImageItem[]	[]	Input	Ordered data for the component. Use the data contract below and stable, unique item IDs.
preview	boolean	true	Input	Open the full-screen viewer when an image is pressed. Enabled by default. Swipes change slides without opening the viewer. Set false for a noninteractive image surface.
viewerLabels	NeuImageViewerLabels	{}	Input	Optional text for the embedded viewer: label, closeLabel, previousLabel, nextLabel, zoomLabel, zoomOutLabel and errorLabel. Previous and next labels fall back to the carousel labels.
loop	boolean	false	Input	Allows navigation from last to first and first to last, by arrows, swipe or autoplay. It does not start automatic playback; enable autoplay for that.
autoplay	boolean	false	Input	Automatically advances slides at autoplayInterval and shows a pause/play control. Off by default. Pauses during touch interaction, while the viewer is open and with reduced motion. Without loop it stops on the last image.
autoplayInterval	number	4000	Input	Delay between automatic advances in milliseconds, default 4000. Zero or negative stops automatic playback. Positive values are bounded to 1000–60000; nonfinite values use 4000. Manual navigation restarts the delay.
pauseLabel	string	'Pause slideshow'	Input	Accessible name of the slideshow pause button, displayed only when autoplay is enabled and multiple slides exist.
playLabel	string	'Play slideshow'	Input	Accessible name of the button that resumes a user-paused slideshow. It restarts the interval without immediately skipping a slide.
previousLabel	string	'Previous image'	Input	Text or accessible name used for previous. It does not perform the action by itself.
nextLabel	string	'Next image'	Input	Text or accessible name used for next. It does not perform the action by itself.
emptyLabel	string	'No images'	Input	Text or accessible name used for empty state. It does not perform the action by itself.

Models

Name	Type	Default	Binding	Description
index	number	0	Model · two-way	Current zero-based image or carousel position. Bind a writable signal with [(index)].
open	boolean	false	Model · two-way	Whether the carousel image viewer is open. Shares the current index with the carousel; automatic playback pauses until the viewer closes.

Outputs

Name	Payload	When it emits
indexChange	number	Emits the updated index value. [(index)] binds this output together with its model input.
openChange	boolean	Emits the updated open value. [(open)] binds this output together with its model input.

Model state

Bind the signal with [(modelName)] without calling it. Use modelName() to read its value.

model-fields.ts

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

// Fields inside your component class
readonly index = signal<number>(0);
readonly open = signal<boolean>(false);

Types and data interfaces

Use the imports in your application. The definitions below are provided for reference.

NeuImageItem

NeuImageItem.ts

import type { NeuImageItem } from '@neural-ui/native';

// Public definition for reference only. Import this type; do not redeclare it.
export interface NeuImageItem {
    readonly id: string;
    readonly uri: string;
    readonly label: string;
}

Field	Type	Requirement	Meaning
id	string	Required	Stable, unique identifier used for tracking and selection.
uri	string	Required	Native image or file URI.
label	string	Required	Human-readable item name.

NeuImageViewerLabels

NeuImageViewerLabels.ts

import type { NeuImageViewerLabels } from '@neural-ui/native/image-viewer';

// Public definition for reference only. Import this type; do not redeclare it.
export interface NeuImageViewerLabels {
    readonly label?: string;
    readonly closeLabel?: string;
    readonly previousLabel?: string;
    readonly nextLabel?: string;
    readonly zoomLabel?: string;
    readonly zoomOutLabel?: string;
    readonly errorLabel?: string;
}

Field	Type	Requirement	Meaning
label	string	Optional	Human-readable item name.
closeLabel	string	Optional	Accessible name of the image viewer close action.
previousLabel	string	Optional	Accessible name of the previous-image action.
nextLabel	string	Optional	Accessible name of the next-image action.
zoomLabel	string	Optional	Accessible name of the zoom-in action.
zoomOutLabel	string	Optional	Accessible name of the zoom-out action.
errorLabel	string	Optional	Message announced when the image cannot be loaded.