feat: TextField component by wonderlul · Pull Request #4904 · callstack/react-native-paper

wonderlul · 2026-04-22T06:43:24Z

Motivation

File structure
The component is split by variant (filled/ and outlined/) and a root that wires shared behavior. Each area keeps logic, styles, utils, and constants in separate files. That follows patterns already used elsewhere in the library, but goes one step further so responsibilities stay obvious: variant-specific layout and theming do not drown in shared code, and the public API file stays focused on behavior and types.

LeftAccessory / RightAccessory vs TextInput adornments
TextInput composes leading and trailing content through left and right, which are built around icons and affixes (TextInput.Icon, TextInput.Affix) and internal adornment types. TextField instead exposes LeftAccessory and RightAccessory as render props (component types). The field passes curated layout and state—notably the merged style for alignment with the field, plus status, multiline, and editable—so accessories stay aligned with the input without re-implementing field internals. That supports arbitrary leading/trailing UI (clear actions, custom buttons, non-icon content) while still inheriting the important structural styles from the component.

filled / outlined instead of flat / outlined
Material Design 3 describes text fields in terms of filled and outlined styles. The existing TextInput API uses mode: 'flat' | 'outlined', where “flat” corresponds to the filled look. The new component names variants filled and outlined so the public API matches MD3 language and is easier to map from the spec and design tools.

Style overrides
TextField is built as a small stack of clear layers, and each layer can be adjusted without fighting the rest. The outer pressable wrapper, the field shell (border, background, row that includes accessories), and the inner content wrapper (label + TextInput) each accept dedicated style props (pressableStyle, fieldStyle, containerStyle). The underlying TextInput still uses the normal style prop (and the rest of TextInputProps) for typography, padding, and input-specific layout. Label and helper text can be customized through labelProps and helperProps (including style). Leading/trailing UI uses LeftAccessory / RightAccessory, which receive a prepared style from the field so custom content stays aligned while remaining fully under your control. Together, this gives predictable “override the part you mean” behavior instead of a single opaque style that’s hard to reason about.

TextField instead of TextInput
Material Design 3 uses the term text field for this control. Exporting a second “Paper” input named TextInput would also blur the built-in React Native TextInput in imports and documentation. A dedicated TextField name keeps the design-system component clearly namespaced and aligned with MD3, while the underlying control remains React Native’s TextInput where appropriate.

Positioning relative to TextInput
TextField is intended as the modern replacement path for form text entry in react-native-paper: implementation is structured for clarity and maintainability, and it adopts MD3-oriented theming (including use of the PlatformColor API where it fits platform tokens). Compared to the legacy TextInput stack, this design aims to be easier to follow, less ad hoc in how variants and layout are split, and more efficient in how styles and state are applied—giving teams a refreshed, spec-aligned building block for new work without forcing an immediate break for existing TextInput users.

Order of merging

#4901

Related issue

#4878
#4329
#4235

Test plan

Run the Example app.

filled

outlined

callstack-bot · 2026-04-22T06:47:51Z

Hey @wonderlul, thank you for your pull request 🤗. The documentation from this branch can be viewed here.

adrcotfas

Below are some components described in the specs I see were not covered. Do we want them?

in all error examples from the specs there's a trailing error icon
the option to have leading and trailing text (called prefix and suffix) for currency, units of measurement etc; for suffix, the text field is aligned to the end instead of start; - character counter (aligned to the end, same style as supporting text)
The native filled TextField has an animation for the outline when selecting it: center to edges reveal
see https://m3.material.io/components/text-fields/guidelines

Some other notes:

Please double check the tokens from the specs. I added some comments about opacity/color for certain elements that was missing; maybe there are other inconsistencies.
A more complex example would be nice to cover more use cases and these elements, if we add them.

Here's a recording from this app showing the features mentioned above: https://github.com/material-components/material-components-android. I recommend installing this app to double check how TextField looks and behaves like in native.

