ShaderGradientとは？React・Next.jsで3Dグラデーション背景を実装する手順

ShaderGradientは、three.jsで動く3Dグラデーションをブラウザ上で調整し、そのままReactコンポーネントとして貼り込めるMITライセンスのOSSです。ダウンロードして起動する専用アプリは存在せず、Webエディタとnpmパッケージ、それにFigma・Framerのプラグインだけで完結します。この記事では、公式リポジトリruucm/shadergradientとnpm registryの実データをもとに、React・Next.jsへの組み込み手順と、公式ドキュメントには書かれていない依存関係の落とし穴までを扱います。

まとめ

• 実体は npm の @shadergradient/react（最新2.4.20／2025年12月8日公開）と、Webエディタ shadergradient.co、Figmaプラグイン、Framerコンポーネントの4形態。OS別インストーラを配布するデスクトップ版は無い。
• Reactで使うには three と @react-three/fiber を自分で追加する。パッケージ側に依存宣言が無いため、入れ忘れてもnpmは警告を出さない。
• Next.js 15のApp Routerでは React 19 + React Three Fiber 9系の組み合わせが必須。8系だと ReactCurrentOwner 参照エラーで画面が落ちる。
• ESM専用パッケージで、require() からは読み込めない。
• three 0.183.0以降では THREE.Clock の非推奨警告がコンソールに出る（issue #158、2026年7月29日時点で未解決）。動作自体には影響しない。

以下、提供形態の整理から導入コード、そして採用前に潰しておくべき制約までを順に見ていきます。

ShaderGradientの提供形態｜デスクトップアプリではなくブラウザとnpmで完結する

GitHubの公式リポジトリ ruucm/shadergradient は自らを「Create beautiful moving gradients on Framer, Figma and React」と説明しています。2022年4月16日に作成され、2026年7月29日時点でスター1,995・フォーク109、直近のpushは2026年6月11日です。配布経路はnpmとデザインツールのプラグインのみで、インストーラ、ライセンスキー、独自のプロジェクトファイル形式はどこにも存在しません。動作要件はWebGLが動くブラウザです。

グラデーションの描画そのものはthree.jsが担当しています。three.jsの基礎から押さえたい場合はThree.jsとは？ – Three.jsの概要とその魅力について徹底解説を先に読むと、後述するプロパティの意味がつかみやすくなります。

Figma・Framer・Reactの3経路と、出力物から決める選び分け

迷ったときの判断基準は単純で、最終的な成果物がコードかどうかだけです。Webサイトやアプリに組み込むならnpm版一択で、他の2つは検討する必要すらありません。逆にデザインカンプの背景として静止画やGIFが欲しいだけなら、Figma Communityのプラグイン（ID: 1203016883447870818）で完結します。Framerで作ったサイトに載せるなら、公式が配布するFramerコンポーネントのURLをキャンバスに貼り付けるのが最短です。npm版を選んだ場合だけ、次章以降の依存関係の管理が発生します。

shadergradient.coのカスタマイズ画面で設定を作りURLとして持ち出す手順

公式サイトの /customize は、形状・3色のカラー・カメラ角度・アニメーション速度をGUIで詰めるためのエディタです。ここで作った状態はページのクエリ文字列にすべて載るため、URLをコピーするだけで設定を持ち出せます。READMEが例示しているURLは次のような形です。

https://www.shadergradient.co/customize?animate=on&cDistance=3.6&cPolarAngle=90
&color1=%2352ff89&color2=%23dbba95&color3=%23d0bce1&lightType=3d&shader=defaults
&type=plane&uFrequency=5.5&uSpeed=0.4&uStrength=4

クエリのキー名は、そのままReactコンポーネントのprops名に対応します。type、color1、uSpeed といったパラメータをコード上で手探りするより、エディタで見た目を確定させてからURLごとコードへ渡すほうが早く終わります。渡し方は後述の control='query' です。

@shadergradient/reactの導入手順とインストール時に踏みやすい依存の罠

宣言されていない three・@react-three/fiber の手動追加

npm registryで2.4.20の実体を確認すると、package.jsonに dependencies フィールドそのものが存在せず、peerDependencies も react と react-dom（いずれも ^18.2.0 || ^19.0.0）の2つだけです。ところが配布されているdistを開くと、外部モジュールとして three と @react-three/fiber をimportしています。宣言と実装が食い違っているため、この2つを入れ忘れてもインストール時には何も起きず、ビルドやランタイムで初めてモジュール解決エラーになります。

