Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
e99a7d3
feat(ember-form): add Ember adapter
NullVoxPopuli May 8, 2026
56454b8
feat(ember-form): closure-bound this.form.Field
NullVoxPopuli May 8, 2026
5816eb1
feat(ember-form): address review — trackedObject, reactive args, docs
NullVoxPopuli May 8, 2026
fbfd92f
feat(ember-form): bump ember-source to 7.1.0-alpha.5, strip `on`/`fn`…
NullVoxPopuli May 12, 2026
290b230
chore(ember-form): address review notes + self-cleanup pass
NullVoxPopuli May 13, 2026
c7b14f3
feat(ember-form)!: refactor createForm into a component factory
NullVoxPopuli May 14, 2026
5894482
docs(ember-form): adopt tanstackForm / f block-param convention
NullVoxPopuli May 17, 2026
905b525
chore(ember-form): align with NullVoxPopuli/ember-primitives conventions
NullVoxPopuli May 22, 2026
381e565
style(ember-form): apply the repo prettier config
NullVoxPopuli Sep 17, 2026
85f19f9
refactor(ember-form): typed Field, useSelector, one subscription per …
NullVoxPopuli Sep 17, 2026
c4f631a
docs(ember-form): show the quick start in a class-based component
NullVoxPopuli Sep 17, 2026
d645fe9
docs(ember-form): explain why the examples do not use the name `form`
NullVoxPopuli Sep 17, 2026
9cde168
test(ember-form): cover the behaviors that the other adapters test
NullVoxPopuli Sep 17, 2026
84b3803
ci(ember-form): run the browser tests on the GitHub runner
NullVoxPopuli Sep 17, 2026
51f6d2b
perf(ember-form): de-dupe store tracking per key
NullVoxPopuli Sep 17, 2026
ce9fce2
feat(ember-form): support ember-source 6.8
NullVoxPopuli Sep 17, 2026
1a23626
refactor(ember-form): plain getters instead of a Proxy in trackStore
NullVoxPopuli Sep 17, 2026
2bce6e2
revert(ember-form): the minimum is ember-source 7.1, not 6.8
NullVoxPopuli Sep 17, 2026
4dbba13
perf(ember-form): one render pass, and no option updates on a keystroke
NullVoxPopuli Nov 19, 2026
2655f59
docs(ember-form): keyed array rows, tracked form state, fixed examples
NullVoxPopuli Nov 19, 2026
a3a10bd
ci(ember-form): install ember-source 7.1 for the oldest-version job
NullVoxPopuli Nov 19, 2026
1ed4884
docs(ember-form): list the open work in TODO.md
NullVoxPopuli Nov 19, 2026
045e352
refactor(ember-form): give Field live options, and document the updat…
NullVoxPopuli Nov 19, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 37 additions & 0 deletions .github/workflows/pr.yml
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,43 @@ jobs:
directory: packages
env:
CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
test-browser:

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we test in the browser, becaues thats where our users are

(the typical (end-)user is not running jsdom in node)

