React Router Actions

Overview

react-router-actions is a package designed to simplify the management of multiple actions on a single React Router route. This is especially useful for scenarios where a route requires different behaviors or processes based on specific user interactions or application states. Currently, it is only compatible with React Router v7.

To install the package, run:

npm i react-router-actions

Features

• [x] Compatible with environments where JavaScript is disabled
• [x] Supports form validation using typeschema
• [x] Extends fetcher functionality with callbacks (onSuccess, onError)
• [ ] Support for custom action URLs (execute actions on routes other than the parent route)

:warning: This library may not be production-ready yet. It is recommended not to use it in production with complex logic. If you encounter any bugs, please open an issue to ensure they are addressed promptly.

Exports

The package exports the following utilities:

actions

A function for defining multiple actions for a single route. You provide an object where each key is the action name, and each value is the function that implements the corresponding action.

validatedAction

A utility for creating actions with built-in input validation. It uses typeschema for validation and expects an object with the following properties:

• input: A schema that defines the expected structure of the input.
• handler: A function that processes the action.

useAction

A React hook to utilize the defined actions in your components. It extends the fetcher object, adding an errors property that captures validation errors returned by validatedAction.

Usage Example

Here’s a practical example demonstrating how to define and use actions within a route:

import { actions, useAction, validatedAction } from 'react-router-actions';
import { useLoaderData } from 'react-router'
import z from 'zod'

export const action = actions({
  updateUser: validatedAction({
    input: z.object({
      first_name: z.string().min(3),
      last_name: z.string().min(3)
    }),
    handler(ctx, body){
      // update user based on 'body'...
      return { message: "User updated successfully" }
    }
  }),
  deleteUser: (ctx) => {
    // delete user ...
    return { message: "User deleted successfully" }
  },
})

export const loader = () => {
  return { userInfo: {...} }
}

function EditUserRoute() {
  const { userInfo } = useLoaderData()
  const updateUser = useAction('updateUser')
  const deleteUser = useAction('deleteUser', {
    onSuccess(data) {
      alert(data.message)
    }
  })

  return (
  <div>
    <updateUser.Form>
      <input name='first_name' defaultValue={userInfo.first_name} />
      {updateUser.errors.first_name && <span>{updateUser.errors.first_name}</span>}
      <input name='last_name' defaultValue={userInfo.last_name} />
      {updateUser.errors.last_name && <span>{updateUser.errors.last_name}</span>}
      <button type='submit'>Save</button>
    </updateUser.Form>
    <deleteUser.Form>
      <button type='submit'>Delete User</button>
    </deleteUser.Form>
  </div>
  );
}

export default EditUserRoute;

Code Breakdown

The actions function organizes multiple actions such as updateUser, which validates user input using zod before updating user data, and deleteUser, a straightforward action to delete a user. The loader function fetches initial user data, which is accessed via useLoaderData to prefill form fields in the component. The useAction hook binds these actions to forms, enhancing them with validation error handling and success callbacks. The updateUser.Form component includes input fields for user details, displays validation errors inline, and submits data to update the user. Meanwhile, the deleteUser.Form component provides a button to delete the user, triggering a success alert upon completion.

By sending the _action query parameter, these forms identify the correct server-side action to execute, ensuring compatibility with environments where JavaScript is disabled.

How Actions Work

1. When a form is submitted, the useAction hook automatically sends the _action query parameter to the server.
2. The server uses this parameter to determine which action to execute.
3. Server executes the action. Based on the action type (a regular action or a validatedAction) it returns the corresponding response.

License

This project is licensed under the MIT License.