Use CSS anchor positioning

README.md

@@ -25,6 +25,42 @@ Supported Browsers
 | --------- | --------- | --------- | --------- |
 | Edge| last 2 versions| last 2 versions| last 2 versions
 
+## CSS Anchor Positioning
+
+Shepherd uses the modern CSS Anchor Positioning API for optimal performance and native browser support. This provides excellent positioning capabilities in browsers that support it:
+
+- **Chrome 125+**: Full native support
+- **Safari 26+**: Full native support  
+- **Edge 125+**: Full native support
+- **Firefox**: Support is coming but currently requires a polyfill
+
+### Adding Polyfill Support
+
+For broader browser compatibility (including Firefox), you can add the CSS Anchor Positioning polyfill:
+
+```html
+<script type="module">
+  if (!("anchorName" in document.documentElement.style)) {
+    import("https://unpkg.com/@oddbird/css-anchor-positioning");
+  }
+</script>
+```
+
+Or install via npm for bundled applications:
+
+```bash
+npm install @oddbird/css-anchor-positioning
+```
+
+```javascript
+// Add to your app initialization
+if (!("anchorName" in document.documentElement.style)) {
+  import("@oddbird/css-anchor-positioning");
+}
+```
+
+The polyfill is approximately 40KB gzipped and provides comprehensive support for CSS anchor positioning in all modern browsers.
+
 # Shepherd
 
 Shepherd makes it simple to create custom user on-boarding tours, trainings and announcements to drive user adoption. 

docs-src/src/content/docs/guides/install.mdx

@@ -37,6 +37,57 @@ Don't forget to add your styles
 import 'shepherd.js/dist/css/shepherd.css';
 ```
 
+## Browser Compatibility
+
+Shepherd uses the modern CSS Anchor Positioning API for optimal performance and positioning. This provides excellent support in modern browsers:
+
+- **Chrome 125+**: Full native support
+- **Safari 26+**: Full native support  
+- **Edge 125+**: Full native support
+- **Firefox**: Support is coming but currently requires a polyfill
+
+### Adding Polyfill for Broader Support
+
+For applications that need to support browsers without native CSS anchor positioning (like Firefox), you can add the polyfill:
+
+<Tabs>
+  <TabItem label="CDN">
+  ```html
+  <script type="module">
+    if (!("anchorName" in document.documentElement.style)) {
+      import("https://unpkg.com/@oddbird/css-anchor-positioning");
+    }
+  </script>
+  ```
+  </TabItem>
+  <TabItem label="npm">
+  ```bash
+  npm install @oddbird/css-anchor-positioning
+  ```
+
+  ```javascript
+  // Add to your app initialization
+  if (!("anchorName" in document.documentElement.style)) {
+    import("@oddbird/css-anchor-positioning");
+  }
+  ```
+  </TabItem>
+  <TabItem label="yarn">
+  ```bash
+  yarn add @oddbird/css-anchor-positioning
+  ```
+
+  ```javascript
+  // Add to your app initialization
+  if (!("anchorName" in document.documentElement.style)) {
+    import("@oddbird/css-anchor-positioning");
+  }
+  ```
+  </TabItem>
+</Tabs>
+
+**Note**: The polyfill adds approximately 40KB gzipped to your bundle. Most modern browsers (Chrome 125+, Safari 26+) don't need it.
+
 ### GitHub Releases
 
 Whenever we release a new version, the contents of the `dist` are uploaded

docs-src/src/content/docs/guides/usage.md

@@ -230,7 +230,7 @@ If the element to highlight does not yet exist while instantiating tour steps, y
 - `id`: The string to use as the `id` for the step. If an id is not passed one will be generated.
 - `modalOverlayOpeningPadding`: An amount of padding to add around the modal overlay opening
 - `modalOverlayOpeningRadius`: An amount of border radius to add around the modal overlay opening. It can be either a number or an object with properties `{ topLeft, bottomLeft, bottomRight, topRight }`
-- `floatingUIOptions`: Extra options to pass to [Floating UI](https://floating-ui.com/docs/getting-started)
+- `anchorOptions`: Options for CSS anchor positioning including `placement`, `offset`, and `arrow`
 - `showOn`: A function that, when it returns true, will show the step. If it returns false, the step will be skipped.
 - `scrollTo`: Should the element be scrolled to when this step is shown? If true, uses the default `scrollIntoView`, if an object, passes that object as the params to `scrollIntoView` i.e. `{behavior: 'smooth', block: 'center'}`
 - `scrollToHandler`: A function that lets you override the default `scrollTo` behavior and define a custom action to do the scrolling,
@@ -297,7 +297,7 @@ myTour.addStep({
 });
 ```
 
-You can also provide an options object, to configure the arrow's [padding](https://floating-ui.com/docs/arrow#padding). The padding is the closest the arrow will get to the edge of the step.
+You can also provide an options object, to configure the arrow's padding. The padding is the closest the arrow will get to the edge of the step.
 
 ```js
 myTour.addStep({

docs-src/src/content/docs/recipes/cookbook.md

@@ -39,14 +39,13 @@ between them or if you need to fine tune the position according to some custom l
 For example:
 
 ```js
-import { offset } from '@floating-ui/dom';
-
 const tour = new Shepherd.Tour({
   steps: [
     {
       ...
-      floatingUIOptions: {
-        middleware: [offset({ mainAxis: 0, crossAxis: 12 })]
+      anchorOptions: {
+        placement: 'bottom',
+        offset: 12
       }
       ...
     }

landing/src/pages/index.astro

@@ -120,7 +120,7 @@ import MainPage from '@layouts/MainPage.astro';
         // This should add the first tour step
         steps: [
           {
-            text: '\n         <p>\n           Shepherd is a JavaScript library for guiding users through your app.\n           It uses <a href="https://floating-ui.com/" data-test-popper-link>Floating UI</a>,\n           another open source library, to render dialogs for each tour "step".\n         </p>\n        \n         <p>\n           Among many things, Floating UI makes sure your steps never end up off screen or cropped by an overflow.\n           (Try resizing your browser to see what we mean.)\n         </p>\n',
+             text: '\n         <p>\n           Shepherd is a JavaScript library for guiding users through your app.\n           It uses modern CSS anchor positioning to render dialogs for each tour "step".\n         </p>\n        \n         <p>\n           CSS anchor positioning ensures your steps are always positioned correctly relative to target elements.\n           (Try resizing your browser to see what we mean.)\n         </p>\n',
             attachTo: {
               element: '.hero-welcome',
               on: 'bottom'

package.json

@@ -33,6 +33,7 @@
   "devDependencies": {
     "@babel/core": "^7.28.4",
     "@babel/preset-env": "^7.28.3",
+    "@oddbird/css-anchor-positioning": "^0.7.0",
     "@typescript-eslint/eslint-plugin": "^7.18.0",
     "@typescript-eslint/parser": "^7.18.0",
     "autoprefixer": "^10.4.21",