npm i @shadergradient/react @react-three/fiber three
npm i -D @types/three

READMEは three-stdlib と camera-controls の追加も指示しています。ただし2.4.20のdistを調べると、camera-controlsの実装もthree-stdlibのRGBELoaderもチャンクファイルへ丸ごとバンドルされており、外部importとしては一切現れません。実際に自分で解決する必要があるのは three と @react-three/fiber の2つです。ここを絞っておくと、後述するthreeの版固定が効きやすくなります。

なお公式が開発時に使っているのは、devDependenciesの記載どおり @react-three/fiber ^8.17.10 と three ^0.169.0 です。つまりパッケージ自体は8系でビルドされており、次に挙げる「App Routerでは9系が必須」という制約は、ShaderGradient側ではなくNext.js側の事情から来ています。

ShaderGradientCanvasとShaderGradientによる最小構成

パッケージが公開している型定義には、ShaderGradient、ShaderGradientCanvas、useShaderGradientCanvasContext、presets、presetsArray、initialActivePreset、propertyControls、formatUrlString、formatFramerProps が並んでいます。日常的に使うのは最初の2つで、キャンバスの中にグラデーションを1つ置くのが基本形です。

import { ShaderGradientCanvas, ShaderGradient } from '@shadergradient/react'

export function Background() {
  return (
    <ShaderGradientCanvas
      style={{ position: 'absolute', inset: 0 }}
      pixelDensity={1.5}
      fov={45}
    >
      <ShaderGradient cDistance={32} cPolarAngle={125} />
    </ShaderGradientCanvas>
  )
}

v2の @shadergradient/react はレンダラーだけを提供し、状態管理もコントロールUIも持ちません。色を動的に切り替えたいなら、propsを自前のstateから渡します。

control=’query’による設定URLの受け渡し

propsを1つずつ書き写す代わりに、control に 'query' を指定して urlString にエディタのURLを丸ごと渡せます。デザイン担当が調整したURLをそのままコードに貼れるので、色や速度の微調整のたびにpropsを書き換える往復がなくなります。

<ShaderGradientCanvas>
  <ShaderGradient
    control='query'
    urlString='https://www.shadergradient.co/customize?animate=on&cDistance=3.6&uSpeed=0.4'
  />
</ShaderGradientCanvas>

指定を省略した場合は 'props' として扱われ、JSXに書いた値が使われます。両方を混ぜると意図しない値が優先されるので、1つのコンポーネントではどちらかに寄せてください。

Next.js 15 App Routerで必須となる版の組み合わせ

環境ごとに要求されるバージョンが変わるのは、ShaderGradient本体ではなくReact Three Fiber側の事情です。READMEの互換表は次のとおりです。

App RouterでReact Three Fiber 8系を使うと、Uncaught Error: Cannot read properties of undefined (reading ‘ReactCurrentOwner’) でページごとクラッシュします。App Routerが内部に抱えるReact 19 canaryと8系のreact-reconcilerが噛み合わないためで、issue #138として2025年9月1日に報告され2026年5月8日にクローズされました。8系は8.18.0（2025年2月19日）で更新が止まっているので、App Router案件では最初から9系（2026年7月29日時点の最新は9.6.1）を選んでください。この組み合わせを守っていれば、next.config へのtranspilePackages追加やエイリアス設定は不要です。

mainブランチのCHANGELOGには、2.4.22のnoExternal ‘react-reconciler’、2.4.23のproduction-wrap修正といったreact-reconciler周りの変更が積まれています。ただし後述のとおりこれらはnpmに公開されていません。2.4.20を使う限り、回避策は表の組み合わせを守ることだけです。

主要プロパティの分類と、見た目を詰めるときに触る順番

触る順番は、形状のtype、色3点、カメラ距離と角度、最後にアニメーション速度です。typeを変えると同じカメラ設定でも見え方が大きく変わるため、先に色や速度を詰めると作業が無駄になります。uStrengthやuFrequencyといったシェーダー側のパラメータは相互に影響し合うので、GUIで当たりを付けてからコードへ移すほうが確実です。

GitHubリポジトリとパッケージ構成｜v1からv2への移行判断

v1「shadergradient」とv2「@shadergradient/react」の実質的な違い

