@salve-software/react-native-nitro-input-mask 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 salvesoftware
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NitroInputMask.podspec

@@ -0,0 +1,31 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "NitroInputMask"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => min_ios_version_supported, :visionos => 1.0 }
+  s.source       = { :git => "https://github.com/Salve-Software/react-native-nitro-input-mask.git", :tag => "#{s.version}" }
+
+  s.source_files = [
+    # Implementation (Swift)
+    "ios/**/*.{swift}",
+    # Autolinking/Registration (Objective-C++)
+    "ios/**/*.{m,mm}",
+    # Implementation (C++ objects)
+    "cpp/**/*.{hpp,cpp}",
+  ]
+
+  load 'nitrogen/generated/ios/NitroInputMask+autolinking.rb'
+  add_nitrogen_files(s)
+
+  s.dependency 'React-jsi'
+  s.dependency 'React-callinvoker'
+  install_modules_dependencies(s)
+end

package/README.md

@@ -0,0 +1,181 @@
+# react-native-nitro-input-mask
+
+Native input masks for React Native — zero JS flicker, built on [Nitro Modules](https://github.com/mrousavy/nitro).
+
+[![npm version](https://img.shields.io/npm/v/react-native-nitro-input-mask.svg)](https://www.npmjs.com/package/react-native-nitro-input-mask)
+[![npm downloads](https://img.shields.io/npm/dm/react-native-nitro-input-mask.svg)](https://www.npmjs.com/package/react-native-nitro-input-mask)
+[![License](https://img.shields.io/npm/l/react-native-nitro-input-mask.svg)](./LICENSE)
+
+<p align="center">
+  <img src="./assets/demo.gif" width="320" />
+</p>
+
+---
+
+## Why
+
+Most React Native mask libraries apply the mask in JavaScript — every keystroke crosses the bridge before the field is updated, causing a visible flicker.
+
+`react-native-nitro-input-mask` runs the entire mask engine natively (Swift on iOS, Kotlin on Android) via Nitro Modules, so the field is updated synchronously with no flicker.
+
+## Features
+
+- **Zero flicker** — mask applied synchronously on the native side
+- **`<NitroInputMask />`** — drop-in replacement for React Native's `<TextInput />`
+- **`NitroInputMaskService`** — apply a mask to any string without a component
+- **Built-in mask types** — `custom`, `money`, `datetime`, `credit-card`
+- **Range tokens** — e.g. `[1-12]` for month, `[1-31]` for day
+- iOS and Android support
+
+## Requirements
+
+| | Minimum |
+|---|---|
+| React Native | 0.78 |
+| Node | 18 |
+
+> **New Architecture only.** The Old Architecture is not supported.
+
+## Installation
+
+```sh
+npm install react-native-nitro-input-mask react-native-nitro-modules
+```
+
+```sh
+yarn add react-native-nitro-input-mask react-native-nitro-modules
+```
+
+```sh
+bun add react-native-nitro-input-mask react-native-nitro-modules
+```
+
+### iOS
+
+```sh
+cd ios && pod install
+```
+
+## Usage
+
+### `<NitroInputMask />`
+
+Drop-in replacement for `<TextInput />`. Accepts all standard `TextInputProps` plus `maskType` and `maskOptions`.
+
+```tsx
+import React, { useState } from 'react'
+import { NitroInputMask } from 'react-native-nitro-input-mask'
+
+function PhoneInput() {
+  const [value, setValue] = useState('')
+
+  return (
+    <NitroInputMask
+      maskOptions={{ mask: '(999) 999-9999' }}
+      placeholder="(555) 000-0000"
+      keyboardType="numeric"
+      onChangeText={setValue}
+    />
+  )
+}
+```
+
+```tsx
+// Money
+<NitroInputMask
+  maskType="money"
+  maskOptions={{ unit: '$ ', precision: 2 }}
+  keyboardType="numeric"
+  onChangeText={setValue}
+/>
+
+// Date
+<NitroInputMask
+  maskType="datetime"
+  maskOptions={{ format: 'MM/DD/YYYY' }}
+  keyboardType="numeric"
+  onChangeText={setValue}
+/>
+
+// Credit card
+<NitroInputMask
+  maskType="credit-card"
+  maskOptions={{ issuer: 'visa-or-mastercard' }}
+  keyboardType="numeric"
+  onChangeText={setValue}
+/>
+```
+
+### `NitroInputMaskService`
+
+Apply a mask to any string — useful for formatting values in lists, previews, etc.
+
+```tsx
+import { NitroInputMaskService } from 'react-native-nitro-input-mask'
+
+NitroInputMaskService.applyMask({
+  value: '5551234567',
+  maskOptions: { mask: '(999) 999-9999' },
+})
+// '(555) 123-4567'
+
+NitroInputMaskService.applyMask({
+  value: '123456',
+  maskType: 'money',
+  maskOptions: { unit: '$ ', precision: 2 },
+})
+// '$ 1,234.56'
+
+NitroInputMaskService.applyMask({
+  value: '06252025',
+  maskType: 'datetime',
+  maskOptions: { format: 'MM/DD/YYYY' },
+})
+// '06/25/2025'
+```
+
+## Mask Syntax
+
+| Token | Accepts |
+|---|---|
+| `9` | Digit (0–9) |
+| `A` | Letter (a–z, A–Z) |
+| `*` | Letter or digit |
+| `[n-m]` | Integer in range n–m (e.g. `[1-12]`, `[1-31]`) |
+| Any other character | Literal — inserted as-is |
+
+## API
+
+### `<NitroInputMask />`
+
+Extends React Native's [`TextInputProps`](https://reactnative.dev/docs/textinput#props).
+
+| maskType | maskOptions | Docs |
+|---|---|---|
+| `'custom'` (default) | `{ mask: string }` | [docs/custom.md](./docs/custom.md) |
+| `'money'` | `{ precision?, separator?, delimiter?, unit?, suffixUnit?, zeroCents? }` | [docs/money.md](./docs/money.md) |
+| `'datetime'` | `{ format: string }` | [docs/datetime.md](./docs/datetime.md) |
+| `'credit-card'` | `{ issuer?, obfuscated? }` | [docs/credit-card.md](./docs/credit-card.md) |
+
+### `NitroInputMaskService.applyMask(props)`
+
+| Prop | Type | Description |
+|---|---|---|
+| `value` | `string` | The raw string to mask |
+| `maskType` | `'custom' \| 'money' \| 'datetime' \| 'credit-card'` | Mask type (default `'custom'`) |
+| `maskOptions` | See table above | Options for the chosen mask type |
+
+Returns the masked `string`.
+
+## Contributing
+
+Pull requests are welcome. For major changes, please open an issue first to discuss what you'd like to change.
+
+1. Fork the repo
+2. Create your branch: `git checkout -b feat/your-feature`
+3. Commit your changes following [Conventional Commits](https://www.conventionalcommits.org/)
+4. Open a pull request
+
+## License
+
+MIT © [Salve Software](https://github.com/Salve-Software)

package/android/CMakeLists.txt

@@ -0,0 +1,32 @@
+project(NitroInputMask)
+cmake_minimum_required(VERSION 3.9.0)
+
+set (PACKAGE_NAME NitroInputMask)
+set (CMAKE_VERBOSE_MAKEFILE ON)
+set (CMAKE_CXX_STANDARD 20)
+
+# Enable Raw Props parsing in react-native (for Nitro Views)
+add_compile_options(-DRN_SERIALIZABLE_STATE=1)
+
+# Define C++ library and add all sources
+add_library(${PACKAGE_NAME} SHARED
+        src/main/cpp/cpp-adapter.cpp
+)
+
+# Add Nitrogen specs :)
+include(${CMAKE_SOURCE_DIR}/../nitrogen/generated/android/NitroInputMask+autolinking.cmake)
+
+# Set up local includes
+include_directories(
+        "src/main/cpp"
+        "../cpp"
+)
+
+find_library(LOG_LIB log)
+
+# Link all libraries together
+target_link_libraries(
+        ${PACKAGE_NAME}
+        ${LOG_LIB}
+        android                                   # <-- Android core
+)

package/android/build.gradle

@@ -0,0 +1,148 @@
+buildscript {
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.8.0"
+  }
+}
+
+def reactNativeArchitectures() {
+  def value = rootProject.getProperties().get("reactNativeArchitectures")
+  return value ? value.split(",") : ["armeabi-v7a", "x86", "x86_64", "arm64-v8a"]
+}
+
+def isNewArchitectureEnabled() {
+  return rootProject.hasProperty("newArchEnabled") && rootProject.getProperty("newArchEnabled") == "true"
+}
+
+apply plugin: "com.android.library"
+apply plugin: 'org.jetbrains.kotlin.android'
+apply from: '../nitrogen/generated/android/NitroInputMask+autolinking.gradle'
+apply from: "./fix-prefab.gradle"
+
+if (isNewArchitectureEnabled()) {
+  apply plugin: "com.facebook.react"
+}
+
+def getExtOrDefault(name) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : project.properties["NitroInputMask_" + name]
+}
+
+def getExtOrIntegerDefault(name) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : (project.properties["NitroInputMask_" + name]).toInteger()
+}
+
+android {
+  namespace "com.nitroinputmask"
+
+  ndkVersion getExtOrDefault("ndkVersion")
+  compileSdkVersion getExtOrIntegerDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrIntegerDefault("minSdkVersion")
+    targetSdkVersion getExtOrIntegerDefault("targetSdkVersion")
+    buildConfigField "boolean", "IS_NEW_ARCHITECTURE_ENABLED", isNewArchitectureEnabled().toString()
+
+    externalNativeBuild {
+      cmake {
+        cppFlags "-frtti -fexceptions -Wall -Wextra -fstack-protector-all"
+        arguments "-DANDROID_STL=c++_shared", "-DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON"
+        abiFilters (*reactNativeArchitectures())
+
+        buildTypes {
+          debug {
+            cppFlags "-O1 -g"
+          }
+          release {
+            cppFlags "-O2"
+          }
+        }
+      }
+    }
+  }
+
+  externalNativeBuild {
+    cmake {
+      path "CMakeLists.txt"
+    }
+  }
+
+  packagingOptions {
+    excludes = [
+        "META-INF",
+        "META-INF/**",
+        "**/libc++_shared.so",
+        "**/libfbjni.so",
+        "**/libjsi.so",
+        "**/libfolly_json.so",
+        "**/libfolly_runtime.so",
+        "**/libglog.so",
+        "**/libhermes.so",
+        "**/libhermes-executor-debug.so",
+        "**/libhermes_executor.so",
+        "**/libreactnative.so",
+        "**/libreactnativejni.so",
+        "**/libturbomodulejsijni.so",
+        "**/libreact_nativemodule_core.so",
+        "**/libjscexecutor.so"
+    ]
+  }
+
+  buildFeatures {
+    buildConfig true
+    prefab true
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled false
+    }
+  }
+
+  lintOptions {
+    disable "GradleCompatible"
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_1_8
+    targetCompatibility JavaVersion.VERSION_1_8
+  }
+
+  sourceSets {
+    main {
+      if (isNewArchitectureEnabled()) {
+        java.srcDirs += [
+          // React Codegen files
+          "${project.buildDir}/generated/source/codegen/java"
+        ]
+      }
+    }
+  }
+}
+
+repositories {
+  mavenCentral()
+  google()
+}
+
+
+dependencies {
+  // For < 0.71, this will be from the local maven repo
+  // For > 0.71, this will be replaced by `com.facebook.react:react-android:$version` by react gradle plugin
+  //noinspection GradleDynamicVersion
+  implementation "com.facebook.react:react-native:+"
+
+  // Add a dependency on NitroModules
+  implementation project(":react-native-nitro-modules")
+}
+
+if (isNewArchitectureEnabled()) {
+  react {
+    jsRootDir = file("../src/")
+    libraryName = "NitroInputMask"
+    codegenJavaPackageName = "com.nitroinputmask"
+  }
+}

package/android/fix-prefab.gradle

@@ -0,0 +1,51 @@
+tasks.configureEach { task ->
+  // Make sure that we generate our prefab publication file only after having built the native library
+  // so that not a header publication file, but a full configuration publication will be generated, which
+  // will include the .so file
+
+  def prefabConfigurePattern = ~/^prefab(.+)ConfigurePackage$/
+  def matcher = task.name =~ prefabConfigurePattern
+  if (matcher.matches()) {
+    def variantName = matcher[0][1]
+    task.outputs.upToDateWhen { false }
+    task.dependsOn("externalNativeBuild${variantName}")
+  }
+}
+
+afterEvaluate {
+  def abis = reactNativeArchitectures()
+  rootProject.allprojects.each { proj ->
+    if (proj === rootProject) return
+
+    def dependsOnThisLib = proj.configurations.findAll { it.canBeResolved }.any { config ->
+      config.dependencies.any { dep ->
+        dep.group == project.group && dep.name == project.name
+      }
+    }
+    if (!dependsOnThisLib && proj != project) return
+
+    if (!proj.plugins.hasPlugin('com.android.application') && !proj.plugins.hasPlugin('com.android.library')) {
+      return
+    }
+
+    def variants = proj.android.hasProperty('applicationVariants') ? proj.android.applicationVariants : proj.android.libraryVariants
+    // Touch the prefab_config.json files to ensure that in ExternalNativeJsonGenerator.kt we will re-trigger the prefab CLI to
+    // generate a libnameConfig.cmake file that will contain our native library (.so).
+    // See this condition: https://cs.android.com/android-studio/platform/tools/base/+/mirror-goog-studio-main:build-system/gradle-core/src/main/java/com/android/build/gradle/tasks/ExternalNativeJsonGenerator.kt;l=207-219?q=createPrefabBuildSystemGlue
+    variants.all { variant ->
+      def variantName = variant.name
+      abis.each { abi ->
+        def searchDir = new File(proj.projectDir, ".cxx/${variantName}")
+        if (!searchDir.exists()) return
+        def matches = []
+        searchDir.eachDir { randomDir ->
+          def prefabFile = new File(randomDir, "${abi}/prefab_config.json")
+          if (prefabFile.exists()) matches << prefabFile
+        }
+        matches.each { prefabConfig ->
+          prefabConfig.setLastModified(System.currentTimeMillis())
+        }
+      }
+    }
+  }
+}

package/android/gradle.properties

@@ -0,0 +1,5 @@
+NitroInputMask_kotlinVersion=2.1.20
+NitroInputMask_minSdkVersion=23
+NitroInputMask_targetSdkVersion=35
+NitroInputMask_compileSdkVersion=34
+NitroInputMask_ndkVersion=27.1.12297006

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+</manifest>

package/android/src/main/cpp/cpp-adapter.cpp

@@ -0,0 +1,9 @@
+#include <jni.h>
+#include <fbjni/fbjni.h>
+#include "NitroInputMaskOnLoad.hpp"
+
+JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM* vm, void*) {
+  return facebook::jni::initialize(vm, []() {
+    margelo::nitro::nitroinputmask::registerAllNatives();
+  });
+}

package/android/src/main/java/com/nitroinputmask/NitroInputMaskContext.kt

@@ -0,0 +1,7 @@
+package com.nitroinputmask
+
+import com.facebook.react.bridge.ReactApplicationContext
+
+object NitroInputMaskContext {
+  var reactContext: ReactApplicationContext? = null
+}

package/android/src/main/java/com/nitroinputmask/NitroInputMaskModule.kt

@@ -0,0 +1,108 @@
+package com.nitroinputmask
+
+import android.os.Handler
+import android.os.Looper
+import android.view.View
+import android.view.ViewGroup
+import android.widget.EditText
+import android.widget.TextView
+import androidx.annotation.Keep
+import com.facebook.proguard.annotations.DoNotStrip
+import com.margelo.nitro.nitroinputmask.HybridNitroInputMaskSpec
+import com.margelo.nitro.nitroinputmask.NitroMaskOptions
+import com.nitroinputmask.engine.MaskEngineFactory
+import com.nitroinputmask.engine.MaskEngineProtocol
+import java.lang.ref.WeakReference
+
+private const val ATTACH_RETRIES = 5
+private const val ATTACH_RETRY_DELAY_MS = 50L
+
+@Keep
+@DoNotStrip
+class HybridNitroInputMaskModule : HybridNitroInputMaskSpec() {
+  private data class MaskState(
+    val editTextRef: WeakReference<EditText>,
+    val watcher: NitroInputMaskTextWatcher
+  )
+
+  private val states = mutableMapOf<String, MaskState>()
+
+  override fun attach(nativeID: String, maskType: String, options: NitroMaskOptions) {
+    val engine = MaskEngineFactory.build(maskType, options)
+    attemptAttach(nativeID, engine, ATTACH_RETRIES)
+  }
+
+  private fun attemptAttach(nativeID: String, engine: MaskEngineProtocol, retries: Int) {
+    val context = NitroInputMaskContext.reactContext ?: return
+    context.currentActivity?.runOnUiThread {
+      val root = context.currentActivity?.window?.decorView ?: return@runOnUiThread
+      val editText = findEditText(root, nativeID)
+      if (editText != null) {
+        val watcher = NitroInputMaskTextWatcher(engine, editText)
+        states[nativeID] = MaskState(WeakReference(editText), watcher)
+        insertWatcherFirst(editText, watcher)
+      } else if (retries > 0) {
+        Handler(Looper.getMainLooper()).postDelayed(
+          { attemptAttach(nativeID, engine, retries - 1) },
+          ATTACH_RETRY_DELAY_MS
+        )
+      }
+    }
+  }
+
+  override fun detach(nativeID: String) {
+    val state = states.remove(nativeID) ?: return
+    NitroInputMaskContext.reactContext?.currentActivity?.runOnUiThread {
+      state.editTextRef.get()?.removeTextChangedListener(state.watcher)
+    }
+  }
+
+  override fun updateMask(nativeID: String, maskType: String, options: NitroMaskOptions) {
+    val engine = MaskEngineFactory.build(maskType, options)
+    states[nativeID]?.watcher?.engine = engine
+  }
+
+  override fun setValue(nativeID: String, rawValue: String) {
+    val state = states[nativeID] ?: return
+    val editText = state.editTextRef.get() ?: return
+    val (masked, _) = state.watcher.engine.apply(rawValue)
+    NitroInputMaskContext.reactContext?.currentActivity?.runOnUiThread {
+      if (editText.text.toString() == masked) return@runOnUiThread
+      state.watcher.isProgrammatic = true
+      editText.setText(masked)
+      if (state.watcher.engine.wantsTrailingCursor) {
+        editText.setSelection(editText.text.length)
+      } else {
+        editText.setSelection(editText.text.length)
+      }
+      state.watcher.isProgrammatic = false
+    }
+  }
+
+  private fun findEditText(root: View, nativeID: String): EditText? {
+    val tag = root.getTag(com.facebook.react.R.id.view_tag_native_id)
+    if (root is EditText && tag == nativeID) return root
+    if (root is ViewGroup) {
+      for (i in 0 until root.childCount) {
+        findEditText(root.getChildAt(i), nativeID)?.let { return it }
+      }
+    }
+    return null
+  }
+
+  @Suppress("UNCHECKED_CAST")
+  private fun insertWatcherFirst(editText: EditText, watcher: NitroInputMaskTextWatcher) {
+    // Insert at index 0 so our watcher runs before React Native's own TextWatcher,
+    // ensuring the mask is applied before RN reads the new text.
+    try {
+      val field = TextView::class.java.getDeclaredField("mListeners")
+      field.isAccessible = true
+      val listeners = field.get(editText) as? ArrayList<android.text.TextWatcher>
+      if (listeners != null) {
+        listeners.add(0, watcher)
+        return
+      }
+    } catch (_: Exception) {}
+    editText.addTextChangedListener(watcher)
+  }
+}

package/android/src/main/java/com/nitroinputmask/NitroInputMaskPackage.kt

@@ -0,0 +1,29 @@
+package com.nitroinputmask
+
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.module.model.ReactModuleInfoProvider
+import com.facebook.react.BaseReactPackage
+import com.facebook.react.uimanager.ViewManager
+import com.margelo.nitro.nitroinputmask.NitroInputMaskOnLoad
+
+class NitroInputMaskPackage : BaseReactPackage() {
+  override fun getModule(name: String, reactContext: ReactApplicationContext): NativeModule? {
+    return null
+  }
+
+  override fun getReactModuleInfoProvider(): ReactModuleInfoProvider = ReactModuleInfoProvider {
+    emptyMap()
+  }
+
+  override fun createViewManagers(reactContext: ReactApplicationContext): List<ViewManager<*, *>> {
+    NitroInputMaskContext.reactContext = reactContext
+    return emptyList()
+  }
+
+  companion object {
+    init {
+      NitroInputMaskOnLoad.initializeNative()
+    }
+  }
+}

package/android/src/main/java/com/nitroinputmask/NitroInputMaskServiceModule.kt

@@ -0,0 +1,17 @@
+package com.nitroinputmask
+
+import androidx.annotation.Keep
+import com.facebook.proguard.annotations.DoNotStrip
+import com.margelo.nitro.nitroinputmask.HybridNitroInputMaskServiceSpec
+import com.margelo.nitro.nitroinputmask.NitroMaskOptions
+import com.nitroinputmask.engine.MaskEngineFactory
+
+@Keep
+@DoNotStrip
+class HybridNitroInputMaskServiceModule : HybridNitroInputMaskServiceSpec() {
+  override fun applyMask(value: String, maskType: String, options: NitroMaskOptions): String {
+    val engine = MaskEngineFactory.build(maskType, options)
+    val (masked, _) = engine.apply(value)
+    return masked
+  }
+}