{"id":24938254,"url":"https://github.com/rickonono3/react-winbox","last_synced_at":"2025-04-06T23:16:53.904Z","repository":{"id":37044359,"uuid":"482614519","full_name":"RickoNoNo3/react-winbox","owner":"RickoNoNo3","description":"The newest React component for WinBox.js. A window manager for React.","archived":false,"fork":false,"pushed_at":"2023-06-18T13:47:47.000Z","size":512,"stargazers_count":148,"open_issues_count":1,"forks_count":21,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-30T22:09:57.094Z","etag":null,"topics":["react","react-component","winbox","winbox-js"],"latest_commit_sha":null,"homepage":"https://react-winbox.vercel.app/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RickoNoNo3.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"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}},"created_at":"2022-04-17T19:26:21.000Z","updated_at":"2025-01-25T18:28:01.000Z","dependencies_parsed_at":"2024-10-23T00:38:01.918Z","dependency_job_id":null,"html_url":"https://github.com/RickoNoNo3/react-winbox","commit_stats":{"total_commits":109,"total_committers":3,"mean_commits":"36.333333333333336","dds":"0.39449541284403666","last_synced_commit":"aa36668a59ad629d9e23c6c3830978e881d9b104"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RickoNoNo3%2Freact-winbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RickoNoNo3%2Freact-winbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RickoNoNo3%2Freact-winbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RickoNoNo3%2Freact-winbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RickoNoNo3","download_url":"https://codeload.github.com/RickoNoNo3/react-winbox/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247563935,"owners_count":20958971,"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","react-component","winbox","winbox-js"],"created_at":"2025-02-02T17:46:20.322Z","updated_at":"2025-04-06T23:16:53.887Z","avatar_url":"https://github.com/RickoNoNo3.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# React-WinBox\n\n\u003ca target=\"_blank\" href=\"https://www.npmjs.com/package/react-winbox\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/react-winbox?style=flat-square\"\u003e\u003c/a\u003e\n\u003c!--![GitHub Workflow Status](https://img.shields.io/github/workflow/status/rickonono3/react-winbox/Node.js%20CI/main?style=flat-square)--\u003e\n\nA React controlled component for [WinBox.js](https://github.com/nextapps-de/winbox), with full Reactful props and state. Includes all configurations of WinBox.js by using React component props.\n\n**Full type declaration for both JavaScript and TypeScript.**\n\n## Play the [Demo](https://react-winbox.vercel.app)\n\ndemo: \u003chttps://react-winbox.vercel.app\u003e\n\n-----\n\n![demo screenshot](https://github.com/RickoNoNo3/react-winbox/blob/main/demo.jpg)\n\n## Install\n\n```bash\nnpm install --save react-winbox\n# OR\nyarn add react-winbox\n```\n\n## Usage\n\n### Help for different situations\n\n- [Use in Next.js](#use-in-next)\n- [Upgrade from versions \u003c=1.4](#upgrade)\n\n### Examples\n\n\u003e Ensure the document body has an initial non-zero height, e.g. `100vh`.\n\n```jsx\nimport 'winbox/dist/css/winbox.min.css'; // required\nimport 'winbox/dist/css/themes/modern.min.css'; // optional\nimport 'winbox/dist/css/themes/white.min.css'; // optional\nimport WinBox from 'react-winbox';\n\n\u003cWinBox\n  width={this.state.boxWidth ?? 500}\n  height={300}\n  x=\"center\"\n  y={30}\n  noClose={this.state.inEditing}\n\u003e\n  \u003cdiv\u003e\n    \u003ch1\u003eHello, WinBox!\u003c/h1\u003e\n    \u003cMyComponent myProps={1} onChange={this.handleChange}/\u003e\n  \u003c/div\u003e\n\u003c/WinBox\u003e\n```\n\nOr you can do more one step, to make a genuine 'windows manager', just like:\n\n```tsx\n// ...\n// some code to maintain a list of necessary windows info...\n// ...\nconst [windows, setWindows] = useState([]);\n\nconst handleClose = (force, id) =\u003e {\n  let state = [...windows];\n  const index = state.findIndex(info =\u003e info.id === id);\n  if (index === -1) return\n  if (state[index].onclose \u0026\u0026 state[index].onclose(force)) return true;                       \n  // window-specific onclose, returns true if it does not need the default close process.\n  state.splice(index, 1);\n  setTimeout(() =\u003e setWindows(state)); // to change winbox showing state while `onclose`, MUST wrap it within `setTimeout`\n};\n\nreturn (\n  \u003c\u003e\n    {windows.map(info =\u003e (\n      \u003cWinBox \n        key={info.id} \n        id={info.id} \n        onClose={(force) =\u003e handleClose(force, info.id)}\n        {...info.neededProps} // assign any props you want to WinBox\n      \u003e\n        \u003cdiv\u003eSome children\u003c/div\u003e\n      \u003c/WinBox\u003e\n    ))}\n  \u003c/\u003e\n);\n```\n\n## Notice\n\n- To use WinBox, ensure the document body has an initial non-zero height, e.g. 100vh.\n- To open a winbox, just create it in your virtual DOM, that's enough.\n- To close a winbox, just do not render it. It's safe.\n- `onclose` is called BEFORE the winbox goes to close process. It is easy to block a closing for some unsaved data or giving a confirmation to user to close (see the doc to get more info). However, if you do not want to block the closing, but want to destroy the React WinBox component, be sure to wrap destroying actions within `setTimeout` so that they occur after the winbox.js DOM is truly closed, e.g. `setTimeout(() =\u003e setShowWindow(false))`.\n- To change some properties of the winbox DOM, just change the component's properties. The properties need [official methods](https://github.com/nextapps-de/winbox#overview) support. We suggest that all states you want to control of the winbox should be listened for changes and keep controlled, such as `width` state with `onResize` callback. But if you do not have such listeners, you can call the `forceUpdate` method from refs to keep the winbox status in control as well.\n- If you have to operate the pure WinBox.js object manually, you can find a `winBoxObj` in the component ref. It's needed only when you want to call `mount()` method.\n\n## Props and Methods\n\n### See the official document for [WinBox.js](https://github.com/nextapps-de/winbox)\n\n### Props\n\n\u003e most props are one-to-one corresponding to the params of WinBox.js.\n\n```ts\ntype WinBoxPropType = {\n  title?: string\n  /** \n   * Icon supports both native image urls and React package resources:\n   *\n   * Example:\n   * ```\n   * import icon from './icon.jpg';\n   * \n   * \u003cWinBox icon={icon} {...otherProps} /\u003e\n   * ```\n   */\n  icon?: string\n  id?: string\n  children?: ReactElement | ReactElement[] | null\n  url?: string // When you use this, the children elements will be ignored.\n\n  noAnimation?: boolean,\n  noShadow?: boolean,\n  noHeader?: boolean,\n  noMin?: boolean,\n  noMax?: boolean,\n  noFull?: boolean,\n  noClose?: boolean,\n  noResize?: boolean,\n  noMove?: boolean,\n  modal?: boolean,\n  hide?: boolean,\n\n  index?: number,\n  border?: number,\n  background?: string,\n\n  max?: boolean,\n  min?: boolean,\n  fullscreen?: boolean,\n\n  x?: string | number | 'center' | 'right',\n  y?: string | number | 'center' | 'bottom',\n  top?: string | number,\n  bottom?: string | number,\n  left?: string | number,\n  right?: string | number,\n  height?: string | number,\n  width?: string | number,\n\n  /**\n   * This callback is called BEFORE the winbox goes to close process. So if you want to destroy the React WinBox component while it is triggered, be sure to wrap destroying actions within `setTimeout` so that they occur after the winbox.js DOM is truly closed，e.g. `setTimeout(() =\u003e setState({showWindow: false}))`\n   *\n   * see the following document for more detail about the argument and the return value.\n   * @see https://github.com/nextapps-de/winbox\n   * @param force Whether you should not abort the winbox to close. If this is true, you MUST return false, or some problems will happen.\n   * @return noDefaultClose - true if the winbox does not need the default close process, for example, when it needs a confirmation to close instead of being closed suddenly.\n   */\n  onClose?: (force: boolean) =\u003e boolean | undefined | void,\n  onMove?: (x: number, y: number) =\u003e any,\n  onResize?: (width: number, height: number) =\u003e any,\n  onBlur?: () =\u003e any,\n  onFocus?: () =\u003e any,\n\n  /** Used for themeing. The `no-xxx` classes that winbox.js already appointed can not assign here, use special props instead, e.g. class `no-resize` to prop `noResize={true}` */\n  className?: string | number,\n\n  minWidth?: number | string,\n  minHeight?: number | string,\n  maxWidth?: number | string,\n  maxHeight?: number | string,\n\n  onCreate?: (options: any) =\u003e any,\n  onFullscreen?: () =\u003e any,\n  onMinimize?: () =\u003e any,\n  onMaximize?: () =\u003e any,\n  onRestore?: () =\u003e any,\n  onHide?: () =\u003e any,\n  onShow?: () =\u003e any,\n\n  /**\n   * an array of WinBoxControlInfo\n   * @see https://github.com/nextapps-de/winbox#custom-controls\n   */\n  customControls?: WinBoxControlInfo[],\n}\n\ntype WinBoxControlInfo = {\n  /** Index to jump into native controls. If no index assigned, custum controls will be arranged side-by-side automatically on the left of native controls*/\n  index?: number\n  /** a name to identify the button, can also style it by using css, may starts with `wb-` */\n  class: string\n  /** an image resource same like icon prop */\n  image: string\n  click?: () =\u003e void,\n}\n```\n\n### Methods\n\n\u003e use React Ref to call these methods\n\n```ts\nforceUpdate (callback?: () =\u003e void) =\u003e void\n\nfocus () =\u003e void\n\nblur () =\u003e void\n\ngetId () =\u003e string | undefined\n\ngetIndex () =\u003e number | undefined\n\ngetPosition () =\u003e { x: number, y: number } | undefined\n\ngetSize () =\u003e { width: number, height: number } | undefined\n\ngetSizeLimit () =\u003e { minWidth: number, minHeight: number, maxWidth: number, maxHeight: number } | undefined\n\ngetViewportBoundary () =\u003e { top: number, right: number, bottom: number, left: number} | undefined\n\nisFocused () =\u003e boolean\n\nisHidden () =\u003e boolean\n\nisMax () =\u003e boolean\n\nisMin () =\u003e boolean\n\nisFullscreen () =\u003e boolean\n\nisClosed () =\u003e boolean // REACT ONLY. Returns true if the winbox DOM element has been removed but the React component not yet.\n\n// below methods are not suggested, as they are not state-controlled and have alternative props.\nminimize () =\u003e void // prop `min`\nmaximize () =\u003e void // prop `max`\nfullscreen () =\u003e void // prop `fullscreen`\nrestore () =\u003e void // prop `min`/`max`/`fullscreen`\nhide () =\u003e void // prop `hide`\nshow () =\u003e void // prop `hide`\n```\n\n\u003e Thanks for your reading. If any questions or problems, feel free to issue them.\n\n-----\n\n# Extra Helps\n## Use in Next\nTo use `react-winbox` in Next.js, there are some special steps:\n1. install `react-winbox` (must \u003e= v1.5.0) into your project.\n2. ([Source](https://github.com/RickoNoNo3/react-winbox/issues/10#issuecomment-1348653226)) install `next-transpile-modules`, and change the `next.config.js` to:  \n```js\nconst withTM = require('next-transpile-modules')([\n  'react-winbox',\n]);\nmodule.exports = withTM({\n  // additional webpack configurations\n});\n```\n3. in `_app.js`:  \n```js\nimport 'winbox/dist/css/winbox.min.css';\nimport 'winbox/dist/css/themes/modern.min.css'; // optional\nimport 'winbox/dist/css/themes/white.min.css'; // optional\n```\n4. in files you want to use `react-winbox`:  \n```jsx\n//import WinBox from 'react-winbox'; // do not use this, use below:\nimport dynamic from 'next/dynamic';\nconst WinBox = dynamic(() =\u003e import('react-winbox'), {ssr: false});\n```\n\nAll is OK, start coding now!\n\n## Upgrade\nFor old versions upgrading to v1.5.x, these things deserve attention:\n- **All old versions have bugs in React 18+, but v1.5+ do not.**\n- CSS files need to be imported manually. See [example 1](#examples).\n- All props are camel-cased, use `onClose` instead of `onclose`.\n- `splitscreen` has been removed, some props and methods were added.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frickonono3%2Freact-winbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frickonono3%2Freact-winbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frickonono3%2Freact-winbox/lists"}