Ionic

Mobile-first Ionic field components for ng-forge dynamic forms, optimized for iOS and Android with native platform styling.

Installation

Install the package and its peer dependencies:

npm install @ng-forge/dynamic-forms @ng-forge/dynamic-forms-ionic @ionic/angular

Quick Start

1. Configure Providers

Add Ionic field types to your application:

// app.config.ts
import { ApplicationConfig } from '@angular/core';
import { provideDynamicForm } from '@ng-forge/dynamic-forms';
import { withIonicFields } from '@ng-forge/dynamic-forms-ionic';

export const appConfig: ApplicationConfig = {
  providers: [provideDynamicForm(...withIonicFields())],
};

2. Import Ionic Styles

Add Ionic core styles to your application:

@import '@ionic/angular/css/core.css';
@import '@ionic/angular/css/normalize.css';
@import '@ionic/angular/css/structure.css';
@import '@ionic/angular/css/typography.css';

// Optional: Additional Ionic utility styles
@import '@ionic/angular/css/padding.css';
@import '@ionic/angular/css/float-elements.css';
@import '@ionic/angular/css/text-alignment.css';
@import '@ionic/angular/css/text-transformation.css';
@import '@ionic/angular/css/flex-utils.css';

3. Create Your First Form

import { Component, signal } from '@angular/core';
import { JsonPipe } from '@angular/common';
import { DynamicForm, type FormConfig } from '@ng-forge/dynamic-forms';

@Component({
  selector: 'app-contact-form',
  imports: [DynamicForm, JsonPipe],
  template: `
    <form [dynamic-form]="config" [(value)]="formValue"></form>
    @let value = formValue();
    <pre>{{ value | json }}</pre>
  `,
})
export class ContactFormComponent {
  formValue = signal({});

  config = {
    fields: [
      {
        key: 'name',
        type: 'input',
        label: 'Full Name',
        value: '',
        required: true,
        props: {
          placeholder: 'Enter your name',
        },
      },
      {
        key: 'email',
        type: 'input',
        label: 'Email',
        value: '',
        required: true,
        email: true,
        props: {
          type: 'email',
          placeholder: 'your@email.com',
        },
      },
      {
        key: 'message',
        type: 'textarea',
        label: 'Message',
        value: '',
        required: true,
        minLength: 10,
        props: {
          placeholder: 'Your message here...',
          rows: 4,
          autoGrow: true,
        },
      },
      {
        type: 'submit',
        key: 'submit',
        label: 'Send Message',
        props: {
          color: 'primary',
          expand: 'block',
        },
      },
    ],
  } as const satisfies FormConfig;
}

Complete Form Example

Here's a full registration form showcasing multiple Ionic field types optimized for mobile:

{
  fields: [
    { key: 'firstName', type: 'input', label: 'First Name', required: true, minLength: 2,
      validationMessages: { required: 'This field is required', minLength: 'Must be at least {{requiredLength}} characters' },
      props: { placeholder: 'Enter your first name' } },
    { key: 'lastName', type: 'input', label: 'Last Name', required: true, minLength: 2,
      validationMessages: { required: 'This field is required', minLength: 'Must be at least {{requiredLength}} characters' },
      props: { placeholder: 'Enter your last name' } },
    { key: 'email', type: 'input', label: 'Email Address', required: true, email: true,
      validationMessages: { required: 'This field is required', email: 'Please enter a valid email address' },
      props: { type: 'email', placeholder: 'user@example.com', helperText: 'We will never share your email' } },
    { key: 'age', type: 'input', label: 'Age', required: true, min: 18, max: 120,
      validationMessages: { required: 'This field is required', min: 'Must be at least {{min}}', max: 'Must not exceed {{max}}' },
      props: { type: 'number', placeholder: '18' } },
    { key: 'country', type: 'select', label: 'Country', required: true,
      validationMessages: { required: 'This field is required' },
      options: [
        { value: 'us', label: 'United States' }, { value: 'uk', label: 'United Kingdom' },
        { value: 'ca', label: 'Canada' }, { value: 'au', label: 'Australia' },
        { value: 'de', label: 'Germany' }, { value: 'fr', label: 'France' }, { value: 'jp', label: 'Japan' }
      ],
      props: { placeholder: 'Select your country' } },
    { key: 'plan', type: 'select', label: 'Subscription Plan', required: true,
      validationMessages: { required: 'This field is required' },
      options: [
        { value: 'free', label: 'Free - $0/month' }, { value: 'pro', label: 'Pro - $10/month' },
        { value: 'enterprise', label: 'Enterprise - $50/month' }
      ],
      props: { placeholder: 'Choose a plan' } },
    { key: 'bio', type: 'textarea', label: 'Bio',
      props: { placeholder: 'Tell us about yourself', helperText: 'Optional - share a bit about yourself', rows: 4, autoGrow: true } },
    { key: 'newsletter', type: 'checkbox', label: 'Subscribe to newsletter', props: { labelPlacement: 'end' } },
    { type: 'submit', key: 'submit', label: 'Create Account', props: { color: 'primary', expand: 'block' } },
  ],
}

