Installation

Before installing

Create your application with the official Angular Native template: it configures the framework runtime dependencies. These versions identify our tested environment. Additional native modules depend on the features your app uses.

Use npm with its default peer dependency resolution. Android requires an SDK and emulator or a compatible phone; the iOS simulator requires macOS and Xcode. You can also open a compatible app in Expo Go on a physical device.

1. Create an Angular Native app

Start with the official template, pinned to the framework version supported by this release. It installs Angular and the framework runtime, configures Metro and creates src/main.ts and src/app/app.ts. If your app already uses Angular Native 0.18.2, skip this step.

npx create-expo-app@latest my-neural-app --template @ng-native/template@0.18.2
cd my-neural-app

Official Angular Native setup

2. Install Neural Native

Run the command in the application directory, alongside package.json. Installation includes all 64 components and resolves the declared dependencies and required peers.

npm install @neural-ui/native@beta

There is no global Neural Native provider to add to app.config, no NgModule to import and no global theme stylesheet to load. The next step imports the controls and applies the theme in an Angular component.

3. Create your first screen

Replace src/app/app.ts in the generated template with this complete example. Keep the exported class named App: the generated entry point already mounts it. The input updates an Angular signal, and the button displays a confirmation when pressed.

import { Component, inject, signal } from '@angular/core';
import { SafeAreaProvider, SafeAreaView, Text, View } from '@ng-native/components';
import { StatusBar } from '@ng-native/device';
import { NeuThemeComponent } from '@neural-ui/native/theme';
import { NeuInputComponent } from '@neural-ui/native/input';
import { NeuButtonComponent } from '@neural-ui/native/button';

@Component({
  selector: 'app-root',
  imports: [
    SafeAreaProvider, SafeAreaView, View, Text,
    NeuThemeComponent, NeuInputComponent, NeuButtonComponent,
  ],
  template: `
    <safe-area-provider>
      <neu-theme scheme="system">
        <safe-area-view class="screen">
          <view class="body">
            <neu-input label="Full name" placeholder="Enter your name" [(value)]="name" />
            <neu-button label="Save profile" (pressed)="save()" />
            <text class="feedback">{{ feedback() }}</text>
          </view>
        </safe-area-view>
      </neu-theme>
    </safe-area-provider>
  `,
  styles: `
    :host, .screen { flex: 1; }
    .body { padding: 24px; gap: 16px; }
    .feedback { color: var(--neu-text); }
  `,
})
export class App {
  readonly name = signal('');
  readonly feedback = signal('');

  constructor() {
    inject(StatusBar).set({ style: 'auto' });
  }

  save(): void {
    const name = this.name().trim();
    this.feedback.set(name ? 'Saved: ' + name : 'Enter your name.');
  }
}

SafeAreaProvider and SafeAreaView respect the device insets. NeuTheme supplies the shared theme, scheme="system" follows the device appearance, and component imports make the lowercase selectors available in this template.

4. Test your screen

Replace the generated src/app/app.test.ts counter test with these tests for the profile form. They check both a saved name and empty submission.

import { cleanup, fireEvent, render, screen, userEvent } from '@ng-native/testing';
import { afterEach, expect, test } from 'vitest';
import { App } from './app.ts';

afterEach(cleanup);

test('saves the profile name', async () => {
  await render(App);
  await fireEvent.changeText(screen.getByLabelText('Full name'), 'Ada');
  await userEvent.setup().press(screen.getByRole('button', { name: 'Save profile' }));
  expect(screen.getByText('Saved: Ada')).toBeTruthy();
});

test('asks for a name before saving', async () => {
  await render(App);
  await userEvent.setup().press(screen.getByRole('button', { name: 'Save profile' }));
  expect(screen.getByText('Enter your name.')).toBeTruthy();
});

In vitest.config.mts, include the distributed library in ngNative's inline option. This is the complete configuration for this example; preserve any additional test settings your application needs.

import { ngNative } from '@ng-native/testing/vitest';
import { defineConfig } from 'vitest/config';

export default defineConfig({
  plugins: [ngNative({ inline: ['@neural-ui/native'] })],
});

5. Run the application

npm start

Metro opens the development server. Press a to open Android or i to open the iOS simulator, or scan the QR code with a compatible Expo Go app. The result should show a Full name input and a Save profile button. Type a name and press the button to confirm that the state and events work.

Run the template checks after editing. A typecheck validates TypeScript and Angular templates; it does not replace interaction tests on a device.

npm run typecheck
npm test

Adding it to an existing project

An existing Angular Native app only needs the package installation, component imports and a theme wrapper around the intended screen. Keep its existing bootstrap and application services. A standard Angular web app needs the Angular Native Web renderer to run these components; installing the package alone does not turn a web app into a native app.

Continue with project configuration

If something does not work

npm ls @neural-ui/native @angular/core @ng-native/components @ng-native/device @ng-native/icons
npx expo install --check

Check version compatibility