Devour/devour_data/docs/action.json

{
  "id": "04a5fca92d57f145fcbd0c66",
  "source": "solid:signals",
  "type": "github-document",
  "title": "action",
  "content": "---\ntitle: action\nuse_cases: \u003e-\n  forms, user input, data mutations, optimistic updates, form submissions,\n  server actions, post requests\ntags:\n  - actions\n  - forms\n  - mutations\n  - post\n  - validation\n  - optimistic-updates\n  - server\nversion: '1.0'\ndescription: \u003e-\n  Learn how to handle form submissions and data mutations in SolidJS with\n  actions, including optimistic updates and server-side processing.\n---\n\nThe `action` function wraps an asynchronous function and returns an [action](/solid-router/concepts/actions).\n\nWhen an action is triggered, it creates a submission object that tracks its execution status.\nThis state can be accessed with the [`useSubmission`](/solid-router/reference/data-apis/use-submission) and [`useSubmissions`](/solid-router/reference/data-apis/use-submissions) primitives.\n\nAfter an action completed successfully, all queries active in the same page are revalidated, unless revalidation is configured using [response helpers](/solid-router/concepts/actions#managing-navigation-and-revalidation).\n\n## Import\n\n```tsx\nimport { action } from \"@solidjs/router\";\n```\n\n## Type\n\n```tsx\nfunction action\u003cT extends Array\u003cany\u003e, U = void\u003e(\n\tfn: (...args: T) =\u003e Promise\u003cU\u003e,\n\tname?: string\n): Action\u003cT, U\u003e;\n\nfunction action\u003cT extends Array\u003cany\u003e, U = void\u003e(\n\tfn: (...args: T) =\u003e Promise\u003cU\u003e,\n\toptions?: { name?: string; onComplete?: (s: Submission\u003cT, U\u003e) =\u003e void }\n): Action\u003cT, U\u003e;\n\nfunction action\u003cT extends Array\u003cany\u003e, U = void\u003e(\n\tfn: (...args: T) =\u003e Promise\u003cU\u003e,\n\toptions:\n\t\t| string\n\t\t| { name?: string; onComplete?: (s: Submission\u003cT, U\u003e) =\u003e void } = {}\n): Action\u003cT, U\u003e;\n```\n\n## Parameters\n\n### `handler`\n\n- **Type:** `(...args: T) =\u003e Promise\u003cU\u003e`\n- **Required:** Yes\n\nAn asynchronous function that performs the action's logic.\nWhen the action is used with a [`\u003cform\u003e` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/form), the function receives a [`FormData` object](https://developer.mozilla.org/en-US/docs/Web/API/FormData) as its first parameter.\n\n### `options`\n\n- **Type:** `string | { name?: string; onComplete?: (s: Submission\u003cT, U\u003e) =\u003e void }`\n- **Required**: No\n\nA unique string used to identify the action in Server-Side Rendering (SSR) environments.\nThis is required when using the action with a `\u003cform\u003e` element.\n\nAlternatively, a configuration object can be passed with the following properties.\n\n#### `name`\n\n- **Type:** `string`\n- **Required:** No\n\nThe unique string to identify the action in SSR environments.\nRequired for `\u003cform\u003e` usage.\n\n#### `onComplete` (optional):\n\n- **Type:** `(s: Submission\u003cT, U\u003e) =\u003e void`\n- **Required:** No\n\nA function that runs after the action completes.\nIt receives a submission object as its parameter.\n\n## Return value\n\n`action` returns an action with the following properties.\n\n### `with`\n\nA method that wraps the original action and returns a new one.\nWhen this new action is triggered, the arguments passed to `with` are forwarded to the original action.\nIf this new action is used with a `\u003cform\u003e`, the `FormData` object is passed as the last parameter, after any other forwarded parameters.\n\n## Examples\n\n### Form submission\n\n```tsx\nimport { action } from \"@solidjs/router\";\n\nconst addTodoAction = action(async (formData: FormData) =\u003e {\n\t// Adds a new todo to the server.\n}, \"addTodo\");\n\nfunction TodoForm() {\n\treturn (\n\t\t\u003cform action={addTodoAction} method=\"post\"\u003e\n\t\t\t\u003cinput name=\"name\" /\u003e\n\t\t\t\u003cbutton\u003eAdd todo\u003c/button\u003e\n\t\t\u003c/form\u003e\n\t);\n}\n```\n\n### Passing additional arguments\n\n```tsx\nimport { action } from \"@solidjs/router\";\n\nconst addTodoAction = action(async (userId: number, formData: FormData) =\u003e {\n\t// ... Adds a new todo for a specific user.\n}, \"addTodo\");\n\nfunction TodoForm() {\n\tconst userId = 1;\n\treturn (\n\t\t\u003cform action={addTodoAction.with(userId)} method=\"post\"\u003e\n\t\t\t\u003cinput name=\"name\" /\u003e\n\t\t\t\u003cbutton\u003eAdd todo\u003c/button\u003e\n\t\t\u003c/form\u003e\n\t);\n}\n```\n\n### Triggering actions programmatically\n\n```tsx\nimport { action, useAction } from \"@solidjs/router\";\n\nconst markDoneAction = action(async (id: string) =\u003e {\n\t// ... Marks a todo as done on the server.\n});\n\nfunction NotificationItem(props: { id: string }) {\n\tconst markDone = useAction(markDoneAction);\n\n\treturn \u003cbutton onClick={() =\u003e markDone(props.id)}\u003eMark as done\u003c/button\u003e;\n}\n```",
  "url": "https://github.com/solidjs/solid-docs/blob/HEAD/src/routes/solid-router/reference/data-apis/action.mdx",
  "metadata": {
    "path": "src/routes/solid-router/reference/data-apis/action.mdx",
    "repo": "solidjs/solid-docs",
    "repo_url": "https://github.com/solidjs/solid-docs.git",
    "size": 4236,
    "source_type": "github"
  },
  "hash": "5523600ac5072d93213af730058cc9bab92d377d3b66460c29c142462098438f",
  "timestamp": "2026-02-23T11:43:00.192567398+01:00"
}