🧩 Proposal: emptyStringOr(...) helper for Valibot

[mxa0079]

What

Add a new helper function:

import * as v from "valibot";

// eslint-disable-next-line @typescript-eslint/no-explicit-any
export function emptyStringOr<TSchema extends v.BaseSchema<any, any, any>>(schema: TSchema) {
  return v.union([
    v.literal(""),
    schema
  ]);
}

It would allow a schema to accept either the literal "" (an empty string) or a value matching the supplied schema.

Why

Why
In modern React / Next.js form workflows, the distinction between controlled and uncontrolled components is critical. The built-in methods like optional() or nullable() in Valibot may lead devs to initialize form fields as undefined or null, which triggers the classic React warning:

“A component is changing an uncontrolled input to be controlled. This is likely caused by the value changing from undefined to a defined value…” 

Here’s how the wrong pattern happens:

• A developer uses optional() on a string field, so the type allows string | undefined.
• The React input’s value ends up being undefined initially, making the input uncontrolled.
• Later the user types something, the value becomes a defined string → the input transitions to controlled → React throws a warning.
• This can lead to subtle bugs, UI glitches or inconsistent form state.

By contrast, emptyStringOr(schema) gives you: a safe default of "" for no value (so the input remains a string, staying controlled), or a valid string per your schema. That avoids the uncontrolled→controlled switch entirely and aligns with best practices for controlled components: always supply a string (not undefined) to the value prop. 

Backward compatibility & Notes

• Purely additive: no breaking changes.
• Devs can continue using optional()/nullable() for scenarios where undefined or null are truly meaningful values—but in React inputs this often isn’t the case.
• Clarify in the docs: emptyStringOr() does not transform "" into undefined—it simply allows "" as a valid value. If transformation is needed, the user should apply v.transform() on top.
• Emphasize that this pattern is especially important in React forms where you want to avoid unintended uncontrolled→controlled transitions.

Example usage (React-form context)

export const PersonProfile = object({
 
  firstName: pipe(string('El Nombre es requerido'), trim()),
  phone: emptyStringOr(PhoneNumber),
  phoneCountryCode: string(),
});

// In your React form:
// initial value: "" rather than undefined
// validation: either empty string (meaning “not filled”) or a non-empty string

Documentation snippet

emptyStringOr(schema): Schema
Accepts either the literal empty string "", or a value matching the given schema.
Why use it? In controlled React inputs you want the value prop to always be a string (to avoid uncontrolled ↔ controlled warnings). This helper makes that case explicit, rather than relying on undefined or null which may lead to UI or state inconsistencies.
Equivalent to: v.union([ v.literal(""), schema ]).

Call to Action
I propose we introduce emptyStringOr(...) in the next minor version of Valibot. I’m happy to open a PR containing full implementation + tests + doc updates.

[fabian-hiller]

Sorry for my very late answer! @dosu what do you think about it? Consider Valibot's history, current API and general design philosophy.

[dosubot[bot]]

The emptyStringOr helper is a well-justified proposal and fits Valibot’s philosophy. The pattern of accepting empty strings alongside another schema is already recommended for React forms to avoid uncontrolled/controlled warnings, and is documented as the canonical solution using v.union([v.literal(''), schema]) in the official API. However, there’s no dedicated helper for this use case yet.

Community discussions show that while the union pattern works, it’s not always readable or clear, especially for new users or in large codebases. A focused helper like emptyStringOr would improve clarity and developer experience, especially for React form scenarios see discussion. Maintainers have previously suggested custom helpers for this pattern and are open to additive, modular utilities that don’t bloat the API or bundle size.

Technically, the union schema is robust and designed for these scenarios, so the helper would be a thin, readable abstraction over existing functionality see implementation.

If added, it should be clearly documented as a convenience for React-controlled inputs, with guidance that it does not transform "" to undefined, and that further transformation can be layered if needed. Naming is clear and intentful as proposed.

In summary: emptyStringOr is consistent with Valibot’s modular, composable, and DX-focused design. It’s a purely additive, non-breaking helper that would clarify a common pattern and improve usability for React form integration. I recommend accepting the proposal.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[fabian-hiller]

Thank you for your feedback! I'm not sure if we should add such a helper. If we do, we need a better name that matches the naming style of similar schemas such as optional and nullable.

Here is a slightly updated version of your function:

import * as v from 'valibot';

export function emptyStringOr<TSchema extends v.GenericSchema>(
  schema: TSchema,
) {
  return v.union([v.literal(''), schema]);
}