Styling

1. Use useFormBridge(schema, { globalDefaults }) when a whole screen or product area needs the same theme. This is the default recommendation for CSS Modules, StyleSheet, utility-class maps, or design-system-wide field chrome.
2. Use local props on <fields.name classNames={...} /> when one field needs a special variant without mutating the shared schema.
3. Use form.fieldController(name) when a built-in field needs a fully custom trigger, shell, or modal while keeping the same schema contract. Use field.custom(defaultValue).render(...) only when the value model itself is custom.

The public type surface guards these layers too: a text field does not expose textarea-only or select-only props, and native fields do not expose web-only props such as className.

Merge order is predictable: builder behavior → globalDefaults → local field props → field controller or custom render layer.

Complete globalDefaults surface:

This is the most common production setup.

• One globalDefaults object themes the form wrapper, every generated field, and the submit button
• The schema stays reusable across pages because the visual system lives at the screen level
• You still keep an escape hatch for one field with local prop overrides

react-formbridge now exports official host components for styling libraries that want a stable component reference.

• FieldHost renders any generated field component passed through its field prop
• SubmitHost renders Form.Submit through a stable submit prop
• FormHost renders the generated Form component through a stable form prop

These helpers are especially useful with styled-components, styled-components/native, or any wrapper-based styling system that works better with stable host components than with runtime-generated field references.

Choose this pattern when the app already uses styled-components or styled-components/native.

• Use the exported host helpers instead of rebuilding your own wrappers
• Keep the styled shell stable and pass the generated field, submit button, or form through props
• On web, normal CSS selectors can target label, input, textarea, and the other built-in elements
• On native, use .attrs({ styles: { ... } }) to feed slot styles into the generated field

This stable-host pattern is the safest documented recipe because generated field components are runtime artifacts. It keeps styling ergonomic without forcing users to hand-build every field.

This recipe is a strong fit for Tailwind, UnoCSS, Windi, or any class-based utility stack.

• The global classNames map gives most of the form its look
• Local classNames and inputProps cover one-off field variations
• The runtime stays the same because the generated field still owns value, validation, and events

Use this when you want to prove the styling API quickly, or when one form needs a polished custom look without introducing a new styling dependency.

• styles targets the built-in slots directly on both web and native
• renderHint, renderError, and renderRequiredMark cover the cases where plain styles are not enough
• This is also a good recipe for incrementally migrating an existing screen to react-formbridge

On web, the API is broad enough to work with CSS Modules, utility classes, styled-components, Emotion, or plain objects.

• classNames.wrapper and styles.wrapper theme the field container directly
• globalDefaults.form and globalDefaults.submit style the generated form wrapper and submit button
• highlightOnError lets you opt out of the built-in red field chrome while keeping the error message
• wrapperProps, labelProps, hintProps, and errorProps let you push DOM attributes without losing the generated renderer
• inputProps is available on text-like web fields, textareaProps on textarea fields, and selectProps on select fields
• renderLabel, renderHint, renderError, and renderRequiredMark cover the cases where styling alone is not enough

Web field slot names currently exposed through classNames / styles.
Slot names are prefixed with the field type so it is clear where each override will land.

On React Native, the same layering applies, but the override points stay React Native-friendly instead of DOM-specific.

• styles.wrapper themes the field wrapper, while globalDefaults.form and globalDefaults.submit theme the form container and submit button
• highlightOnError lets you opt out of the built-in red field chrome while keeping the error message
• Renderer-specific extra keys are also supported in styles, which is especially useful for inputs such as checkboxes, async selectors, or modal option lists
• wrapperProps, labelProps, inputProps, hintProps, and errorProps help with test IDs, accessibility, or integration with surrounding layout primitives
• Native fields do not expose web-only props such as className, textareaProps, or selectProps
• renderLabel, renderHint, renderError, and renderRequiredMark cover the cases where a simple style object is not enough

Native field slot names currently exposed through styles.
Slot names are prefixed with the field type so it is clear where each override will land.

• Use globalDefaults when a whole route, modal, onboarding flow, or checkout screen should share one visual system
• Keep platform-specific differences inside the globalDefaults object at the screen level
• Use local field props when one field needs a variant, a special helper text, or a different accent color on one screen
• Use the stable host recipe for styled-components and styled-components/native
• Use className on form / submit plus classNames slot maps on fields for Tailwind-style utility frameworks on web
• Use style, styles, wrappers, or the stable host recipe for React Native styling systems such as StyleSheet, NativeWind-friendly wrappers, or in-house component kits
• Let the field type guide the override point: inputProps for text-like fields, textareaProps for textareas, selectProps for selects
• The API stays agnostic on purpose, so the same schema can power web and native without forcing the same styling stack on both platforms

Complete host helper exports:

Each host keeps the full props surface of the runtime component it wraps, including platform-native attributes.