{"pageProps":{"error":null,"preview":false,"file":{"fileRelativePath":"content/docs/plugins/screens.md","data":{"frontmatter":{"title":"Screen Plugins","prev":"/docs/plugins/content-creators","next":"/docs/plugins/toolbar-widgets"},"excerpt":" Screen Plugins allow you to render modal UI and handle various content editing needs. The purpose of these screens is to give a way to display information about the website that is not suited to&hellip;","markdownBody":"\nScreen Plugins allow you to render modal UI and handle various content editing needs. The purpose of these screens is to give a way to display information about the website that is not suited to inline or sidebar editing.\n\n**Example use cases** may include:\n\n- User Management\n- CI build status\n- Website Metadata e.g. SEO\n- Layout Configuration e.g. MenusFor example, one might use a _Screen Plugin_ to register a form to edit 'global site data'.\n\n## Interface\n\n```ts\nexport interface ScreenPlugin<ExtraProps = {}> {\n  __type: 'screen'\n  name: string\n  Component(props: ScreenComponentProps & ExtraProps): React.ReactElement\n  Icon: any\n  layout: 'fullscreen' | 'popup'\n}\n\nexport interface ScreenComponentProps {\n  close(): void\n}\n```\n\n| Option      | Description                                                                             |\n| ----------- | --------------------------------------------------------------------------------------- |\n| `__type`    | The name of the plugin. Always `'screen'`.                                              |\n| `name`      | The text to be displayed in the form menu and at the top of the screen modal.           |\n| `Component` | An array of fields that populate a modal form. Field values can populate new file data. |\n| `Icon`      | A component to render in the form menu, next to the `name`.                             |\n| `layout`    | Determines the modal layout. Defaults to `popup`.                                       |\n\n### Name, Icon, & Component\n\nThe **`ScreenPlugin` has three main pieces**: a name, an icon, and a React Component. The name and icon can be used to list the screen plugin in a menu.\n\n![global-menu](/img/tina-grande-global-form.jpg)\n\nWhen the user clicks on the menu item, it opens a screen in which the React Component is rendered. _Think of a screen as an empty canvas_, it provides the space to create an editing interface beyond the sidebar.\n\n### Layout\n\nThere are two potential modal layouts for a screen plugin: `fullscreen` and `popup`. You can choose to utilize either depending on the purpose of the _screen_.\n\n![full screen plugin](/img/blog/screen-plugin/fullscreen-screen-plugin.png)\n![popup screen plugin](/img/blog/screen-plugin/popup-screen-plugin.png)\n\nWithin the modal, the `name` & `Component` are rendered.\n\n## Helpers\n\n### _useScreenPlugin_\n\n`useScreenPlugin` creates a screen and registers the plugin with the CMS. It accepts a screen options object and dependencies to watch. If the dependencies update, the screen will update.\n\n```ts\nuseScreenPlugin(options: ScreenOptions, deps: DependencyList): void\n```\n\n**Screen Options**\n\n```ts\nexport interface ScreenOptions<ExtraProps = {}> {\n  name: string\n  Component: React.FC<ExtraProps & ScreenComponentProps>\n  Icon: any\n  layout?: ScreenPlugin['layout']\n  props?: ExtraProps\n}\n```\n\n#### Creating a Screen Plugin\n\nCreating a Screen Plugin with the `useScreenPlugin` hook involves three steps:\n\n1. Import the `useScreenPlugin` hook from `tinacms`\n2. Create a custom `ScreenPlugin`\n3. Register the screen plugin with `useScreenPlugin`\n\n**Example**\n\n```jsx\n// 1. Import `useScreenPlugin`\nimport { useScreenPlugin } from 'tinacms'\n\n// 2. Define the screen plugin\nconst ScreenPlugin = {\n  name: 'Example Screen',\n  Component() {\n    return <h1>This is a screen!</h1>\n  },\n  Icon: () => <span>🦙</span>,\n  layout: 'popup'\n}\n\nexport default function Page() {\n  // 3. Register the plugin\n  useScreenPlugin(ScreenPlugin)\n\n  return (\n      //...\n  )\n}\n```\n\n### _useFormScreenPlugin_\n\n`useFormScreenPlugin` creates and registers a new Screen Plugin that renders a form in a `popup` modal. This is a great place to put forms for content that doesn't belong on any particular page, for example with site metadata.\n\n> Tip: This hook creates what was previously called a _Global Form_.\n\n**Example**\n\n```jsx\nimport { useFormScreenPlugin } from 'tinacms'\nimport { useJsonForm } from 'gatsby-tinacms-json'\n\nfunction Layout(props) {\n  // Create the form\n  const [data, form] = useJsonForm(props.data.dataJson)\n\n  // Register it as a Screen with the CMS\n  useFormScreenPlugin(form)\n\n  return <h1>{data.firstName}</h1>\n}\n```\n\n## Further Reading\n\n- Checkout this [step-by-step blog](/blog/screen-plugins) on **how to create your own Screen Plugin**\n- Learn how to [register plugins](/docs/plugins#adding-plugins) with the CMS\n- Visit the [Field Plugins](/docs/plugins/fields) docs to learn about how you can customize your form.\n"}},"tocItems":"- [Interface](#interface)\n  * [Name, Icon, & Component](#name-icon--component)\n  * [Layout](#layout)\n- [Helpers](#helpers)\n  * [_useScreenPlugin_](#usescreenplugin)\n    + [Creating a Screen Plugin](#creating-a-screen-plugin)\n  * [_useFormScreenPlugin_](#useformscreenplugin)\n- [Further Reading](#further-reading)","docsNav":[{"title":"Getting Started","id":"getting-started","items":[{"id":"/docs/getting-started/introduction","slug":"/docs/getting-started/introduction","title":"Introduction"}]},{"title":"CMS","id":"the-cms","items":[{"id":"/docs/cms","slug":"/docs/cms","title":"Overview"}]},{"title":"User Interface","id":"user-interface","items":[{"id":"/docs/ui","title":"Sidebar & Toolbar","slug":"/docs/ui"},{"title":"Inline Editing","id":"inline-editing","slug":"/docs/ui/inline-editing","items":[{"id":"/docs/ui/inline-editing/inline-text","title":"Inline Text","slug":"/docs/ui/inline-editing/inline-text"},{"id":"/docs/ui/inline-editing/inline-textarea","title":"Inline Textarea","slug":"/docs/ui/inline-editing/inline-textarea"},{"id":"/docs/ui/inline-editing/inline-wysiwyg","title":"Inline Wysiwyg","slug":"/docs/ui/inline-editing/inline-wysiwyg"},{"id":"/docs/ui/inline-editing/inline-image","title":"Inline Image","slug":"/docs/ui/inline-editing/inline-image"},{"id":"/docs/ui/inline-editing/inline-group","title":"Inline Group","slug":"/docs/ui/inline-editing/inline-group"},{"id":"/docs/ui/inline-editing/inline-blocks","title":"Inline Blocks","slug":"/docs/ui/inline-editing/inline-blocks"}]},{"id":"/docs/ui/alerts","title":"Alerts","slug":"/docs/ui/alerts"},{"id":"/docs/ui/styles","title":"Custom Styles","slug":"/docs/ui/styles"}]},{"id":"plugins","title":"Plugins","items":[{"title":"About Plugins","id":"forms","slug":"/docs/plugins"},{"title":"Forms","id":"forms","slug":"/docs/plugins/forms"},{"title":"Fields","id":"fields","slug":"/docs/plugins/fields","items":[{"id":"/docs/plugins/fields/text","slug":"/docs/plugins/fields/text","title":"Text"},{"id":"/docs/plugins/fields/textarea","slug":"/docs/plugins/fields/textarea","title":"Text Area"},{"id":"/docs/plugins/fields/number","slug":"/docs/plugins/fields/number","title":"Number"},{"id":"/docs/plugins/fields/image","slug":"/docs/plugins/fields/image","title":"Image"},{"id":"/docs/plugins/fields/color","slug":"/docs/plugins/fields/color","title":"Color"},{"id":"/docs/plugins/fields/toggle","slug":"/docs/plugins/fields/toggle","title":"Toggle"},{"id":"/docs/plugins/fields/select","slug":"/docs/plugins/fields/select","title":"Select"},{"id":"/docs/plugins/fields/tags","slug":"/docs/plugins/fields/tags","title":"Tags"},{"id":"/docs/plugins/fields/list","slug":"/docs/plugins/fields/list","title":"List"},{"id":"/docs/plugins/fields/group","slug":"/docs/plugins/fields/group","title":"Group"},{"id":"/docs/plugins/fields/group-list","slug":"/docs/plugins/fields/group-list","title":"Group List"},{"id":"/docs/plugins/fields/blocks","slug":"/docs/plugins/fields/blocks","title":"Blocks"},{"id":"/docs/plugins/fields/date","slug":"/docs/plugins/fields/date","title":"Date & Time"},{"id":"/docs/plugins/fields/markdown","slug":"/docs/plugins/fields/markdown","title":"Markdown"},{"id":"/docs/plugins/fields/html","slug":"/docs/plugins/fields/html","title":"HTML"},{"id":"/docs/plugins/fields/custom-fields","slug":"/docs/plugins/fields/custom-fields","title":"Custom Fields"}]},{"title":"Content Creators","id":"content-creator","slug":"/docs/plugins/content-creators"},{"title":"Screens","id":"screens","slug":"/docs/plugins/screens"},{"title":"Toolbar Widgets","id":"toolbar:widget","slug":"/docs/plugins/toolbar-widgets"}]},{"id":"events","title":"Events","items":[{"id":"/docs/events","slug":"/docs/events","title":"About Events"}]},{"title":"Media","id":"media","items":[{"id":"/docs/media","slug":"/docs/media","title":"About Media"}]},{"id":"apis","title":"External APIs","items":[{"id":"/docs/api","slug":"/docs/apis","title":"About APIs"}]},{"title":"Integrations","id":"nextjs","items":[{"id":"/docs/integrations/nextjs","slug":"/docs/integrations/nextjs","title":"Next.js"},{"id":"/docs/integrations/gatsby","slug":"/docs/integrations/gatsby","title":"Gatsby"}]},{"title":"Release Notes","id":"releases","items":[{"id":"/docs/releases","href":"/docs/releases","title":"All Releases"}]},{"title":"Packages","id":"packages","items":[{"id":"/packages/react-tinacms-date","slug":"/packages/react-tinacms-date","title":"react-tinacms-date"},{"id":"/packages/react-tinacms-editor","slug":"/packages/react-tinacms-editor","title":"react-tinacms-editor"},{"id":"/packages/react-tinacms-github","slug":"/packages/react-tinacms-github","title":"react-tinacms-github"},{"id":"/packages/react-tinacms-inline","slug":"/packages/react-tinacms-inline","title":"react-tinacms-inline"},{"id":"/packages/react-tinacms-strapi","slug":"/packages/react-tinacms-strapi","title":"react-tinacms-strapi"},{"id":"/packages/next-tinacms-github","slug":"/packages/next-tinacms-github","title":"next-tinacms-github"},{"id":"/packages/next-tinacms-json","slug":"/packages/next-tinacms-json","title":"next-tinacms-json"},{"id":"/packages/next-tinacms-markdown","slug":"/packages/next-tinacms-markdown","title":"next-tinacms-markdown"},{"id":"/packages/gatsby-plugin-tinacms","slug":"/packages/gatsby-plugin-tinacms","title":"gatsby-plugin-tinacms"},{"id":"/packages/gatsby-tinacms-git","slug":"/packages/gatsby-tinacms-git","title":"gatsby-tinacms-git"},{"id":"/packages/gatsby-tinacms-json","slug":"/packages/gatsby-tinacms-json","title":"gatsby-tinacms-json"},{"id":"/packages/gatsby-tinacms-remark","slug":"/packages/gatsby-tinacms-remark","title":"gatsby-tinacms-remark"}]}],"nextPage":{"slug":"/docs/plugins/toolbar-widgets","title":"Toolbar Widgets"},"prevPage":{"slug":"/docs/plugins/content-creators","title":"Content Creator Plugins"}},"__N_SSG":true}