Forms


In Tina, forms are how you expose your site's content for editing.

Local & Global Forms

There are two distinct types of forms: Local and Global. Local forms are contextual, typically associated with editing content specific to the page or context. Local forms render in the sidebar by default.

tina-grande-local-form

Global forms live within a settings-type panel, they could be site-wide settings, theme configurations, general metadata, or other top-level configs. In the sidebar, global forms are accessed via the hamburger menu in the upper left-hand corner. These forms are typically registered on a global (layout) component so that they are always accessible through different page contexts.

tina-grande-global-form

Setup Predefined Forms

Most of the time, you will be using predefined forms provided by Tina. If you're using Gatsby, most of your needs will be met by the remark & JSON forms already defined by Tina. If your site uses Markdown as a data source, head over to the Using Markdown Files tutorial. If you need to edit JSON data, head over to the Using JSON Files tutorial.

Creating Custom Forms

If you want to make custom forms, they can be created by invoking the useForm, useLocalForm, or useGlobalForm hooks. They are incredibly similar, the main difference being that useLocalForm & useGlobalForm will register the forms as plugins, and useForm does not.

Please note: creating custom forms is considered an advanced use-case. It is recommended for most folks to use Tina's predefined forms mentioned above.

useForm

This custom hook creates a form without registering it to the CMS. Check out the usePlugin hook documentation to see how to register a form to the CMS.

function useForm(
  options: FormOptions,
  watch: Partial<WatchableFormValue> = {}
): [object, Form | undefined]

interface FormOptions {
  id: any
  label: string
  initialValues: object
  fields: Field[]
  onSubmit(object): Promise<object | null>
}

useLocalForm

function useLocalForm(
  options: FormOptions,
  watch: Partial<WatchableFormValue> = {}
): [object, Form | undefined]

interface FormOptions {
  id: any
  label: string
  initialValues: object
  fields: Field[]
  onSubmit(object): Promise<object | null>
}

useGlobalForm

function useGlobalForm(
  options: FormOptions,
  watch: Partial<WatchableFormValue> = {}
): [FormShape, Form | undefined]

interface FormOptions {
  id: any
  label: string
  initialValues: object
  fields: Field[]
  onSubmit(object): Promise<object | null>
}
  • id: Must be a unique identifier.
  • label: The name of the form being edited.
  • initialValues: The initial values being edited by the form.
  • fields: A list of field definitions. This is used to render the form widgets so the values can be edited.
  • onSubmit: A javascript function to be called when the form is submitted. See the final-form docs for more details.

Example

import { useLocalForm } from 'react-tinacms'

function PageTemplate(props) {
  let [someData] = useLocalForm({
    id: 'uid',
    label: 'someData',
    initialValues: props.data.someData,
    fields: [{ name: 'someField', component: 'text' }],
    onSubmit(someData) {
      // ...
    },
  })

  return (
    <div>
      Some Field: <span>{someData.someField}</span>
    </div>
  )
}

Update react-tinacms version:0.9.0: The previous hook useCMSForm used to create custom forms is now the same as useLocalForm