screen-20260423-165915-1776952725646.mp4

adrcotfas · 2026-04-23T12:38:18Z

+      borderColor: hasActiveOutline ? activeOutlineColor : inactiveOutlineColor,
+    },
+    disabled && $disabledStyle,
+    $fieldStyleOverride,


Is this intentional? It's already part of fieldStyles above.

Yes, this is intentional. outlineStyles are kind of additional outline to handle the focus state that has to be overridden as well.

adrcotfas · 2026-04-23T12:42:44Z

+  paddingHorizontal: TEXT_FIELD_INPUT_WRAPPER_PADDING_HORIZONTAL,
+  fontSize: HELPER_FONT_SIZE,
+  fontWeight: '400',
+  textAlign: 'left',


I think we should consider RTL instead of hardcoding left.

Considering RTL using left is actually handling both cases depending on the settings. Do you have something else in mind?

By considering RTL you mean outlined/logic.ts writingDirection? Doesn't the text still anchor to the left side regardless of writingDirection?
Shouldn't this be auto instead of left or just remove it?

With auto it aligns text to the left and doesn't respect the RTL settings. I guess with textAlign: left it considers left as the start no matter if it's left or right :-). Don't even ask me how long it took me to figure that out.

adrcotfas · 2026-04-23T12:48:57Z

@@ -0,0 +1,20 @@
+import {
+  ACCESORY_SIZE,


Typo for ACCESSORY_SIZE here and in styles.ts:, filled/constants.ts, outlined/constants.ts.

adrcotfas · 2026-04-23T12:52:44Z

@@ -0,0 +1,167 @@
+import { Animated, StyleProp, TextStyle, ViewStyle } from 'react-native';


The filled variant does not handle RTL as the outlined variant does. Also, some RTL tests would be useful.

adrcotfas · 2026-04-23T13:18:21Z

+
+  let inactiveOutlineColor = colors.outline;
+
+  if (disabled) {


According to specs:

Outlined text field disabled outline color -> md.sys.color.on-surface Outlined text field disabled outline opacity -> 0.12

adrcotfas · 2026-04-23T13:34:42Z

+    {
+      backgroundColor: disabled ? surfaceContainerHighest : surfaceVariant,
+    },
+    disabled && $disabledStyle,


The outlined variant applies disabled && $disabledStyle per element (input, label, accessories). The filled variant applies it only to the field parent.

$animatedLabelTextStyles has no disabled dimming.

According to specs:

Filled text field disabled container opacity -> 0.04

adrcotfas · 2026-04-23T13:36:36Z

+          autoCapitalize="none"
+          pressableStyle={styles.field}
+        />
+        <TextField


No outline is visible here.

adrcotfas · 2026-04-23T13:57:50Z

+
+import {
+  ACCESORY_SIZE,
+  HELPER_FONT_SIZE,


For consistency with the specs, I would rename all occurrences of helper to supportingText and accessory to icon.

adrcotfas · 2026-04-23T14:44:05Z

@@ -0,0 +1,167 @@
+import { Animated, StyleProp, TextStyle, ViewStyle } from 'react-native';
+


In the specs placeholders are hidden until the TextField is selected.

adrcotfas reviewed Apr 23, 2026

View reviewed changes

feat: text field component introduction

d0cffca

wonderlul force-pushed the feat/TextField branch from 3f47684 to d0cffca Compare April 24, 2026 06:55

		@@ -0,0 +1,167 @@
		import { Animated, StyleProp, TextStyle, ViewStyle } from 'react-native';

Uh oh!

Conversation

wonderlul commented Apr 22, 2026

Motivation

Order of merging

Related issue

Test plan

Uh oh!

callstack-bot commented Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

adrcotfas left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adrcotfas Apr 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

callstack-bot commented Apr 22, 2026 •

edited

Loading

adrcotfas left a comment •

edited

Loading

adrcotfas Apr 24, 2026 •

edited

Loading