CHANGELOGの2.0.0に記録されたMajor Changeは「@shadergradient/react」の一行だけで、スコープなしパッケージからスコープ付きパッケージへの移行そのものがメジャー更新の中身でした。旧パッケージ shadergradient は1.3.5（2024年10月22日）で更新が止まり、説明文も「For better code experiences in the Framer Canvas」とFramer向けのまま残っています。v1はストアとUIを同梱していましたが、v2はレンダラーだけに絞られました。

移行するかどうかは、直近1か月のダウンロード数を見れば判断が付きます。2026年6月25日から7月24日の実績で、@shadergradient/react が119,479に対し shadergradient は14,979です。新規導入でv1を選ぶ理由はありません。

紛らわしいのが、READMEに登場するもう1つの旧パッケージ shadergradient-old（1.2.7／2024年3月31日）です。READMEはこれを「ストアとUIを同梱していたレガシーv1。旧来のwith-storeビルドに依存している場合だけ使い続けること」と位置づけています。版番号だけ見ると shadergradient の1.3.5（2024年10月22日）のほうが新しいため、単に「古いv1」と考えると取り違えます。すでに shadergradient で動いているコードをそのまま維持するならパッケージを変える必要はなく、shadergradient-old はストア同梱ビルドを名指しで固定したいときの退避先だと理解してください。

npm未公開パッケージと名前が紛らわしい別プロジェクトの見分け方

公式リポジトリまわりには、名前だけ見ると取り違えやすいパッケージがいくつか流通しています。導入前に区別しておかないと、無関係なライブラリのドキュメントを読み続けることになります。

• @shadergradient/ui：READMEが「Not published to npm」と明記しているとおり、npmには0.0.0のプレースホルダ（2025年2月9日）しか無い。Framer・Figma向けにESMバンドルとして配布される。
• @shader-gradient/core・@shader-gradient/react・@shader-gradient/vue（0.3.0／2026年6月21日）：スコープ名にハイフンが入る別物で、リポジトリはJannchie/shader-gradient。作者もコードも公式とは無関係。
• shader-gradient-vue、@siavava/shadergradient-vue：いずれも第三者によるVue移植で、公式のサポート対象外。

版を確認する先も間違えないでください。先に触れた2.4.21から2.4.24はmainブランチのCHANGELOGにしか存在せず、npmのdist-tagsのlatestは2.4.20のままです。版はnpm registry側で確認します。ライセンスはREADMEとpackage.jsonのいずれもMIT（ruucm、stone-skipper）で、商用サイトでも利用できます。

導入前に潰しておく制約｜ESM専用・非推奨警告・常時描画のコスト

import条件のみのexportsとrequire()非対応

2.4.20のpackage.jsonの exports は {".": {"import": "./dist/index.mjs", "types": "./dist/index.d.mts"}} だけで、require 条件もCJSビルドも用意されていません。型定義ファイルも .d.mts 一種類です。そのため、CommonJSのまま動かしているJestのテストや、node --require 経由のスクリプトからは読み込めません。ESM対応のtransform設定を入れるか、テスト側でモックに差し替えるかの二択になります。ESMとCommonJSの解決の違いでつまずいた経験がある場合は、Native ESMの基本仕組みとCommonJSとの根本的な違いの整理で前提を揃えてから設定に取りかかると早く終わります。

three 0.183.0以降で出るTHREE.Clockの非推奨警告

2.4.20のdistは、threeから Clock をimportしてインスタンス化しています。一方three側は0.183.0（2026年2月18日公開）のビルドに「THREE.Clock: This module has been deprecated. Please use THREE.Timer instead.」という警告を追加しました。0.182.0（2025年12月10日）のビルドにこの文字列は含まれていません。結果として、threeを0.183.0以降に上げるとコンソールに非推奨警告が出続けます。issue #158として2026年7月25日に報告され、7月29日時点で未解決です。

描画は正常に動くので、警告を許容するのが基本方針です。CIがコンソール警告をエラー扱いする構成だけ、threeを0.182.x に固定して回避してください。最新の0.185.1（2026年7月1日）へ上げる必要が本当にあるかは、他の依存と合わせて判断する話になります。

常時描画のコストとlazyLoad採用の判断基準

ShaderGradientCanvas の型定義には lazyLoad、threshold、rootMargin、pixelDensity、powerPreference、preserveDrawingBuffer が用意されています。ファーストビューの外に置く背景なら lazyLoad を有効にし、rootMargin で先読み距離を決めるのが定石です。表示中の負荷が気になるなら pixelDensity を下げます。

