{"id":13565685,"url":"https://github.com/pixijs/pixi-react","last_synced_at":"2025-05-14T01:03:04.542Z","repository":{"id":37927630,"uuid":"125637394","full_name":"pixijs/pixi-react","owner":"pixijs","description":"Write PIXI apps using React declarative style","archived":false,"fork":false,"pushed_at":"2024-09-30T18:53:01.000Z","size":17019,"stargazers_count":2391,"open_issues_count":51,"forks_count":179,"subscribers_count":23,"default_branch":"main","last_synced_at":"2024-10-29T15:06:06.108Z","etag":null,"topics":["pixi","react","react-fiber","renderer"],"latest_commit_sha":null,"homepage":"https://pixijs.io/pixi-react/","language":"JavaScript","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/pixijs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","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},"funding":{"open_collective":"pixijs"}},"created_at":"2018-03-17T14:29:23.000Z","updated_at":"2024-10-28T19:39:43.000Z","dependencies_parsed_at":"2024-01-13T07:22:52.645Z","dependency_job_id":"8350b308-3655-47f6-92e5-853b94365590","html_url":"https://github.com/pixijs/pixi-react","commit_stats":{"total_commits":770,"total_committers":59,"mean_commits":13.05084745762712,"dds":0.2298701298701299,"last_synced_commit":"b85a7af00f7b4a8ffc7edb3d958f7afafd255fd7"},"previous_names":["inlet/react-pixi"],"tags_count":174,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pixijs%2Fpixi-react","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pixijs%2Fpixi-react/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pixijs%2Fpixi-react/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pixijs%2Fpixi-react/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pixijs","download_url":"https://codeload.github.com/pixijs/pixi-react/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247353727,"owners_count":20925328,"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":["pixi","react","react-fiber","renderer"],"created_at":"2024-08-01T13:01:52.947Z","updated_at":"2025-04-08T22:19:09.738Z","avatar_url":"https://github.com/pixijs.png","language":"JavaScript","funding_links":["https://opencollective.com/pixijs"],"categories":["TypeScript"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./.github/react.svg\" alt=\"pixi-react\" width=\"310\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003e\n  \u003ccode\u003e@pixi/react\u003c/code\u003e\n\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eSimply the best way to write PixiJS applications in React\u003c/strong\u003e\n  \u003cbr /\u003e\n  \u003csub\u003eWrite \u003ca href=\"http://www.pixijs.com/\"\u003ePixiJS\u003c/a\u003e applications using React declarative style 👌\u003c/sub\u003e\n\u003c/p\u003e\n\n\u003cbr /\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/github/v/release/pixijs/pixi-react\" alt=\"release\" /\u003e\n  \u003cimg src=\"https://img.shields.io/npm/dm/@pixi/react\" alt=\"downloads\" /\u003e\n  \u003cimg src=\"https://img.shields.io/circleci/project/github/pixijs/pixi-react/master.svg\" alt=\"ci tests\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/license-MIT-green.svg\" alt=\"license\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/react-v18.0.0-ff69b4.svg\" alt=\"react version\" /\u003e\n\u003c/p\u003e\n\n\u003cbr /\u003e\n\n`@pixi/react` is an open-source, production-ready library to render high performant PixiJS applications in React.\n\n## Features\n\n- React v19 support\n- PixiJS v8 support\n\n## Getting Started\n\n### Quick Start\n\nIf you want to start a new React project from scratch then we recommend [Create React App](https://github.com/facebook/create-react-app), but `@pixi/react` should work with any React application (Remix, Next.js, etc).\nTo add `@pixi/react` to an existing React application, just install the dependencies:\n\n#### Install Dependencies\n```bash\nnpm install pixi.js@^8.2.6 @pixi/react\n```\n\n#### Pixie React Usage\n```jsx\nimport {\n  Application,\n  extend,\n} from '@pixi/react'\nimport {\n  Container,\n  Graphics,\n} from 'pixi.js'\nimport { useCallback } from 'react'\n\nextend({\n  Container,\n  Graphics,\n})\n\nconst MyComponent = () =\u003e {\n  const drawCallback = useCallback(graphics =\u003e {\n    graphics.clear()\n    graphics.setFillStyle({ color: 'red' })\n    graphics.rect(0, 0, 100, 100)\n    graphics.fill()\n  }, [])\n\n  return (\n    \u003cApplication\u003e\n      \u003cpixiContainer x={100} y={100}\u003e\n        \u003cpixiGraphics draw={drawCallback} /\u003e\n      \u003c/pixiContainer\u003e\n    \u003c/Application\u003e\n  )\n}\n```\n\n## Docs\n\n### `extend`\n\nOne of the most important concepts to understand with v8 is `extend`. Normally `@pixi/react` would have to import all pf Pixi.js to be able to provide the full library as JSX components. Instead, we use an internal catalogue of components populated by the `extend` API. This allows you to define exactly which parts of Pixi.js you want to import, keeping your bundle sizes small.\n\nTo allow `@pixi/react` to use a Pixi.js component, pass it to the `extend` API:\n\n```jsx\nimport { Container } from 'pixi.js'\nimport { extend } from '@pixi/react'\n\nextend({ Container })\n\nconst MyComponent = () =\u003e (\n  \u003cpixiContainer /\u003e\n)\n```\n\n\u003e [!CAUTION]\n\u003e Attempting to use components that haven't been passed to the `extend` API **will result in errors**.\n\n### Components\n\n#### `\u003cApplication\u003e`\n\nThe `\u003cApplication\u003e` component is used to wrap your `@pixi/react` app. The `\u003cApplication\u003e` component can take [all props that can be set](https://pixijs.download/release/docs/app.ApplicationOptions.html) on [`PIXI.Application`](https://pixijs.download/release/docs/app.Application.html).\n\n##### Example Usage\n\n```jsx\nimport { Application } from '@pixi/react'\n\nconst MyComponent = () =\u003e {\n  return (\n    \u003cApplication\n      autoStart\n      sharedTicker /\u003e\n  )\n}\n```\n\n###### `defaultTextStyle`\n\n`defaultTextStyle` is a convenience property. Whatever is passed will automatically be assigned to Pixi.js's [`TextStyle.defaultTextStyle`](https://pixijs.download/release/docs/text.TextStyle.html#defaultTextStyle).\n\n\u003e [!NOTE]\n\u003e This property **is not retroactive**. It will only apply to text components created after `defaultTextStyle` is set. Any text components created before setting `defaultTextStyle` will retain the base styles they had before `defaultTextStyle` was changed.\n\n###### `extensions`\n\n`extensions` is an array of extensions to be loaded. Adding and removing items from this array will automatically load/unload the extensions. The first time this is handled happens before the application is initialised. See Pixi.js's [`extensions`](https://pixijs.download/release/docs/extensions.html) documentation for more info on extensions.\n\n###### `resizeTo`\n\nThe `\u003cApplication\u003e` component supports the `resizeTo` property, with some additional functionality: it can accept any HTML element **or** it can take a React `ref` directly.\n\n```jsx\nimport { Application } from '@pixi/react'\nimport { useRef } from 'react'\nconst MyComponent = () =\u003e {\n  const parentRef = useRef(null)\n  return (\n    \u003cdiv ref={parentRef}\u003e\n      \u003cApplication resizeTo={parentRef} /\u003e\n    \u003c/div\u003e\n  )\n}\n```\n\n#### Pixi Components\n\nAll other components should be included in your IDE's intellisense/autocomplete once you've installed/imported `@pixi/react`. If it's exported from Pixi.js, it's supported as a component with the `pixi` prefix. Here's a selection of commonly used components:\n\n```jsx\n\u003cpixiContainer /\u003e\n\u003cpixiGraphics /\u003e\n\u003cpixiSprite /\u003e\n\u003cpixiAnimatedSprite /\u003e\n\u003cpixiText /\u003e\n\u003cpixiHtmlText /\u003e\n```\n\n##### `\u003cpixiGraphics\u003e`\n\nThe `pixiGraphics` component has a special `draw` property. `draw` takes a callback which receives the `Graphics` context, allowing drawing to happen on every tick.\n\n```jsx\nconst MyComponent = () =\u003e {\n  return (\n    \u003cpixiGraphics draw={graphics =\u003e {\n      graphics.clear()\n      graphics.setFillStyle({ color: 'red' })\n      graphics.rect(0, 0, 100, 100)\n      graphics.fill()\n    }} /\u003e\n  )\n}\n```\n\n#### Custom Components\n\n`@pixi/react` supports custom components via the `extend` API. For example, you can create a `\u003cviewport\u003e` component using the [`pixi-viewport`](https://github.com/davidfig/pixi-viewport) library:\n\n```jsx\nimport { extend } from '@pixi/react'\nimport { Viewport } from 'pixi-viewport'\n\nextend({ Viewport })\n\nconst MyComponent = () =\u003e {\n  \u003cviewport\u003e\n    \u003cpixiContainer /\u003e\n  \u003c/viewport\u003e\n}\n```\n\nThe `extend` API will teach `@pixi/react` about your components, but TypeScript won't know about them nor their props. If you're using Typescript, check out our [docs for Typescript Users](#for-typescript-users).\n\n### Hooks\n\n#### `useApplication`\n\n`useApplication` allows access to the parent `PIXI.Application` created by the `\u003cApplication\u003e` component. This hook _will not work_ outside of an `\u003cApplication\u003e` component. Additionally, the parent application is passed via [React Context](https://react.dev/reference/react/useContext). This means `useApplication` will only work appropriately in _child components_, and in the same component that creates the `\u003cApplication\u003e`.\n\nFor example, the following example `useApplication` **will not** be able to access the parent application:\n\n```jsx\nimport {\n  Application,\n  useApplication,\n} from '@pixi/react'\n\nconst ParentComponent = () =\u003e {\n  // This will cause an invariant violation.\n  const { app } = useApplication()\n\n  return (\n    \u003cApplication /\u003e\n  )\n}\n```\n\nHere's a working example where `useApplication` **will** be able to access the parent application:\n\n```jsx\nimport {\n  Application,\n  useApplication,\n} from '@pixi/react'\n\nconst ChildComponent = () =\u003e {\n  const { app } = useApplication()\n\n  console.log(app)\n\n  return (\n    \u003ccontainer /\u003e\n  )\n}\n\nconst ParentComponent = () =\u003e (\n  \u003cApplication\u003e\n    \u003cChildComponent /\u003e\n  \u003c/Application\u003e\n)\n```\n\n#### `useExtend`\n\n`useExtend` allows the `extend` API to be used as a React hook. Additionally, the `useExtend` hook is memoised, while the `extend` function is not.\n\n```jsx\nimport { Container } from 'pixi.js'\nimport { useExtend } from '@pixi/react'\n\nconst MyComponent = () =\u003e {\n  useExtend({ Container })\n\n  return (\n    \u003ccontainer /\u003e\n  )\n}\n```\n\n#### `useTick`\n\n`useTick` allows a callback to be attached to the [`Ticker`](https://pixijs.download/release/docs/ticker.Ticker.html) on the parent application.\n\n```jsx\nimport { useTick } from '@pixi/react'\n\nconst MyComponent = () =\u003e {\n  useTick(() =\u003e console.log('This will be logged on every tick'))\n}\n```\n\n`useTick` optionally takes an options object. This allows control of all [`ticker.add`](https://pixijs.download/release/docs/ticker.Ticker.html#add) options, as well as adding the `isEnabled` option. Setting `isEnabled` to `false` will cause the callback to be disabled until the argument is changed to true again.\n\n```jsx\nimport { useState } from 'react'\nimport { useTick } from '@pixi/react'\n\nconst MyComponent = () =\u003e {\n  const [isEnabled, setIsEnabled] = useState(false)\n\n  useTick(() =\u003e console.log('This will be logged on every tick as long as `isEnabled` is `true`'), isEnabled)\n\n  return (\n    \u003csprite onClick={setIsEnabled(previousState =\u003e !previousState)}\u003e\n  )\n}\n```\n\n\u003e [!CAUTION]\n\u003e The callback passed to `useTick` **is not memoised**. This can cause issues where your callback is being removed and added back to the ticker on every frame if you're mutating state in a component where `useTick` is using a non-memoised function. For example, this issue would affect the component below because we are mutating the state, causing the component to re-render constantly:\n\u003e ```jsx\n\u003e import { useState } from 'react'\n\u003e import { useTick } from '@pixi/react'\n\u003e\n\u003e const MyComponent = () =\u003e {\n\u003e   const [count, setCount] = useState(0)\n\u003e\n\u003e   useTick(() =\u003e setCount(previousCount =\u003e previousCount + 1))\n\u003e\n\u003e   return null\n\u003e }\n\u003e ```\n\u003e This issue can be solved by memoising the callback passed to `useTick`:\n\u003e ```jsx\n\u003e import {\n\u003e   useCallback,\n\u003e   useState,\n\u003e } from 'react'\n\u003e import { useTick } from '@pixi/react'\n\u003e\n\u003e const MyComponent = () =\u003e {\n\u003e   const [count, setCount] = useState(0)\n\u003e\n\u003e   const updateCount = useCallback(() =\u003e setCount(previousCount =\u003e previousCount + 1), [])\n\u003e\n\u003e   useTick(updateCount)\n\u003e }\n\u003e ```\n\n### For Typescript Users\n\n#### Custom Components\n\n`@pixi/react` already offers types for built-in components, but custom components need to be added to the library's type catalogue so it knows how to handle them. This can be achieved by adding your custom components to the `PixiElements` interface. Here's what it may look like to add the `viewport` component from our earlier `extend` example:\n\n```ts\n// global.d.ts\nimport { type PixiReactElementProps } from '@pixi/react'\nimport { type Viewport } from 'pixi-viewport'\n\ndeclare module '@pixi/react' {\n  interface PixiElements {\n    viewport: PixiReactElementProps\u003ctypeof Viewport\u003e;\n  }\n}\n```\n\nNow you'll be able to use your custom component in your project without any type errors!\n\n#### Unprefixed Elements\n\nIf you like to live life on the wild side, you can enable unprefixed Pixi elements (i.e. `\u003ccontainer\u003e` instead of `\u003cpixiContainer\u003e`) by adding the `UnprefixedPixiElements` interface to the `PixiElements` interface.\n\n```ts\n// global.d.ts\nimport { type UnprefixedPixiElements } from '@pixi/react'\n\ndeclare module '@pixi/react' {\n  interface PixiElements extends UnprefixedPixiElements {}\n}\n```\n\nThe prefixed and unprefixed elements have the same functionality, but we recommend sticking to the prefixed components to avoid collisions with other libraries that add intrinsic elements to JSX (such as [`react-dom`](https://www.npmjs.com/package/react-dom) and [`@react-three/fiber`](https://www.npmjs.com/package/@react-three/fiber)).\n\n\u003e [!IMPORTANT]\n\u003e Some components conflict with other libaries, such as `\u003csvg\u003e` in `react-dom` and `\u003ccolor\u003e` in `@react-three/fiber`. To address this the `pixi` prefixed elements are always available, even after injecting the unprefixed elements.\n\n\n#### Extending Built-in Components\n\nThe props for built-in components are available on the `PixiElements` type and can be used to extend the built-in types.\n\n```ts\nimport { type PixiElements } from '@pixi/react'\n\nexport type TilingSpriteProps = PixiElements['pixiTilingSprite'] \u0026 {\n  image?: string;\n  texture?: Texture;\n};\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpixijs%2Fpixi-react","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpixijs%2Fpixi-react","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpixijs%2Fpixi-react/lists"}