Getting started: build a GraphQL Form in 5 minutes

Install the library

• yarn add react-apollo-form OR
• npm i react-apollo-form

then, add to your package.json scripts section:

"react-apollo-form": "react-apollo-form fetch-mutations <graphqlEndpoint> <outpurDir>"

• graphqlEndpoint should be the url of your GraphQL API, ex: "http://localhost:3000/graphql"
• outpurDir should be the path where files will be generated, ex: "./src/core/forms"

---

Generating "meta" files

Just run npm run react-apollo-form.

You should see 3 steps : "schema download", "mutations types generations", "json schema generation".

If the commands do not finish with "Done.", please check:

• that your GraphQL server is accessible (up and without authentication)
• that your GraphQL server has 'introspection' enabled !
• that the outputDir is writable

---

Configuring a "Form component"

react-apollo-form expose a configure(options) function with the following options:

interface ApolloFormConfigureOptions {
    client: ApolloClient<any>;
    jsonSchema: JSONSchema6;
    theme?: ApolloFormConfigureTheme;
}

• client is necessary in order to call the mutation when a form submit
• jsonSchema is necessary for extract mutation arguments as form fields
• theme is optional (see "Theming")

TypeScript Tips

For TypeScript users, configure() takes a "type arguments" for mutations names union types. The script generates 3 files, including a mutations.d.ts that expose a ApolloFormMutationNames type.

Providing ApolloFormMutationNames to configure() will allow nice autocomplete when building a form (see next section)

Usage

import * as React from 'react';
import { configure } from 'react-apollo-form';
import { client } from './apollo'; // a file thats export a configured Apollo Client


const jsonSchema = require('./core/apollo-form-json-schema.json');

export const ApplicationForm = configure<ApolloFormMutationNames>({
    // tslint:disable-next-line:no-any
    client: client as any,
    jsonSchema
});

---

Build your first form

We now have a fresh <ApplicationForm> form component.

Here are the available props:

type ApolloFormProps<MutationNamesType> = {
    data: any;
    config: ApolloFormConfig & { mutation?: { name: MutationNamesType } };
    ui?: UiSchema & ApolloFormUi;
    title?: string;
    subTitle?: string;
    onSave?: (data: object) => void;
    onCancel?: () => void;
    children?: React.SFC<ApolloRenderProps>;
    liveValidate?: boolean;
}

Props

Prop	Description
data	initial data to fill the fields
config	There is two types of config, see below the table
ui	same as react-jsonschema-form, see below the table
title	Form title (string)
subtitle	Form subtitle (string)
onSave	callback after save ((data: object) => void)
onCancel	callback on cancel action (() => void)
liveValidate	should the form run validation on user actions or on submit ? (boolean, default: false)

Props.config : ApolloFormConfig

There is two config mode:

• form from mutation: ApolloFormConfigMutation
• form from raw schema: ApolloFormConfigManual

ApolloFormConfigMutation

Given a mutation name and document, ApolloForm will fetch mutations arguments and "convert" them to form fields (as JSON Schema properties).

ApolloForm will call mutation.document to save data on submit.

interface ApolloFormConfigMutation extends ApolloFormConfigBase {
    mutation: {
        name: string; // mutation name
        document: DocumentNode; // mutation document
        // apollo mutation options
        variables?: object;
        context?: object;
        refetchQueries?: string[] | PureQueryOptions[] | RefetchQueriesProviderFn;
    };
}

ApolloFormConfigManual

If your form is not linked directly to a mutation, you can switch to "manual mode" by passing a raw JSON Schema and a callback to saveData on submit.

interface ApolloFormConfigManual extends ApolloFormConfigBase {
    schema: JSONSchema6;
    saveData: (formData: any) => any;
}