ただし、Core Web Vitalsが厳しく問われるLPやモバイル比率の高いサイトでは、ShaderGradientを採用しないという判断のほうが妥当です。GPUで毎フレーム描画し続ける以上、遅延ロードやピクセル密度の調整で消せるのは初期コストだけで、スクロール中の負荷は残ります。リポジトリにも「Google Pagespeed Timeout」（issue #80）や「Stuttering on mobile」（issue #81）が未クローズのまま残っています。動きのある背景がコンバージョンに直結しないページなら、静止画のグラデーションで十分です。ページの描画コストをどこまで許容するかの前提整理には、レンダリングとは？ブラウザ描画の仕組みとCSR/SSR/SSGの違い・選定基準を解説が使えます。

よくある質問

ShaderGradientの利用に費用はかかりますか？

かかりません。リポジトリのREADMEとnpmのpackage.jsonのいずれもライセンスをMITと明記しており、著作権表示はruucmとstone-skipperの2名です。商用サイトへの組み込みも、改変してのプロダクト利用も可能です。ただし2026年7月29日時点でリポジトリ直下にLICENSEファイルは置かれておらず、ライセンス表記はREADME末尾とpackage.jsonの license フィールドにあります。社内の法務確認でファイルの提示を求められる場合は、この2か所を根拠として示してください。

デザインカンプ用に静止画やGIFだけ欲しい場合はどうしますか？

Figmaプラグイン（Figma Community ID: 1203016883447870818）を使えば、Reactの実装を一切書かずに済みます。READMEのFuture Planでは「Figma GIF Support」が完了項目としてチェック済みで、GIF書き出しのサンプルもExamplesセクションからリンクされています。動く背景をそのまま納品物に含めたいのか、それとも実装コードに組み込みたいのかで経路が分かれるだけなので、前者ならnpm版を触る必要はありません。逆にFigmaプラグインで作ったGIFをそのままWebサイトの背景に貼るのは、ファイルサイズと色数の制約から実用的ではありません。

GitHubのどのリポジトリとパッケージが公式ですか？

ruucm/shadergradient が公式です。2022年4月16日作成で、homepageにshadergradient.coが設定されており、npmの @shadergradient/react もここから公開されています。検索で見つかる zavalit/ruucm-shadergradient は、GitHub API上もこのリポジトリの個人フォークとして記録されています。紛らわしいのはスコープ名にハイフンが入る @shader-gradient 系で、こちらはJannchie/shader-gradientという別作者の独立したプロジェクトです。ドキュメントを読む前にオーナー名を確認してください。

VueやSvelteでも使えますか？

公式パッケージはReact専用です。distが @react-three/fiber とReactのJSXランタイムに直接依存しているため、他フレームワークからそのまま呼び出すことはできません。npmには shader-gradient-vue や @siavava/shadergradient-vue といったVue向けの移植がありますが、いずれも第三者製で公式のサポート対象外です。READMEのFuture Planには「シェーダーコードを別パッケージに切り出してJSやVueなどから再利用可能にする」が未着手項目として残るのみで、公式のVue版パッケージ自体の計画は示されていません。Solid.js対応はissue #156として2026年5月7日に要望が挙がった段階です。

React 18のプロジェクトのままでも導入できますか？

できます。2.4.20のpeerDependenciesはreactとreact-domのいずれも ^18.2.0 || ^19.0.0 で、React 18を明示的にサポートしています。READMEの互換表でも、Next.js 14、Next.js 15のPages Router、Viteなどの環境はReact 18のままReact Three Fiberの8系か9系を選べます。React 19への移行が必須になるのはNext.js 15のApp Routerだけです。ただしReact Three Fiberの8系は8.18.0（2025年2月19日）を最後に更新が止まっているため、React 18に留まる場合でも新規導入では9系を選んでおくほうが後の移行が楽になります。

関連記事

• Three.jsとは？ – Three.jsの概要とその魅力について徹底解説
• PixiJSとは？WebGL/WebGPUで動く2D描画エンジンの使い方をv8対応で解説
• Native ESMの基本仕組みとCommonJSとの根本的な違いの整理
• レンダリングとは？ブラウザ描画の仕組みとCSR/SSR/SSGの違い・選定基準を解説
• RiveとLottieの違いを徹底比較｜ファイルサイズ・インタラクティブ性・Unity対応で選ぶ