name: Test (browser, ember-source ${{ matrix.ember-source || 'current' }})
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
# '' keeps the version in the lockfile. '~7.1.0' is the oldest supported version.
ember-source: ['', '~7.1.0']
steps:
- name: Checkout
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
with:
fetch-depth: 0
persist-credentials: false
- name: Setup Tools
uses: TanStack/config/.github/setup@99d23c6212f36eff17d30a21e58da77f55a4cfe9 # main
- name: Get base and head commits for `nx affected`
uses: nrwl/nx-set-shas@3e9ad7370203c1e93d109be57f3b72eb0eb511b1 # v4.4.0
with:
main-branch-name: main
- name: Install ember-source ${{ matrix.ember-source }}
if: ${{ matrix.ember-source != '' }}
# `pnpm add` keeps the version in the lockfile if it satisfies the new range.
run: |
pnpm --filter @tanstack/ember-form exec node --eval '
const fs = require("node:fs")
const pkg = JSON.parse(fs.readFileSync("package.json", "utf8"))
pkg.devDependencies["ember-source"] = process.env.EMBER_SOURCE
fs.writeFileSync("package.json", JSON.stringify(pkg, null, 2) + "\n")
'
pnpm install --no-frozen-lockfile
pnpm --filter @tanstack/ember-form exec node --print 'require("ember-source/package.json").version'
env:
EMBER_SOURCE: ${{ matrix.ember-source }}
# Nx agents have no browser. This runner has Chrome.
- name: Run Browser Tests
run: pnpm run test:browser
preview:
name: Preview
runs-on: ubuntu-latest
Expand Down
42 changes: 42 additions & 0 deletions docs/config.json
Original file line number Diff line number Diff line change
Expand Up @@ -98,6 +98,15 @@
"to": "framework/svelte/quick-start"
}
]
},
{
"label": "ember",
"children": [
{
"label": "Quick Start",
"to": "framework/ember/quick-start"
}
]
}
]
},
Expand Down Expand Up @@ -411,6 +420,39 @@
"to": "framework/svelte/guides/form-composition"
}
]
},
{
"label": "ember",
"children": [
{
"label": "Basic Concepts",
"to": "framework/ember/guides/basic-concepts"
},
{
"label": "Form Validation",
"to": "framework/ember/guides/validation"
},
{
"label": "Dynamic Validation",
"to": "framework/ember/guides/dynamic-validation"
},
{
"label": "Async Initial Values",
"to": "framework/ember/guides/async-initial-values"
},
{
"label": "Arrays",
"to": "framework/ember/guides/arrays"
},
{
"label": "Linked Fields",
"to": "framework/ember/guides/linked-fields"
},
{
"label": "Form Composition",
"to": "framework/ember/guides/form-composition"
}
]
}
]
},
Expand Down
116 changes: 116 additions & 0 deletions docs/framework/ember/guides/arrays.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,116 @@
---
id: arrays
title: Arrays
---

TanStack Form supports arrays as values in a form, including sub-object values inside of an array.

## Basic Usage

