Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/relay-tools/react-relay-mutation
Higher-level React mutation API for Relay
https://github.com/relay-tools/react-relay-mutation
Last synced: about 2 months ago
JSON representation
Higher-level React mutation API for Relay
- Host: GitHub
- URL: https://github.com/relay-tools/react-relay-mutation
- Owner: relay-tools
- License: mit
- Created: 2019-03-25T17:42:12.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2024-07-30T04:36:43.000Z (about 2 months ago)
- Last Synced: 2024-07-30T12:15:16.357Z (about 2 months ago)
- Language: TypeScript
- Homepage:
- Size: 2.38 MB
- Stars: 40
- Watchers: 4
- Forks: 2
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-list - react-relay-mutation - level React mutation API for Relay | relay-tools | 43 | (TypeScript)
README
# React Relay Mutation [![Travis][build-badge]][build] [![npm][npm-badge]][npm]
Higher-level [React](https://reactjs.org/) mutation API for [Relay](https://relay.dev/).
## Usage
This package provides a `useMutation` Hook and a `` component. These wrap up committing Relay mutations and keeping track of the mutation state.
```js
import React from 'react';
import { Mutation, useMutation } from 'react-relay-mutation';
/* ... */
function MyComponentWithHook({ myValue }) {
const [mutate, { loading }] = useMutation(
graphql`
mutation ExampleWithHookMutation($input: MyMutationInput) {
myMutation(input: $input) {
value
}
}
`,
{
onCompleted: ({ myMutation }) => {
window.alert(`received ${myMutation.value}`);
},
},
);
return loading ? (
) : (
{
mutate({
variables: {
input: { value: myValue },
},
});
}}
>
Run Mutation
);
}
function MyComponentWithComponent({ myValue }) {
return (
{
window.alert(`received ${myMutation.value}`);
}}
>
{([mutate, { loading }]) =>
loading ? (
) : (
{
mutate({
variables: {
input: { value: myValue },
},
});
}}
>
Run Mutation
)
}
);
}
```
The `useMutation` hook and the `` component take a mutation node and optionally any mutation options valid for `commitMutation` in Relay, except that `onCompleted` only takes a single argument for the response, as errors there will be handled identically to request errors. The `useMutation` hook takes the mutation as its first argument, and the optional configuration object as its second argument. The `` component takes the mutation node as the `mutation` prop, and any other options as props by name. In both cases, `variables` is optional.
Both `useMutation` and `` provide a tuple of a `mutate` callback and a `mutationState` object. This is the return value for `useMutation` and the argument passed into the function child for ``.
The `mutate` callback optionally takes a configuration object as above. Any options specified here will override the options specified to `useMutation` or to ``. Additionally, if `variables` was not specified above, it must be specified here. The `mutate` callback returns a promise. This will resolve with the mutation response or reject with any error (except when an `onError` callback is specified, in which case it will resolve with no value on errors).
The `mutationState` object has the following properties:
- `loading`: a boolean indicating whether the mutation is currently pending
- `data`: the response data for the mutation
- `error`: any errors returned by the mutation
### Specifying the Relay environment
By default, `useMutation` and `` take the Relay environment from React context. This context is automatically provided by `` and by many integrations that replace ``, such as Found Relay.
If you do not already have the Relay environment in context, you can provide the environment manually:
```js
import { ReactRelayContext } from 'react-relay';
/* ... */
function MyAppWithRelayEnvironment() {
return (
);
}
```
You can also pass in the environment in the configuration object:
```js
const [mutate] = useMutation(mutation, { environment });
```
## Acknowledgements
This library closely follows the mutation API in [React Apollo](https://www.apollographql.com/docs/react/).
[build-badge]: https://img.shields.io/travis/relay-tools/react-relay-mutation/master.svg
[build]: https://travis-ci.org/relay-tools/react-relay-mutation
[npm-badge]: https://img.shields.io/npm/v/react-relay-mutation.svg
[npm]: https://www.npmjs.org/package/react-relay-mutation