This example demonstrates:

• Text inputs with mobile keyboard optimization
• Select dropdowns with native action sheets
• Checkboxes and toggles with Ionic styling
• Radio buttons
• Date/time pickers with native selectors
• Range sliders with pin display
• Multi-checkbox selections
• Form submission

Field Types Reference

Complete reference for all Ionic field types with mobile-first design, native platform styling, and comprehensive validation.

Text Input Fields

Text input fields provide mobile-optimized text entry with platform-specific keyboards.

Input

Text input field with mobile keyboard optimization and platform-adaptive styling.

Live Demo:

{
  key: 'email',
  type: 'input',
  label: 'Email Address',
  value: '',
  props: {
    type: 'email',
    placeholder: 'Enter your email',
  },
}

Basic Usage:

{
  key: 'email',
  type: 'input',
  label: 'Email Address',
  value: '',
  required: true,
  email: true,
  props: {
    type: 'email',
    placeholder: 'your@email.com',
    clearInput: true,
  },
}

Field Properties:

Validation Properties:

Props (Ionic-Specific):

Textarea

Multi-line text input field with auto-grow support for mobile devices.

Live Demo:

{
  key: 'bio',
  type: 'textarea',
  label: 'Biography',
  value: '',
  maxLength: 500,
  props: {
    rows: 6,
    placeholder: 'Tell us about yourself',
    autoGrow: true,
  },
}

Basic Usage:

{
  key: 'bio',
  type: 'textarea',
  value: '',
  label: 'Biography',
  placeholder: 'Tell us about yourself',
  required: true,
  maxLength: 500,
  props: {
    rows: 4,
    autoGrow: true,
  },
}

Props (Ionic-Specific):

Selection Fields

Selection fields enable users to choose from predefined options with mobile-optimized interfaces.

Select

Dropdown selection field with native action sheets on mobile devices.

Live Demo:

{
  key: 'framework',
  type: 'select',
  label: 'Framework',
  options: [
    { value: 'angular', label: 'Angular' },
    { value: 'react', label: 'React' },
    { value: 'vue', label: 'Vue.js' },
  ],
  props: {
    placeholder: 'Choose a framework',
  },
}

Basic Usage:

{
  key: 'country',
  type: 'select',
  value: '',
  label: 'Country',
  required: true,
  options: [
    { value: 'us', label: 'United States' },
    { value: 'uk', label: 'United Kingdom' },
    { value: 'ca', label: 'Canada' },
  ],
  props: {
    interface: 'action-sheet',
  },
}

Props (Ionic-Specific):

Radio

Radio button group for selecting a single option with mobile-friendly spacing.

Live Demo:

{
  key: 'subscriptionPlan',
  type: 'radio',
  label: 'Subscription Plan',
  options: [
    { value: 'free', label: 'Free' },
    { value: 'pro', label: 'Pro' },
    { value: 'enterprise', label: 'Enterprise' },
  ],
}

Basic Usage:

{
  key: 'size',
  type: 'radio',
  value: '',
  label: 'Select Size',
  required: true,
  options: [
    { value: 'small', label: 'Small' },
    { value: 'medium', label: 'Medium' },
    { value: 'large', label: 'Large' },
  ],
}

