react-smoke v1.0.4

This library provides React components to create awesome 3D galleries. It supports rendering with solid colors, images, and videos, offering a wide range of possibilities for showcasing media in a 3D environment.

Play with the demo to see what you can do with this library.

npm install react-smoke three @react-three/fiber

or

yarn add react-smoke three @react-three/fiber

Peer Dependencies

This library is designed to work alongside @react-three/drei, and @react-three/fiber. These are listed as peer dependencies, meaning that it expects these packages to be present in your project:

• three.js: A JavaScript 3D library that creates and displays animated 3D computer graphics in a web browser.
• @react-three/fiber: A React renderer for three.js that brings declarative, reactive, and component-based patterns to 3D rendering.

As peer dependencies, they are not automatically installed when you install this library. You need to manually install them in your project, if not already present. This approach helps to avoid version conflicts and reduce bundle size.

Basic Usage

This renders a gallery with three items: a solid color, an image, and a video. The gallery is rendered in a canvas element using react-three-fiber.

Gallery

The Gallery component is the container for all items in the gallery. It is responsible for laying out the items in a 3D space. It also provides a number of properties that can be used to customize the gallery:

Properties

GalleryChildren

The GalleryChildren type is an array of GalleryItem objects. These objects can be one of the following types:

• SolidColorItem
• ImageItem
• VideoItem
• GalleryItem

ItemProps

interface ItemProps {
  width?: number;
  height?: number;
  radialSegments?: number;
  heightSegments?: number;
  innerRadiusPercent?: number;
}

The ItemProps type is used to customize the items in the gallery. The items are rendered using the GalleryItem components.

Properties

SolidColorItem

<SolidColorItem color="#ff0000" />

The SolidColorItem component is used to render a solid color in the gallery. It is responsible for rendering the item's geometry and material. It uses the SolidColorItemMaterial component to render the item's material.

Properties

ImageItem

<ImageItem src="https://picsum.photos/200/300" />

The ImageItem component is used to render an image in the gallery. It is responsible for rendering the item's geometry and material. It uses the ImageItemMaterial component to render the item's material.

Properties

VideoItem

<VideoItem src="./video.mp4" />

The VideoItem component is used to render a video in the gallery. It is responsible for rendering the item's geometry and material. It uses the VideoItemMaterial component to render the item's material.

Properties

Ground

The Ground component is used to render the ground in the gallery. It is responsible for rendering the ground's geometry and material. It uses the MeshReflectorMaterial component from @react-three/drei to render the ground's material.

GroundProp

interface GroundProps {
  width?: number;
  height?: number;
  reflectorMaterial?: {
    color?: string;
    roughness?: number;
    metalness?: number;
    resolution?: number;
    mixBlur?: number;
    mixStrength?: number;
    blur?: [number, number] | number;
    mirror?: number;
    minDepthThreshold?: number;
    maxDepthThreshold?: number;
    depthScale?: number;
    depthToBlurRatioBias?: number;
    distortionMap?: Texture;
    distortion?: number;
    mixContrast?: number;
    reflectorOffset?: number;
  };
  disableReflector?: boolean;
}

Properties

GalleryItem

type GalleryItemProps = PropsWithChildren<{
  material: GalleryItemMaterial;
}>;

The GalleryItem component is used to render an item in the gallery. It is responsible for rendering the item's geometry and material.

Properties

GalleryItemMaterial

interface GalleryItemMaterial {
  generate: () => Material | Material[];
}

The GalleryItemMaterial type is used to generate the three.js Material of a gallery item. There are built-in materials that can be used to render solid colors, images, and videos. You can also create your own custom materials.

Built-in Materials

GalleryScene

<GalleryScene>
  <Gallery>
    <SolidColorItem color="#ff0000" />
    <ImageItem src="https://picsum.photos/200/300" />
    <VideoItem
      src="http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4"
      crossOrigin="anonymous"
    />
  </Gallery>
</GalleryScene>

The GalleryScene component is used to render the gallery in a canvas element using react-three-fiber. It is responsible for setting up the scene, camera, and lighting.

GallerySceneProps

type GallerySceneProps = Omit<CanvasProps, "children"> & {
  children: GallerySceneChildren;
  backgroundColor?: string;
  fog?: {
    color?: string;
    near?: number;
    far?: number;
  };
  orbitControls?: OrbitControlsProps;
  disableControls?: boolean;
  disableFog?: boolean;
  disableEnvironment?: boolean;
  environment?: EnvironmentProps;
};

Properties

Contributing

Contributions are welcome! Please read our Code of Conduct and Contributing