{"id":13469719,"url":"https://github.com/nomcopter/react-mosaic","last_synced_at":"2025-05-14T22:05:25.169Z","repository":{"id":39545317,"uuid":"85968492","full_name":"nomcopter/react-mosaic","owner":"nomcopter","description":"A React tiling window manager","archived":false,"fork":false,"pushed_at":"2024-12-20T16:36:44.000Z","size":18309,"stargazers_count":4569,"open_issues_count":30,"forks_count":232,"subscribers_count":40,"default_branch":"master","last_synced_at":"2025-05-14T22:03:45.261Z","etag":null,"topics":["react","tiling-window-manager","typescript","window-manager"],"latest_commit_sha":null,"homepage":"https://nomcopter.github.io/react-mosaic/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nomcopter.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["nomcopter"]}},"created_at":"2017-03-23T15:51:26.000Z","updated_at":"2025-05-13T08:18:42.000Z","dependencies_parsed_at":"2023-02-08T14:16:27.639Z","dependency_job_id":"2dfafab4-2342-4b44-a2a7-8d7f92228970","html_url":"https://github.com/nomcopter/react-mosaic","commit_stats":{"total_commits":212,"total_committers":21,"mean_commits":"10.095238095238095","dds":0.6462264150943396,"last_synced_commit":"2621eb67377c42d64a291f63c9e87631962a970f"},"previous_names":[],"tags_count":48,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nomcopter%2Freact-mosaic","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nomcopter%2Freact-mosaic/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nomcopter%2Freact-mosaic/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nomcopter%2Freact-mosaic/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nomcopter","download_url":"https://codeload.github.com/nomcopter/react-mosaic/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254235687,"owners_count":22036962,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["react","tiling-window-manager","typescript","window-manager"],"created_at":"2024-07-31T15:01:52.553Z","updated_at":"2025-05-14T22:05:25.118Z","avatar_url":"https://github.com/nomcopter.png","language":"TypeScript","funding_links":["https://github.com/sponsors/nomcopter"],"categories":["TypeScript","Uncategorized","Libraries"],"sub_categories":["Uncategorized","JavaScript"],"readme":"# react-mosaic\n\n[![CircleCI](https://circleci.com/gh/nomcopter/react-mosaic/tree/master.svg?style=svg)](https://circleci.com/gh/nomcopter/react-mosaic/tree/master)\n[![npm](https://img.shields.io/npm/v/react-mosaic-component.svg)](https://www.npmjs.com/package/react-mosaic-component)\n\nreact-mosaic is a full-featured React Tiling Window Manager meant to give a user complete control over their workspace.\nIt provides a simple and flexible API to tile arbitrarily complex react components across a user's view.\nreact-mosaic is written in TypeScript and provides typings but can be used in JavaScript as well.\n\nThe best way to see it is a simple [**Demo**](https://nomcopter.github.io/react-mosaic/).\n\n#### Screencast\n\n[![screencast demo](./screencast.gif)](./screencast.gif)\n\n## Usage\n\nThe core of react-mosaic's operations revolve around the simple binary tree [specified by `MosaicNode\u003cT\u003e`](./src/types.ts#L12).\n[`T`](./src/types.ts#L7) is the type of the leaves of the tree and is a `string` or a `number` that can be resolved to a `JSX.Element` for display.\n\n### Installation\n\n1.  `yarn add react-mosaic-component`\n1.  Make sure `react-mosaic-component.css` is included on your page.\n1.  Import the `Mosaic` component and use it in your app.\n1.  (Optional) Install Blueprint\n\n### Blueprint Theme\n\nWithout a theme, Mosaic only loads the styles necessary for it to function -\nmaking it easier for the consumer to style it to match their own app.\n\nBy default, Mosaic renders with the `mosaic-blueprint-theme` class.\nThis uses the excellent [Blueprint](http://blueprintjs.com/) React UI Toolkit to provide a good starting state.\nIt is recommended to at least start developing with this theme.\nTo use it install Blueprint `yarn add @blueprintjs/core @blueprintjs/icons` and add their CSS to your page.\nDon't forget to set `blueprintNamespace` in `Mosaic` to the correct value for the version of Blueprint you are using.\n\nSee [blueprint-theme.less](./styles/blueprint-theme.less) for an example of creating a theme.\n\n#### Blueprint Dark Theme\n\nMosaic supports the Blueprint Dark Theme out of the box when rendered with the `mosaic-blueprint-theme bp3-dark` class.\n\n### Examples\n\n#### Simple Tiling\n\n##### app.css\n\n```css\nhtml,\nbody,\n#app {\n  height: 100%;\n  width: 100%;\n  margin: 0;\n}\n```\n\n##### App.tsx\n\n```tsx\nimport { Mosaic } from 'react-mosaic-component';\n\nimport 'react-mosaic-component/react-mosaic-component.css';\nimport '@blueprintjs/core/lib/css/blueprint.css';\nimport '@blueprintjs/icons/lib/css/blueprint-icons.css';\n\nimport './app.css';\n\nconst ELEMENT_MAP: { [viewId: string]: JSX.Element } = {\n  a: \u003cdiv\u003eLeft Window\u003c/div\u003e,\n  b: \u003cdiv\u003eTop Right Window\u003c/div\u003e,\n  c: \u003cdiv\u003eBottom Right Window\u003c/div\u003e,\n};\n\nexport const app = (\n  \u003cdiv id=\"app\"\u003e\n    \u003cMosaic\u003cstring\u003e\n      renderTile={(id) =\u003e ELEMENT_MAP[id]}\n      initialValue={{\n        direction: 'row',\n        first: 'a',\n        second: {\n          direction: 'column',\n          first: 'b',\n          second: 'c',\n        },\n        splitPercentage: 40,\n      }}\n    /\u003e\n  \u003c/div\u003e\n);\n```\n\n`renderTile` is a stateless lookup function to convert `T` into a displayable `JSX.Element`.\nBy default `T` is `string` (so to render one element `initialValue=\"ID\"` works).\n`T`s must be unique within an instance of `Mosaic`, they are used as keys for [React list management](https://reactjs.org/docs/lists-and-keys.html).\n`initialValue` is a [`MosaicNode\u003cT\u003e`](./src/types.ts#L12).\n\nThe user can resize these panes but there is no other advanced functionality.\nThis example renders a simple tiled interface with one element on the left half, and two stacked elements on the right half.\nThe user can resize these panes but there is no other advanced functionality.\n\n#### Drag, Drop, and other advanced functionality with `MosaicWindow`\n\n`MosaicWindow` is a component that renders a toolbar and controls around its children for a tile as well as providing full featured drag and drop functionality.\n\n```tsx\nexport type ViewId = 'a' | 'b' | 'c' | 'new';\n\nconst TITLE_MAP: Record\u003cViewId, string\u003e = {\n  a: 'Left Window',\n  b: 'Top Right Window',\n  c: 'Bottom Right Window',\n  new: 'New Window',\n};\n\nexport const app = (\n  \u003cMosaic\u003cViewId\u003e\n    renderTile={(id, path) =\u003e (\n      \u003cMosaicWindow\u003cViewId\u003e path={path} createNode={() =\u003e 'new'} title={TITLE_MAP[id]}\u003e\n        \u003ch1\u003e{TITLE_MAP[id]}\u003c/h1\u003e\n      \u003c/MosaicWindow\u003e\n    )}\n    initialValue={{\n      direction: 'row',\n      first: 'a',\n      second: {\n        direction: 'column',\n        first: 'b',\n        second: 'c',\n      },\n    }}\n  /\u003e\n);\n```\n\nHere `T` is a `ViewId` that can be used to look elements up in `TITLE_MAP`.\nThis allows for easy view state specification and serialization.\nThis will render a view that looks very similar to the previous examples, but now each of the windows will have a toolbar with buttons.\nThese toolbars can be dragged around by a user to rearrange their workspace.\n\n`MosaicWindow` API docs [here](#mosaicwindow).\n\n#### Controlled vs. Uncontrolled\n\nMosaic views have two modes, similar to `React.DOM` input elements:\n\n- Controlled, where the consumer manages Mosaic's state through callbacks.\n  Using this API, the consumer can perform any operation upon the tree to change the the view as desired.\n- Uncontrolled, where Mosaic manages all of its state internally.\n\nSee [Controlled Components](https://facebook.github.io/react/docs/forms.html#controlled-components).\n\nAll of the previous examples show use of Mosaic in an Uncontrolled fashion.\n\n#### Example Application\n\nSee [ExampleApp](demo/ExampleApp.tsx) (the application used in the [Demo](https://nomcopter.github.io/react-mosaic/))\nfor a more interesting example that shows the usage of Mosaic as a controlled component and modifications of the tree structure.\n\n## API\n\n#### Mosaic Props\n\n```typescript\nexport interface MosaicBaseProps\u003cT extends MosaicKey\u003e {\n  /**\n   * Lookup function to convert `T` to a displayable `JSX.Element`\n   */\n  renderTile: TileRenderer\u003cT\u003e;\n  /**\n   * Called when a user initiates any change to the tree (removing, adding, moving, resizing, etc.)\n   */\n  onChange?: (newNode: MosaicNode\u003cT\u003e | null) =\u003e void;\n  /**\n   * Called when a user completes a change (fires like above except for the interpolation during resizing)\n   */\n  onRelease?: (newNode: MosaicNode\u003cT\u003e | null) =\u003e void;\n  /**\n   * Additional classes to affix to the root element\n   * Default: 'mosaic-blueprint-theme'\n   */\n  className?: string;\n  /**\n   * Options that control resizing\n   * @see: [[ResizeOptions]]\n   */\n  resize?: ResizeOptions;\n  /**\n   * View to display when the current value is `null`\n   * default: Simple NonIdealState view\n   */\n  zeroStateView?: JSX.Element;\n  /**\n   * Override the mosaicId passed to `react-dnd` to control how drag and drop works with other components\n   * Note: does not support updating after instantiation\n   * default: Random UUID\n   */\n  mosaicId?: string;\n  /**\n   * Make it possible to use different versions of Blueprint with `mosaic-blueprint-theme`\n   * Note: does not support updating after instantiation\n   * default: 'bp3'\n   */\n  blueprintNamespace?: string;\n  /**\n   * Override the react-dnd provider to allow applications to inject an existing drag and drop context\n   */\n  dragAndDropManager?: DragDropManager | undefined;\n}\n\nexport interface MosaicControlledProps\u003cT extends MosaicKey\u003e extends MosaicBaseProps\u003cT\u003e {\n  /**\n   * The tree to render\n   */\n  value: MosaicNode\u003cT\u003e | null;\n  onChange: (newNode: MosaicNode\u003cT\u003e | null) =\u003e void;\n}\n\nexport interface MosaicUncontrolledProps\u003cT extends MosaicKey\u003e extends MosaicBaseProps\u003cT\u003e {\n  /**\n   * The initial tree to render, can be modified by the user\n   */\n  initialValue: MosaicNode\u003cT\u003e | null;\n}\n\nexport type MosaicProps\u003cT extends MosaicKey\u003e = MosaicControlledProps\u003cT\u003e | MosaicUncontrolledProps\u003cT\u003e;\n```\n\n#### `MosaicWindow`\n\n```typescript\nexport interface MosaicWindowProps\u003cT extends MosaicKey\u003e {\n  title: string;\n  /**\n   * Current path to this window, provided by `renderTile`\n   */\n  path: MosaicBranch[];\n  className?: string;\n  /**\n   * Controls in the top right of the toolbar\n   * default: [Replace, Split, Expand, Remove] if createNode is defined and [Expand, Remove] otherwise\n   */\n  toolbarControls?: React.ReactNode;\n  /**\n   * Additional controls that will be hidden in a drawer beneath the toolbar.\n   * default: []\n   */\n  additionalControls?: React.ReactNode;\n  /**\n   * Label for the button that expands the drawer\n   */\n  additionalControlButtonText?: string;\n  /**\n   * A callback that triggers when a user toggles the additional controls\n   */\n  onAdditionalControlsToggle?: (toggle: boolean) =\u003e void;\n  /**\n   * Disables the overlay that blocks interaction with the window when additional controls are open\n   */\n  disableAdditionalControlsOverlay?: boolean;\n  /**\n   * Whether or not a user should be able to drag windows around\n   */\n  draggable?: boolean;\n  /**\n   * Method called when a new node is required (such as the Split or Replace buttons)\n   */\n  createNode?: CreateNode\u003cT\u003e;\n  /**\n   * Optional method to override the displayed preview when a user drags a window\n   */\n  renderPreview?: (props: MosaicWindowProps\u003cT\u003e) =\u003e JSX.Element;\n  /**\n   * Optional method to override the displayed toolbar\n   */\n  renderToolbar?: ((props: MosaicWindowProps\u003cT\u003e, draggable: boolean | undefined) =\u003e JSX.Element) | null;\n  /**\n   * Optional listener for when the user begins dragging the window\n   */\n  onDragStart?: () =\u003e void;\n  /**\n   * Optional listener for when the user finishes dragging a window.\n   */\n  onDragEnd?: (type: 'drop' | 'reset') =\u003e void;\n}\n```\n\nThe default controls rendered by `MosaicWindow` can be accessed from [`defaultToolbarControls`](./src/buttons/defaultToolbarControls.tsx)\n\n### Advanced API\n\nThe above API is good for most consumers, however Mosaic provides functionality on the [Context](https://facebook.github.io/react/docs/context.html) of its children that make it easier to alter the view state.\nAll leaves rendered by Mosaic will have the following available on React context.\nThese are used extensively by `MosaicWindow`.\n\n```typescript\n/**\n * Valid node types\n * @see React.Key\n */\nexport type MosaicKey = string | number;\nexport type MosaicBranch = 'first' | 'second';\nexport type MosaicPath = MosaicBranch[];\n\n/**\n * Context provided to everything within Mosaic\n */\nexport interface MosaicContext\u003cT extends MosaicKey\u003e {\n  mosaicActions: MosaicRootActions\u003cT\u003e;\n  mosaicId: string;\n}\n\nexport interface MosaicRootActions\u003cT extends MosaicKey\u003e {\n  /**\n   * Increases the size of this node and bubbles up the tree\n   * @param path Path to node to expand\n   * @param percentage Every node in the path up to root will be expanded to this percentage\n   */\n  expand: (path: MosaicPath, percentage?: number) =\u003e void;\n  /**\n   * Remove the node at `path`\n   * @param path\n   */\n  remove: (path: MosaicPath) =\u003e void;\n  /**\n   * Hide the node at `path` but keep it in the DOM. Used in Drag and Drop\n   * @param path\n   */\n  hide: (path: MosaicPath) =\u003e void;\n  /**\n   * Replace currentNode at `path` with `node`\n   * @param path\n   * @param node\n   */\n  replaceWith: (path: MosaicPath, node: MosaicNode\u003cT\u003e) =\u003e void;\n  /**\n   * Atomically applies all updates to the current tree\n   * @param updates\n   * @param suppressOnRelease (default: false)\n   */\n  updateTree: (updates: MosaicUpdate\u003cT\u003e[], suppressOnRelease?: boolean) =\u003e void;\n  /**\n   * Returns the root of this Mosaic instance\n   */\n  getRoot: () =\u003e MosaicNode\u003cT\u003e | null;\n}\n```\n\nChildren (and toolbar elements) within `MosaicWindow` are passed the following additional functions on context.\n\n```typescript\nexport interface MosaicWindowContext\u003cT extends MosaicKey\u003e extends MosaicContext\u003cT\u003e {\n  mosaicWindowActions: MosaicWindowActions;\n}\n\nexport interface MosaicWindowActions {\n  /**\n   * Fails if no `createNode()` is defined\n   * Creates a new node and splits the current node.\n   * The current node becomes the `first` and the new node the `second` of the result.\n   * `direction` is chosen by querying the DOM and splitting along the longer axis\n   */\n  split: () =\u003e Promise\u003cvoid\u003e;\n  /**\n   * Fails if no `createNode()` is defined\n   * Convenience function to call `createNode()` and replace the current node with it.\n   */\n  replaceWithNew: () =\u003e Promise\u003cvoid\u003e;\n  /**\n   * Sets the open state for the tray that holds additional controls.\n   * Pass 'toggle' to invert the current state.\n   */\n  setAdditionalControlsOpen: (open: boolean | 'toggle') =\u003e void;\n  /**\n   * Returns the path to this window\n   */\n  getPath: () =\u003e MosaicPath;\n  /**\n   * Enables connecting a different drag source besides the react-mosaic toolbar\n   */\n  connectDragSource: (connectedElements: React.ReactElement\u003cany\u003e) =\u003e React.ReactElement\u003cany\u003e;\n}\n```\n\nTo access the functions simply use the [`MosaicContext`](./src/contextTypes.ts#L90)\nor [`MosaicWindowContext`](./src/contextTypes.ts#L91) [context consumers](https://reactjs.org/docs/context.html#contextconsumer).\n\n### Mutating the Tree\n\nUtilities are provided for working with the MosaicNode tree in [`mosaicUtilities`](src/util/mosaicUtilities.ts) and\n[`mosaicUpdates`](src/util/mosaicUpdates.ts)\n\n#### MosaicUpdate\n\n[`MosaicUpdateSpec`](./src/types.ts#L33) is an argument meant to be passed to [`immutability-helper`](https://github.com/kolodny/immutability-helper)\nto modify the state at a path.\n[`mosaicUpdates`](src/util/mosaicUpdates.ts) has examples.\n\n## Upgrade Considerations / Changelog\n\nSee [Releases](https://github.com/nomcopter/react-mosaic/releases)\n\n## License\n\nCopyright 2019 Kevin Verdieck, originally developed at Palantir Technologies, Inc.\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnomcopter%2Freact-mosaic","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnomcopter%2Freact-mosaic","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnomcopter%2Freact-mosaic/lists"}