Project configuration

Do I need to edit app.config?

No global configuration is required by Neural Native. It does not expose an application-wide initialization provider. The official Angular Native 0.18.2 template boots through src/main.ts and does not require an app.config.ts file for these controls. Importing a control makes it available to that component; NeuTheme configures the theme for its descendants.

If your application already groups providers in app.config, keep them for its routing, HTTP or services and pass them through the bootstrap configured by Angular Native. Neural Native does not replace that configuration. Providers and global styles from Neural UI for the web are not required by this native package.

Project files: what to change

For a new app created with the official template, start by installing Neural Native and editing src/app/app.ts. The framework already prepares the entry point and Metro. The file paths below are relative to the application directory.

my-neural-app/
├── package.json
├── package-lock.json
├── app.json
├── metro.config.js
├── tsconfig.json
├── vitest.config.mts
└── src/
    ├── main.ts
    └── app/
        ├── app.ts
        └── app.test.ts

src/app/app.ts: add your screen

This is the file to edit for your first Neural Native screen. In the newly generated template, replace its contents with the complete example below. In an existing app, add the imports and controls to your current component while keeping its existing logic.

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.');
  }
}

The three places to edit are the TypeScript imports at the top, the imports array in @Component and the template. State and action methods belong inside export class App. Keep that class name because the generated entry point imports App.

The example places both controls on the same screen. Their signal state updates as you interact with them.

src/main.ts: keep the generated entry point

You do not need to add anything to this file for Neural Native. The official template already starts the framework and renders App. Keep the complete generated entry point. The following is only the import that connects it to your screen, not a replacement for the file.

// Keep this import in the generated src/main.ts.
import { App } from './app/app.ts';

No app.config.ts file or extra initialization provider is required by the library. Editing the screen exported from src/app/app.ts is enough to make it appear through this existing bootstrap.

package.json: npm adds the dependency

Run this command from the application directory. Let npm update package.json and package-lock.json.

npm install @neural-ui/native@beta

This fragment shows the dependency from the documented baseline. npm saves the version it installs; keep the other dependencies, scripts and configuration created by the template. The lockfile records the exact installed versions.

{
  "dependencies": {
    "@neural-ui/native": "0.1.0-beta.1"
  }
}

metro.config.js: template configuration

The official template already contains this integration. You normally do not change it to add Neural Native. For an existing Expo app without Angular Native, complete the framework manual setup before installing the component library.

const { getDefaultConfig } = require('expo/metro-config');
const { withAngularNative } = require('@ng-native/metro/config.cjs');

module.exports = withAngularNative(getDefaultConfig(__dirname));

Angular Native manual setup

Theme and native layout

Configure the shared appearance in the root NeuTheme: scheme chooses the mode and tokens supplies overrides. Safe-area primitives and flex: 1 let the content fill the available screen.

Theme customization is optional. In the App shown above, add this type import alongside the other imports at the top of src/app/app.ts.

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

Add this property inside export class App, alongside name and feedback. Keep the existing properties and methods.

  readonly tokens = {
    accent: '#3B5BDB',
    onAccent: '#FFFFFF',
    radius: 16,
  } satisfies Partial<NeuTokens>;

Finally, add [tokens] to the existing neu-theme opening tag in the template. Keep the screen content and closing tag in place.

<neu-theme scheme="system" [tokens]="tokens">

Explore theming

See all design tokens

app.json: application options

The generated app.json already enables automatic appearance and iPad support. This fragment shows the relevant fields; merge changes into the existing file rather than replacing its icons, identifiers or other plugins. These options describe your app, not a Neural Native global configuration.

{
  "expo": {
    "name": "My Neural App",
    "slug": "my-neural-app",
    "platforms": [
      "ios",
      "android"
    ],
    "userInterfaceStyle": "automatic",
    "ios": {
      "supportsTablet": true
    },
    "plugins": [
      "@ng-native/metro"
    ]
  }
}

If you add a native module or change a native plugin, restart Metro and rebuild the native host when the change requires it. Expo Go can only run modules included in its runtime; use a development build for additional native integrations.

Signals and forms

For a simple input, [(value)] binds directly to an Angular signal. Checkbox and Switch use [(checked)]. You do not need FormsModule or ngModel for these bindings. Import each control in the component whose template uses it, even if another screen already imported that control.

Signal Forms is optional for validation and field state. Install @angular/forms at the same version as the app Angular packages, import FormField from @angular/forms/signals in the consuming component and follow the forms guide.

Connect a complete form

CSS inside a component or in a separate file

Define CSS in the component through styles, or in a separate file through styleUrl. Use styleUrls for several stylesheets. Angular Native compiles this CSS for its native renderer.

Our short examples use styles so everything is visible in one block. In your project, create the following two files and place app-summary inside the existing root neu-theme. Import SummaryComponent into its parent. No global CSS import or bootstrap change is needed.

import { Component } from '@angular/core';
import { Text, View } from '@ng-native/components';

@Component({
  selector: 'app-summary',
  imports: [Text, View],
  template: `
    <view class="panel">
      <text class="title">Your workspace</text>
      <text class="description">Shared with your team</text>
    </view>
  `,
  styleUrl: './summary.component.css',
})
export class SummaryComponent {}

.panel {
  padding: var(--neu-spacing);
  gap: 8px;
  background-color: var(--neu-surface);
  border-radius: var(--neu-radius);
}

.title {
  color: var(--neu-text);
  font-size: var(--neu-font-size);
  font-weight: 600;
}

.description {
  color: var(--neu-muted);
  font-size: 14px;
}

Choose styles or styleUrl for this example; do not duplicate the same rules in both. Class selectors and the theme variables work in either location. Native layout follows the framework’s supported CSS features, so use its native flex layouts rather than assuming every browser CSS feature is available.

Language, direction and dates

The documentation language selector changes this website. In your app, supply translated labels, hints, errors, empty states and accessibility names. Keep option IDs and stored values stable when translating their visible labels.

<neu-date-input label="Fecha de entrega" locale="es" [(value)]="deliveryDate" />
<neu-calendar locale="es" [(value)]="selectedDate" />

Declare deliveryDate and selectedDate as writable signals in the surrounding component and import the two controls. DateInput and Calendar use locale for their date UI; their date values remain YYYY-MM-DD, independent of the displayed language. Do not use a localized display string as the stored date or convert a date-only value through UTC without deciding your app’s time-zone rules.

locale formats dates and calendar names. Supply action labels such as closeLabel, previousLabel and nextLabel in your app language too. TreeSelect exposes expandLabel and emptyLabel; Uploader accepts stateLabels for its four visible states. The API reference lists the available labels for each component.

For right-to-left languages, configure direction through the native framework and verify the whole screen on each platform. Translation alone does not mirror layouts or directional icons. Check reading order, start/end spacing, long labels and enlarged text; retain the original orientation of non-directional symbols and media.

Feature-specific integrations

Configure file selection and uploads

Explore the icon integration