Props (Ionic-Specific):

Checkbox

Boolean checkbox control optimized for touch interaction.

Live Demo:

{
  key: 'newsletter',
  type: 'checkbox',
  label: 'Subscribe to newsletter',
  value: false,
  props: {
    labelPlacement: 'end',
  },
}

Basic Usage:

{
  key: 'terms',
  type: 'checkbox',
  value: false,
  label: 'I accept the terms and conditions',
  required: true,
}

Props (Ionic-Specific):

Multi-Checkbox

Multiple checkbox selection field for choosing multiple options.

Live Demo:

{
  key: 'interests',
  type: 'multi-checkbox',
  label: 'Interests',
  options: [
    { value: 'sports', label: 'Sports' },
    { value: 'music', label: 'Music' },
    { value: 'technology', label: 'Technology' },
    { value: 'art', label: 'Art' },
  ],
}

Basic Usage:

{
  key: 'interests',
  type: 'multi-checkbox',
  value: [],
  label: 'Select Your Interests',
  required: true,
  options: [
    { value: 'sports', label: 'Sports' },
    { value: 'music', label: 'Music' },
    { value: 'reading', label: 'Reading' },
    { value: 'travel', label: 'Travel' },
  ],
}

Props (Ionic-Specific):

Interactive Fields

Interactive fields provide advanced user input controls optimized for mobile interaction.

Toggle

Slide toggle switch for boolean on/off selections with smooth animations.

Live Demo:

{
  key: 'darkMode',
  type: 'toggle',
  label: 'Dark Mode',
  value: false,
  props: {
    labelPlacement: 'start',
  },
}

Basic Usage:

{
  key: 'notifications',
  type: 'toggle',
  value: false,
  label: 'Enable notifications',
}

Props (Ionic-Specific):

Slider

Range slider control with pin display and snap-to-tick support.

Live Demo:

{
  key: 'volume',
  type: 'slider',
  label: 'Volume',
  minValue: 0,
  maxValue: 100,
  step: 5,
  props: {
    pin: true,
  },
}

Basic Usage:

{
  key: 'volume',
  type: 'slider',
  value: 50,
  label: 'Volume',
  minValue: 0,
  maxValue: 100,
  step: 1,
  props: {
    pin: true,
    ticks: true,
  },
}

Field Properties:

Props (Ionic-Specific):

Datepicker

Date and time selection with native mobile pickers for iOS and Android.

Live Demo:

{
  key: 'birthDate',
  type: 'datepicker',
  label: 'Birth Date',
  props: {
    placeholder: 'Select your birth date',
    presentation: 'date',
  },
}

Basic Usage:

{
  key: 'birthdate',
  type: 'datepicker',
  value: null,
  label: 'Date of Birth',
  required: true,
  props: {
    presentation: 'date',
  },
}

Field Properties:

Props (Ionic-Specific):

Buttons & Actions

Action buttons provide form submission and navigation controls with Ionic styling.

Submit Button

Form submission button that's automatically disabled when the form is invalid.

Live Demo:

{
  type: 'submit',
  key: 'submit',
  label: 'Submit',
  props: {
    color: 'primary',
    fill: 'solid',
  },
}

Basic Usage:

{
  type: 'submit',
  key: 'submit',
  label: 'Create Account',
  props: {
    color: 'primary',
    expand: 'block',
  },
}

The submit button automatically:

• Disables when the form is invalid
• Emits a SubmitEvent when clicked
• Validates all fields before submission

Props:

Navigation Buttons

Navigation buttons for multi-step (paged) forms with platform-adaptive styling.

Basic Usage:

