はじめに

polaris-vue-elements は、Shopify の Polaris web components（<s-button>、<s-text-field>、<s-modal> など）をラップする型付きの Vue 3 コンポーネント集です。web components 本体は Shopify の CDN から runtime で読み込まれます。このライブラリは、それらを型付きで Vue らしく扱えるインターフェース（props、events、v-model）を提供するだけです。

1. インストール

npm install polaris-vue-elements

2. Polaris runtime を読み込む

wrapper コンポーネントは表示のためだけのもので、実際のカスタム要素の定義は含んでいません。ホストアプリで Shopify の Polaris runtime スクリプトを読み込む必要があります。このスクリプトが <s-*> 要素をグローバルに登録します。

html

<!-- index.html -->
<!doctype html>
<html>
  <head>
    <script src="https://cdn.shopify.com/shopifycloud/polaris-2.js"></script>
  </head>
  <body>
    <div id="app"></div>
  </body>
</html>

これは Shopify 管理画面の中だけでなく、どの Vue アプリでも動作します。コンポーネントはただのカスタム要素なので、スクリプトが読み込まれていればどこでも描画されます。

polaris-2.js は Shopify の stable チャンネルで、本番環境での利用を推奨します。特定のリリースに固定したい場合や、runtime のバージョンとこのライブラリのバージョンの関係を知りたい場合は、既知の注意点を参照してください。

Polaris 2.0 と新しい管理画面デザイン

Polaris 2.0 では、Shopify 管理画面の新しいビジュアルデザイン（色、タイポグラフィ、余白、アイコン）が導入されます。2026 年 10 月 22 日に stable になりました（告知）。 1.x からの移行はオプトインです。polaris-1.js を polaris-2.js に置き換えてください。

コードの変更は不要です。 2.0 はビジュアルの更新です。コンポーネント、props、 events、slots は 1.1 と同じで、いくつかの追加（SThumbnail の loading prop など）があるだけです。polaris-1.js のままのアプリもこれらの wrapper で引き続き動作します。 runtime で 2.x が必要になるのは追加分だけです。
各ストアのデザインに従います。 Shopify 管理画面の中では、新しい管理画面デザインのストアでは新しい見た目になり、以前のデザインのストアでは 1.x の見た目のままです。管理画面の外ではデフォルトで新しい見た目が使われるため、ローカルで簡単にプレビューできます。
ビューポート下部付近の固定（fixed）またはスティッキー（sticky）なコンテンツは、 --shopify-safe-area-inset-bottom CSS 変数でスペースを確保してください（environment API）。これにより、フローティング表示の Sidekick バーに隠れなくなります。
Built for Shopify アプリは、2027 年 5 月 1 日までに管理画面の新しいビジュアルスタイルに合わせる必要があります。

3. Vite を設定する

s-* タグを Vue コンポーネントとして解決しようとせず、カスタム要素として扱うよう Vue のコンパイラに指示します。

// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: {
          isCustomElement: (tag) => tag.startsWith('s-'),
        },
      },
    }),
  ],
})

4. 最初のコンポーネント

polaris-vue-elements からコンポーネントをインポートし、他の Vue コンポーネントと同じように使います。props と events はすべて型付けされています。

vue

<script setup lang="ts">
import { SButton } from 'polaris-vue-elements'

function handleClick(): void {
  console.log('clicked')
}
</script>

<template>
  <SButton variant="primary" @click="handleClick">Save</SButton>
</template>

5. フォームコンポーネントでの v-model

フォーム系のコンポーネントは v-model に対応しており、要素ごとに正しい prop/event の組み合わせに対応付けられます（完全な対応表は src/lib/overrides.ts を参照してください。テキスト系は value/input、SCheckbox/SSwitch は checked/change、 SChoiceList は values/change などを使います）。

vue

<script setup lang="ts">
import { ref } from 'vue'
import { STextField } from 'polaris-vue-elements'

const name = ref('')
</script>

<template>
  <STextField v-model="name" label="Name" placeholder="Your name" />
</template>

SModal などのオーバーレイコンポーネントは、2 通りの方法で制御できます。

宣言的に制御する場合は、トリガーボタンに標準 HTML の commandFor/command 属性を指定します。スクリプトは不要です。

vue

<template>
  <SButton commandFor="demo-modal" command="--show">Open modal</SButton>

  <SModal id="demo-modal" heading="Demo modal">
    <SText>Modal content.</SText>
    <template #primary-action>
      <SButton variant="primary" command="--hide" commandFor="demo-modal">Close</SButton>
    </template>
  </SModal>
</template>

命令的に制御する場合は、型付きのテンプレート ref を取得し、$el を通じて内部要素のメソッドを呼び出します。

vue

<script setup lang="ts">
import { useTemplateRef } from 'vue'
import { SModal } from 'polaris-vue-elements'

const modalRef = useTemplateRef<InstanceType<typeof SModal>>('modal')

function openModal(): void {
  modalRef.value?.$el.showOverlay()
}
</script>

<template>
  <SModal ref="modal" id="demo-modal" heading="Demo modal">
    <SText>Modal content.</SText>
  </SModal>
</template>

7. 生の `<s-*>` タグに型を付ける（任意）

wrapper に切り替えず、Polaris 本来のタグ（<s-button>、<s-text-field> など）を書き続けたい場合でも、このパッケージでそれらに型を付けられます。tsconfig.json で一度だけ有効にしてください。

json

{
  "compilerOptions": {
    "types": ["polaris-vue-elements/elements"]
  }
}

または、env.d.ts などの .d.ts ファイルで参照を追加します。

/// <reference types="polaris-vue-elements/elements" />

これにより、すべての Polaris タグが Vue の GlobalComponents に追加され、Volar と vue-tsc が wrapper と同じように生のタグをチェックします。union 型の props、型付きの @click / @aftershow リスナー、命令的なメソッド呼び出しのための型付き要素が得られます。

vue

<template>
  <!-- error: Type '"bogus"' is not assignable to type '"auto" | "primary" | … ' -->
  <s-button variant="bogus">Save</s-button>
</template>

これは型のみの機能です。runtime では何も登録されないため、手順 3 の isCustomElement 設定はそのまま残してください。wrapper との違いは 2 つあります。

生のタグでは v-model を使えません。 :value をバインドし、@input / @change を自分でリッスンするか、各フォームフィールドのプロパティとイベントを対応付けてくれる wrapper コンポーネントを使ってください。
同じタグに対する手書きの shim と併用しないでください。 異なる型を持つ GlobalComponents['s-button'] の宣言が 2 つあると競合します。有効にする際は shim を削除してください。

次のステップ

各 wrapper の prop/event の一覧はコンポーネントリファレンスで確認できます。また、実際に遭遇する前に既知の注意点を読んでおくことをおすすめします。

Shopify アプリを作る場合は、Vue 3 で Shopify 埋め込みアプリを作るを参照してください。 Vue から App Bridge を読み込む方法、認証付きリクエスト、App Bridge API について説明しています。

はじめに ​

1. インストール ​

2. Polaris runtime を読み込む ​

Polaris 2.0 と新しい管理画面デザイン ​

3. Vite を設定する ​

4. 最初のコンポーネント ​

5. フォームコンポーネントでの v-model ​

6. オーバーレイの制御（modal、popover、tooltip） ​

7. 生の <s-*> タグに型を付ける（任意） ​

次のステップ ​