Handle datetime-local for Future API

[lhapaipai]

Hi team!

I've followed the discussion related to the same topic with conform v1: #738

I'm wondering what could be the best practice for use with the future API.

Context

I would like to use a simple native input datetime-local with conform and actually, I need either to:

1. Prepare the data for the default value (like updatedAt in the example below)
2. Define a custom DateTimeField component with another hidden input (for the example I've made the input visible)

Reproduction

import { coerceFormValue, formatResult } from "@conform-to/zod/v4/future";
import {
  FieldName,
  FormProvider,
  isDirty,
  parseSubmission,
  report,
  useControl,
  useField,
  useForm,
  useFormData,
} from "@conform-to/react/future";
import { z } from "zod/v4";
import { data, Form } from "react-router";

const schema = coerceFormValue(
  z.object({
    createdAt: z.date(),
    updatedAt: z.date(),
  }),
);

export async function action({ request }) {
  const formData = await request.formData();
  const submission = parseSubmission(formData);
  const result = schema.safeParse(submission.payload);

  if (!result.success) {
    return report(submission, {
      error: formatResult(result),
    });
  }

  console.log("update server side", result.data);
  return data(null);
}

export async function loader() {
  const infos = {
    updatedAt: new Date("2026-01-01T12:00:00"),
    createdAt: new Date("2026-01-01T06:00:00"),
  };
  return { infos };
}

// Custom field component approach
function DateTimeField({ name }: { name: FieldName<Date> }) {
  const field = useField(name);
  const control = useControl({
    defaultValue: field.defaultValue,
  });
  return (
    <>
      <input type="text" ref={control.register} name={field.name} />
      <input
        type="datetime-local"
        value={control.value?.substring(0, 16)}
        onChange={(e) => {
          control.change(e.target.valueAsDate?.toISOString() ?? "");
        }}
      />
    </>
  );
}

export default function Component({ loaderData, actionData }) {
  const { infos } = loaderData;

  // Data preparation approach
  const prepared = {
    createdAt: infos.createdAt,
    updatedAt: infos.updatedAt.toISOString().substring(0, 16),
  };

  const { form, fields } = useForm(schema, {
    id: "form-zod",
    defaultValue: prepared,
    lastResult: actionData,
  });

  const dirty = useFormData(form.id, (formData) => {
    return isDirty(formData, { defaultValue: prepared });
  });

  return (
    <FormProvider context={form.context}>
      <div>Dirty {dirty ? "yes" : "no"}</div>
      <Form method="post" {...form.props}>
        {/* Using custom component */}
        <DateTimeField name={fields.createdAt.name} />

        {/* Using prepared data */}
        <input
          type="datetime-local"
          defaultValue={fields.updatedAt.defaultValue}
          name={fields.updatedAt.name}
        />
        <div>errors: {fields.updatedAt.errors}</div>
        <div>
          <button>Save</button>
        </div>
      </Form>
    </FormProvider>
  );
}

Question

I think I'm missing something but I can't find what.

I'm wondering why I need to prepare a date for the input (string without the "Z" suffix) but I don't need to prepare a checkbox ("on" string) if I wanted to use a checkbox.

Expected behavior: Being able to pass a Date object directly as defaultValue for a datetime-local input, similar to how checkboxes work.

Current behavior: I need to either:

• Prepare the data by converting the Date to a string with .toISOString().substring(0, 16)
• Create a custom component that handles the conversion

Is this the intended way to work with date inputs, or is there a more idiomatic approach I should be using?

Thanks for your help!

[edmundhung]

Thanks for bringing this up. Stripping the Z suffix does mean we lose explicit timezone information, but it probably makes sense as a default to treat everything as UTC.

To support a different timezone, people would need a custom serialize function. The only thing I am still not fully sure about is how best to support cases where the datetime needs to be coerced based on another field value (for example, when the timezone is provided by the user in the same form), but overall I am on board with the suggestion.

[lhapaipai]

Hi,

I've been working on handling datetime-local inputs with @conform-to/react and @conform-to/zod, and I'd like to know whether my approach follows the recommended practices.

The schema uses z.date() wrapped with coerceFormValue to handle the string-to-Date coercion on the client side. On the display side, I convert the Date to a local datetime string using local getters (getFullYear, getMonth, etc.) to match the browser's native behavior for datetime-local inputs. I also reuse the same formatting function inside the isDirty serializer so that the dirty check compares values consistently.

const baseSchema = z.object({
  updatedAt: z.date(),
});

const clientSchema = coerceFormValue(baseSchema);


export function parseDate(unknown: Date | string | number) {
  return typeof unknown === "string"
    ? new Date(unknown)
    : typeof unknown === "number"
      ? new Date(unknown * 1000)
      : unknown;
}

export function formatDateToDatetimeLocal(unknown: Date | number | string): string {
  const date = parseDate(unknown);
  const year = date.getFullYear();
  const month = (date.getMonth() + 1).toString().padStart(2, "0");
  const day = date.getDate().toString().padStart(2, "0");
  const hours = date.getHours().toString().padStart(2, "0");
  const minutes = date.getMinutes().toString().padStart(2, "0");
  return `${year}-${month}-${day}T${hours}:${minutes}`;
}

export default function Component({ loaderData, actionData }: Route.ComponentProps) {
  const { user } = loaderData;

  const defaultValue = {
    updatedAt: user.updatedAt,
  };

  const { form, fields } = useForm(clientSchema, {
    id: "form-zod",
    defaultValue,
    lastResult: actionData,
  });

  const dirty = useFormData(form.id, (formData) => {
    return isDirty(formData, {
      defaultValue,
      serialize(value, defaultSerialize) {
        if (value instanceof Date) {
          return formatDateToDatetimeLocal(value);
        }

        return defaultSerialize(value);
      },
    });
  });

  return (
    <div>
      <div>Dirty {dirty ? "Yes" : "No"}</div>
      <Form method="post" {...form.props} className="flex flex-col gap-2">
        <div>
          updatedAt
          <input
            className="border"
            type="datetime-local"
            defaultValue={formatDateToDatetimeLocal(fields.updatedAt.defaultValue)}
            name={fields.updatedAt.name}
          />
        </div>

        <Button>Save</Button>
      </Form>
    </div>
  );
}

[edmundhung]

This looks mostly correct to me. You can simplify formatDateToDatetimeLocal to:

export function formatDateToDatetimeLocal(unknown: Date | number | string): string {
  return parseDate(unknown).toISOString().slice(0, -1);
}

If you have multiple forms that need this behavior, I’d recommend using configureForms with one of these approaches:

• Add a custom serialize option that formats Date with formatDateToDatetimeLocal. This makes fields.updatedAt.defaultValue match datetime-local directly.
• Or use extendFieldMetadata to define a custom metadata (for example, defaultUTCDateTimeString) when you only want this for specific fields, while keeping default serialization elsewhere.

That said, I understand your pain and I think it's fair to expect it defaults to UTC. So I just opened #1174 to update the default setup. But your current solution (and the options above) still applies when you need non-UTC timezone behavior.

[edmundhung]

Just notice your solution is formatting the time to local time instead of UTC. This will work if you are parsing the data fully local, but would fail on the server side if they don't share the same timezone setting. You will either need to customize coerceFormValue on how it coerce the datetime string in the server with additional timezone info you have. or just keep it as a string so you can process that manually.

[lhapaipai]

thank you very much @edmundhung !!

However, I would just like to draw your attention to this point.

function parseDate(unknown) {
  return typeof unknown === "string"
    ? new Date(unknown)
    : typeof unknown === "number"
      ? new Date(unknown * 1000)
      : unknown;
}

function formatDateToDatetimeLocal(unknown) {
  const date = parseDate(unknown);
  const year = date.getFullYear();
  const month = (date.getMonth() + 1).toString().padStart(2, "0");
  const day = date.getDate().toString().padStart(2, "0");
  const hours = date.getHours().toString().padStart(2, "0");
  const minutes = date.getMinutes().toString().padStart(2, "0");
  return `${year}-${month}-${day}T${hours}:${minutes}`;
}

const now = new Date();

console.log(formatDateToDatetimeLocal(now)); // 2026-03-04T16:23
console.log(now.toISOString().slice(0, -1)); // 2026-03-04T15:23:53.795

formatDateToDatetimeLocal and ...toISOString().slice(0, -1) do not return the same thing.

For the first one, date.getHours() returns the time in the local timezone (16:23 in the Europe/Paris timezone).
For the second one with slice, it is the UTC time (15:23...), which therefore seems incorrect.

[edmundhung]

Right, I only noticed this right before your message.

The main issue with this approach is an implicit runtime-timezone assumption. It can appear to work in local development because client and server often share the same timezone, but it can diverge in production when they differ.

This is why datetime handling is often tricky 😓 If you want local-time semantics to be consistent across environments, you need to include timezone info both when you render the form and submit it to the server. Maybe submitted with the rest of the form value, or restored from previously stored user settings.

If timezone semantics are not important for your use case, treating it as a plain string is also a reasonable simpler option.

[lhapaipai]

Thanks @edmundhung

[lhapaipai]

Hi @edmundhung,

Thank you for your work on dates. It's a bit awkward to say, but I'm troubled by the changes you made. I ran several tests and find myself in an even trickier situation than before: if you pass a UTC date without the "Z" suffix to a datetime-local input and then call toISOString() on that same input, you end up with a UTC date that has shifted.

const dateStr = "2026-03-14T12:00:00.000Z"

const dateForInputDateTimeLocal = "2026-03-14T12:00:00.000";

// visible to the user: the UTC value 2026-03-14T12:00
// it would never happen that the user actually wants to display
// the UTC value.
<input id="date" type="datetime-local" defaultValue={dateForInputDateTimeLocal} />

const $input = document.getElementById("date")

// value sent from the browser
// "2026-03-14T12:00"
const dateFromInput = $input.value

// value interpreted according to the server's timezone
"2026-03-14T11:00:00.000Z"

I therefore think the discussion I had opened was perhaps not meant to drive a change, and that ultimately, using a UTC datetime string as-is in a datetime-local input should be avoided. I also think the Z suffix should be kept, as its absence can be a source of confusion for the user but also when instantiating via new Date().

new Date("2026-03-14T12:00:00.000")
// are definitely different from
new Date("2026-03-14T12:00:00.000Z")

I look forward to reading your reply. Have a great day!

[edmundhung]

I actually made the change exactly for this two weeks ago in #1174, where we will start serializing date to a local datetime string by calling .toISOString() with the trailing Z stripped, while our schema integration will start coercing these local datetime string by appending Z first before parsing it.

Maybe you can give the pre-release a try and let me know how it plays out for you?

[lhapaipai]

Hi @edmundhung! Thanks for the quick follow-up and for the pre-release — I gave it a try and wanted to share what I found.

The approach in #1174 (stripping the Z from .toISOString() on serialization, then appending it back on coercion) is elegant in principle, but .toISOString() always returns UTC, not local time. Stripping Z produces a UTC timestamp disguised as a naive datetime, which surfaces a few concrete issues in practice:

This surfaces several concrete issues:

1. Wrong display for non-UTC users — a date stored as 21:00 UTC+1 is shown as 20:00 in the input
2. isDirty is always true — format mismatch between the serialized defaultValue ("...T20:08:00.000") and the browser's form value ("...T20:08")
3. Unsafe server-side coercion — only correct if client and server share the same timezone
4. TypeScript error — report({ value: result.data }) fails because Date is not assignable to FormValue

import type { Route } from "./+types/zod-future";

import { coerceFormValue, formatResult } from "@conform-to/zod/v4/future";
import { isDirty, parseSubmission, report, useForm, useFormData } from "@conform-to/react/future";
import { z } from "zod/v4";

import { prisma } from "~/lib/db/prisma.server";
import { data } from "react-router";

import { Form } from "react-router";
import { Button } from "pentatrion-design/button";
import { createToastInCookieHeaders } from "~/lib/toast/toast.server";
import { UserRepository } from "~/domain/musician/.server/user.repository";

const baseSchema = z.object({
  firstName: z.string(),
  updatedAt: z.date(),
});

const schema = coerceFormValue(baseSchema);

export async function action({ request }: Route.ActionArgs) {
  const formData = await request.formData();
  const submission = parseSubmission(formData);

  // ISSUE 3 — Unsafe server-side coercion
  // The browser sends a naive datetime string without timezone: "2026-02-19T20:00"
  // the round-trip is correct because client and server happen to share the same offset.
  // On a UTC server with a UTC+1 client, the parsed date would be off by 1 hour.
  const result = schema.safeParse(submission.payload);

  if (!result.success) {
    return report(submission, {
      error: formatResult(result),
    });
  }

  await UserRepository.update({
    where: { id: "lhapaipai" },
    data: result.data,
  });

  return data(
    report(submission, {
      reset: true,
      // ISSUE 4 — TypeScript error
      // Type '{ firstName: string; updatedAt: Date }' is not assignable to
      // type 'Record<string, FormValue>'. A Date object is not a valid FormValue,
      // so repopulating the form with server data after submission is not typesafe.
      value: result.data,
    }),
    {
      headers: await createToastInCookieHeaders("changements enregistrés !"),
    },
  );
}

export async function loader() {
  const user = await prisma.user.findUniqueOrThrow({
    where: { id: "lhapaipai" },
  });

  // user.updatedAt is a JS Date: Thu Feb 19 2026 21:00:00 GMT+0100
  // user.updatedAt.toISOString() → "2026-02-19T20:08:00.000Z"  (UTC)
  return { user };
}

export default function Component({ loaderData, actionData }: Route.ComponentProps) {
  const { user } = loaderData;

  const defaultValue = {
    firstName: user.firstName,
    updatedAt: user.updatedAt,
    // ^ Date object: Thu Feb 19 2026 21:00:00 GMT+0100
  };

  const { form, fields } = useForm(schema, {
    id: "form-zod",
    defaultValue,
    lastResult: actionData,
  });

  const dirty = useFormData(form.id, (formData) => {
    // ISSUE 2 — isDirty is always true
    //
    // conform serializes defaultValue.updatedAt (a Date) using .toISOString().slice(0, -1):
    //   → "2026-02-19T20:08:00.000"   (UTC, with milliseconds, no Z)
    //
    // The browser's datetime-local input exposes its value at minute precision:
    //   → "2026-02-19T20:08"          (what formData contains, untouched by the user)
    //
    // These two strings never match, so the form is considered dirty on every render
    // even when the user has made no changes.
    return isDirty(formData, {
      defaultValue,
    });
  });

  console.log(fields.updatedAt.defaultValue);
  // → "2026-02-19T20:08:00.000"
  // This is the UTC time serialized by conform (.toISOString().slice(0, -1)).

  return (
    <div>
      <div>Dirty {dirty ? "Yes" : "No"}</div>
      <Form method="post" {...form.props} className="flex flex-col gap-2">
        <div>
          firstName
          <input
            className="border"
            type="test"
            defaultValue={fields.firstName.defaultValue}
            name={fields.firstName.name}
          />
        </div>

        <div>
          updatedAt
          <input
            className="border"
            type="datetime-local"
            // ISSUE 1 — Wrong display for non-UTC users
            //
            // fields.updatedAt.defaultValue is "2026-02-19T20:08:00.000"
            // This is the UTC time (Z stripped). The user is in UTC+1 and expects
            // to see 21:08, but the input shows 20:08 instead.
            //
            // .toISOString() always returns UTC — stripping Z does not produce
            // a local datetime string, it produces a UTC datetime without a timezone marker.
            defaultValue={fields.updatedAt.defaultValue}
            name={fields.updatedAt.name}
          />
        </div>

        <Button>Save</Button>
      </Form>
    </div>
  );
}

[edmundhung]

Thanks for all the details!

I should have mentioned this changes in #1174 is only meant to make the default date serilaizing logic usable for people who are fine with UTC date time string, which I would expect to be quite common especially for back office applications. If you need to display and handle non UTC date time string, what we discussed hasn't really changed.

But I agree issue 2 and 4 shouldn't happen. I will work on a fix.

[lhapaipai]

I've been misled by the JS property valueAsDate, which doesn't seem to work as I expected.
Thank you very much for the clarification!

Your implementation seems to be the best approach in this tricky area. Maybe the Temporal API will help us in the future?

One last point: defaultValue always returns the UTC stringified date without the trailing Z. I wonder whether this choice is suitable for all use cases, such as native components versus UI toolkits.