{
  fields: [
    {
      key: 'step1',
      type: 'page',
      fields: [
        { key: 'step1Title', type: 'text', label: 'Step 1', props: { elementType: 'h3' } },
        { key: 'name', type: 'input', value: '', label: 'Name', required: true },
        {
          type: 'next',
          key: 'next',
          label: 'Continue',
          props: { color: 'primary', expand: 'block' },
        },
      ],
    },
    {
      key: 'step2',
      type: 'page',
      fields: [
        { key: 'step2Title', type: 'text', label: 'Step 2', props: { elementType: 'h3' } },
        { key: 'email', type: 'input', value: '', label: 'Email', required: true },
        { type: 'previous', key: 'back', label: 'Back' },
        { type: 'submit', key: 'submit', label: 'Submit', props: { color: 'primary' } },
      ],
    },
  ],
}

Button Types:

• Next Button: Navigates to the next page. Automatically disabled when current page has validation errors.
• Previous Button: Navigates to the previous page. Always enabled to allow users to go back.

Theming

Ionic components use CSS variables for theming. Customize colors and styles globally or per-component.

Color Palette

Ionic provides a comprehensive color system:

// Field with custom color
{
  key: 'email',
  type: 'input',
  label: 'Email',
  props: {
    color: 'success', // Uses your theme's success color
  },
}

Available Colors:

• 'primary' - Primary brand color
• 'secondary' - Secondary brand color
• 'tertiary' - Tertiary brand color
• 'success' - Success/positive actions
• 'warning' - Warning states
• 'danger' - Error/destructive actions
• 'light' - Light variant
• 'medium' - Medium gray
• 'dark' - Dark variant

Custom Theme Variables

Override Ionic's default colors in your global styles:

:root {
  --ion-color-primary: #3880ff;
  --ion-color-primary-rgb: 56, 128, 255;
  --ion-color-primary-contrast: #ffffff;
  --ion-color-primary-contrast-rgb: 255, 255, 255;
  --ion-color-primary-shade: #3171e0;
  --ion-color-primary-tint: #4c8dff;

  // Customize other colors...
}

See Ionic Theming Guide for complete customization options.

Common Props

All Ionic fields support these common properties:

Mobile Optimization

All Ionic components are designed for mobile devices:

Touch Targets

• Minimum size: 44x44px touch areas for accessibility
• Spacing: Adequate padding for comfortable tapping
• Visual feedback: Ripple effects and state changes

Native Keyboards

Input fields automatically show the appropriate keyboard:

{
  key: 'email',
  type: 'input',
  props: {
    type: 'email',      // Shows email keyboard
    inputmode: 'email', // Forces email input mode
  },
}

Inputmode Options:

• 'text' - Standard keyboard
• 'decimal' - Numeric with decimal
• 'numeric' - Numeric only
• 'tel' - Telephone keypad
• 'search' - Search keyboard
• 'email' - Email keyboard
• 'url' - URL keyboard

Platform Styling

Ionic automatically adapts to the platform:

• iOS: Native iOS styling with SF Pro font and iOS design patterns
• Android: Material Design with Roboto font and MD patterns
• Automatic detection: Based on device platform
• Manual override: Use mode prop to force specific styling

{
  key: 'name',
  type: 'input',
  label: 'Name',
  props: {
    mode: 'ios', // Force iOS styling on all platforms
  },
}

Performance

• Hardware acceleration: GPU-accelerated animations
• Virtual scrolling: Efficient rendering for long lists
• Lazy loading: Components load on demand
• Gesture support: Native swipe and touch gestures

Accessibility

All Ionic components include comprehensive accessibility features:

ARIA Support

• Proper ARIA roles and attributes
• ARIA labels for screen readers
• ARIA-describedby for error messages
• ARIA-invalid for validation states

Keyboard Navigation

• Full keyboard support for all interactive elements
• Tab navigation with proper focus order
• Enter/Space for button activation
• Arrow keys for option selection

Screen Readers

• Descriptive labels for all form controls
• Error message announcements
• State change notifications
• Context-aware instructions

Focus Management

• Visible focus indicators
• Logical focus order
• Focus trap for modals
• Auto-focus on error fields

High Contrast

• Compatible with high contrast modes
• Sufficient color contrast ratios (WCAG AA)
• Clear visual distinctions
• Icon and text alternatives

Next Steps

• Check out Examples & Patterns for real-world use cases
• Learn about Validation for form validation
• See Type Safety for TypeScript integration
• Explore Conditional Logic for dynamic field behavior