> The examples name the form component `PeopleForm` and the yielded form `tanstackForm`. [Why not `form`?](./basic-concepts.md#why-not-form) explains the names.

To use an array, you can iterate over `field.state.value` with [`{{#each}}`](https://api.emberjs.com/ember/release/classes/Ember.Templates.helpers/methods/each):

```gjs
import { createForm } from '@tanstack/ember-form';

const PeopleForm = createForm({
Comment thread
NullVoxPopuli-ai-agent marked this conversation as resolved.
Resolved
defaultValues: {
people: [],
},
});

<template>
<PeopleForm as |tanstackForm|>
<tanstackForm.Field @name="people" @mode="array" as |field|>
{{#each field.state.value key="@index" as |person|}}
{{!-- ... --}}
{{/each}}
</tanstackForm.Field>
</PeopleForm>
</template>
```

Always pass `key="@index"`. Without it, `{{#each}}` identifies a row by its value. form-core replaces the value of a row on each change, so the row renders from the start and its input loses the focus.

This will regenerate the list every time you run `pushValue` on `field`:

```gjs
const addPerson = (field) => field.pushValue({ name: '', age: 0 });

{{!-- inside a template --}}
<button {{on "click" (fn addPerson field)}} type="button">
Add person
</button>
```

Finally, you can use a subfield like so:

```gjs
const handleInput = (field, event) => field.handleChange(event.target.value);
const nameAt = (i) => `people[${i}].name`;

{{!-- inside a template --}}
<tanstackForm.Field @name={{nameAt i}} as |subField|>
<input
value={{subField.state.value}}
{{on "input" (fn handleInput subField)}}
/>
</tanstackForm.Field>
```

## Full Example

```gjs
import { createForm } from '@tanstack/ember-form';

const handleInput = (field, event) => field.handleChange(event.target.value);
const nameAt = (i) => `people[${i}].name`;
const addPerson = (field) => field.pushValue({ name: '', age: 0 });

const onSubmitFor = (form) => (event) => {
event.preventDefault();
event.stopPropagation();
form.handleSubmit();
};

const handleSubmit = ({ value }) => alert(JSON.stringify(value));

const PeopleForm = createForm({
defaultValues: {
people: [],
},
});

<template>
<PeopleForm @onSubmit={{handleSubmit}} as |f|>
<form id="form" {{on "submit" (onSubmitFor f)}}>
<f.Field @name="people" @mode="array" as |field|>
<div>
{{#each field.state.value key="@index" as |_person i|}}
<f.Field @name={{nameAt i}} as |subField|>
<div>
<label>
<div>Name for person {{i}}</div>
<input
value={{subField.state.value}}
{{on "input" (fn handleInput subField)}}
/>
</label>
</div>
</f.Field>
{{/each}}

<button {{on "click" (fn addPerson field)}} type="button">
Add person
</button>
</div>
</f.Field>

<button type="submit">Submit</button>
</form>
</PeopleForm>
</template>
```

> Note: in strict-mode templates you can't put complex expressions like `` `people[${i}].name` `` directly into an attribute or argument value. The `nameAt` helper above is a small module-level function that does the templating in JavaScript and is then invoked as `{{nameAt i}}`.
122 changes: 122 additions & 0 deletions docs/framework/ember/guides/async-initial-values.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,122 @@
---
id: async-initial-values
title: Async Initial Values
---

Let's say that you want to fetch some data from an API and use it as the initial value of a form.

While this problem sounds simple on the surface, there are hidden complexities you might not have thought of thus far.

For example, you might want to show a loading spinner while the data is being fetched, or you might want to handle errors gracefully. Likewise, you could also find yourself looking for a way to cache the data so that you don't have to fetch it every time the form is rendered.

While we could implement many of these features from scratch, it would end up looking a lot like another project we maintain: [TanStack Query](https://tanstack.com/query).

As such, this guide shows you how you can mix-n-match TanStack Form with a data-loading utility (such as [`ember-resources`](https://github.com/NullVoxPopuli/ember-resources), [warp-drive](https://github.com/emberjs/data), or your own routing layer) to achieve the desired behavior.

## Basic Usage

The general shape of the solution is:

1. Load the data outside of the form (in a route, a resource, or a parent component).
2. Render the form only once the data is available, passing the resolved values into the invocation as `@defaultValues`.

Because `createForm` is called at module scope, the component it returns is constructed every time it's invoked in a template. The simplest pattern is to render the form invocation inside an `{{#if}}` that gates on the loading state and pass the resolved data as `@defaultValues`. An arg on the invocation replaces the same key in the options of `createForm`, so `@defaultValues` replaces the fallback values.

```gjs
// person-form.gts
import { createForm } from '@tanstack/ember-form';

const handleInput = (field, event) => field.handleChange(event.target.value);

const onSubmitFor = (form) => (event) => {
event.preventDefault();
event.stopPropagation();
form.handleSubmit();
};

const handleSubmit = async ({ value }) => {
// Do something with form data
console.log(value);
};

const PersonForm = createForm({
// Fallback values. `@defaultValues` replaces them.
defaultValues: {
firstName: '',
lastName: '',
},
});

<template>
<PersonForm
@defaultValues={{@initial}}
@onSubmit={{handleSubmit}}
as |f|
>
<form {{on "submit" (onSubmitFor f)}}>
<f.Field @name="firstName" as |field|>
<input
name={{field.name}}
value={{field.state.value}}
{{on "blur" field.handleBlur}}
{{on "input" (fn handleInput field)}}
/>
</f.Field>
<f.Field @name="lastName" as |field|>
<input
name={{field.name}}
value={{field.state.value}}
{{on "blur" field.handleBlur}}
{{on "input" (fn handleInput field)}}
/>
</f.Field>
<button type="submit">Submit</button>
</form>
</PersonForm>
</template>
```

```gjs
// page.gts
import Component from '@glimmer/component';
import { getPromiseState } from 'reactiveweb/get-promise-state';
import PersonForm from './person-form.gts';

async function loadPerson() {
await new Promise((resolve) => setTimeout(resolve, 1000));

return { firstName: 'FirstName', lastName: 'LastName' };
}

export default class PersonPage extends Component {
request = loadPerson();

get person() {
return getPromiseState(this.request);
}

<template>
{{#if this.person.isLoading}}
<p>Loading...</p>
{{else if this.person.error}}
<p>The person did not load.</p>
{{else}}
<PersonForm @initial={{this.person.resolved}} />
{{/if}}
</template>
}
```

The page shows the loading text until the promise resolves. `<PersonForm>` renders only after that, so the form starts with the fetched values.

> The example uses `getPromiseState` from [`reactiveweb`](https://github.com/universal-ember/reactiveweb). It derives `isLoading`, `error`, and `resolved` from a promise, so the component has no loading flags of its own. Any other source of data works the same way: a route model, ember-resources, or warp-drive. Do not render the form until the data is ready.

## Updating defaults after the form is mounted

To render the form immediately, pass the loaded values when they arrive. The form applies changed args by itself.

```gjs
<PersonForm @initial={{this.person.resolved}} />
```

New default values do not replace the input of a user. A field that the user touched keeps its value.
Loading