Installation

Prérequis#

• Tailwind CSS v4 : les composants et les effets utilisent ses classes et les tokens de couleur de shadcn (bg-background, text-foreground…). Les primitives n'ont aucun prérequis.
• React 19 ou Vue 3.5, ou aucun framework pour le JavaScript natif.
• Un fichier @/lib/utils qui exporte la fonction cn, pour les composants et les effets. Il est créé automatiquement par shadcn init ou shadcn-vue init.
• En TypeScript, les fichiers compilent en mode strict, avec TypeScript 5.9 comme avec TypeScript 6.

Avec le CLI (recommandé)#

Chaque page donne la commande exacte. Le CLI copie les fichiers dans components/o-ui/<élément>/, à l'intérieur du dossier de vos composants, et installe les dépendances. Les primitives dont l'élément a besoin s'installent avec lui, dans des dossiers voisins (components/o-ui/frame-loop/…).

npx shadcn@latest add https://o-ui.hd987.dev/r/magnetic.json

Raccourci par namespace#

Déclarez le registry O-UI une fois dans components.json pour installer les éléments par leur nom :

{
  "registries": {
    "@o-ui": "https://o-ui.hd987.dev/r/{name}.json"
  }
}

npx shadcn@latest add @o-ui/magnetic

Pour Vue, utilisez l'URL https://o-ui.hd987.dev/r/vue/{name}.json dans le components.json de shadcn-vue.

Mettre à jour une primitive partagée#

Une primitive est partagée par tous les éléments O-UI de votre projet : Magnetic, GlowBorder et ScrollTint utilisent le même frame-loop. Le code copié n'a pas de numéro de version :

• Quand vous ajoutez un élément plus récent, le CLI peut demander s'il faut écraser les fichiers d'une primitive déjà présente (« already exists. Would you like to overwrite? »), même avec -y. Acceptez, puis réinstallez avec --overwrite les autres éléments O-UI du projet : tous partagent alors la même version de leurs primitives.
• La même question apparaît si vous avez modifié une primitive à la main.
• Gardez un seul exemplaire de chaque primitive, dans components/o-ui/ : deux copies de frame-loop feraient deux boucles et deux pauses.

À la main#

Chaque page propose un onglet Manuel : installez les dépendances indiquées, puis copiez les fichiers dans les dossiers listés sous components/o-ui/. Copiez aussi les dossiers des primitives indiqués, sauf s'ils sont déjà dans votre projet. Ces dossiers doivent rester voisins : les éléments importent leurs primitives par un chemin relatif (../frame-loop/…).

En JavaScript natif#

Copiez le dossier de l'élément sans ses adaptateurs (.tsx, .vue, use-*.ts), et les dossiers des primitives qu'il utilise : l'onglet Vanilla de chaque page les liste.

• Un composant ou un effet expose une fonction create…(élément, options), qui renvoie update() et destroy().
• Une primitive expose ses fonctions : subscribe…, qui renvoie la fonction de désabonnement, ou observe… et animate…, qui renvoient update() et destroy().

Voir React, Vue et JavaScript natif.