Anchor Positioning

Alpine.js Anchor Positioning: The Magical Sticky Note Guide

🎯 What We’ll Learn

Imagine you have a sticky note that magically follows a button wherever it goes on your desk. That’s exactly what Anchor Positioning does in Alpine.js! It helps floating things (like tooltips, dropdowns, and popups) stick to their buttons perfectly.

🌟 The Big Picture

Think of it like this:

A balloon tied to a child’s wrist 🎈

The balloon (your tooltip) always floats near the child (your button). No matter where the child walks, the balloon follows. That’s anchor positioning!

📦 Part 1: Anchor Positioning Basics

What is an Anchor?

An anchor is the thing your floating element sticks to. Like a ship’s anchor keeps it in place, your button “anchors” your tooltip.

<div x-data="{ open: false }">
  <!-- This button is the ANCHOR -->
  <button x-ref="button" @click="open = !open">
    Click Me
  </button>

  <!-- This tooltip STICKS to the anchor -->
  <div x-show="open" x-anchor="$refs.button">
    I'm a tooltip!
  </div>
</div>

How It Works

graph TD
    A["Button - The Anchor"] --> B["x-anchor directive"]
    B --> C["Tooltip follows button"]
    C --> D["Always stays connected!"]

Simple Example Explained

🎈 Real-Life Analogy

Think of a price tag tied to a product in a store. The tag (tooltip) always hangs near the product (button). Move the product, and the tag follows!

🎚️ Part 2: Anchor Position Modifiers

Now let’s control WHERE the tooltip appears! Just like you can tie a balloon to your left wrist or right wrist, you can position tooltips in different spots.

Available Positions

graph TD
    subgraph Positions
        A["top"] --> B["Floats above"]
        C["bottom"] --> D["Floats below"]
        E["left"] --> F["Floats to left"]
        G["right"] --> H["Floats to right"]
    end

Using Position Modifiers

<!-- Tooltip appears BELOW the button -->
<div x-anchor.bottom="$refs.button">
  I'm below!
</div>

<!-- Tooltip appears ABOVE the button -->
<div x-anchor.top="$refs.button">
  I'm above!
</div>

<!-- Tooltip appears to the LEFT -->
<div x-anchor.left="$refs.button">
  I'm on the left!
</div>

<!-- Tooltip appears to the RIGHT -->
<div x-anchor.right="$refs.button">
  I'm on the right!
</div>

Complete Example

<div x-data="{ open: false }">
  <button
    x-ref="myButton"
    @click="open = !open">
    Show Menu
  </button>

  <div
    x-show="open"
    x-anchor.bottom-start="$refs.myButton"
    class="menu">
    <p>Menu Item 1</p>
    <p>Menu Item 2</p>
  </div>
</div>

Position Combinations

You can be even more specific! Combine positions like this:

🎈 Real-Life Analogy

Think of a speech bubble in a comic book! Sometimes it points up, sometimes down, sometimes to the side. That’s exactly what these modifiers do!

⚙️ Part 3: Anchor Configuration Options

Now for the cool part! You can customize how your anchor behaves with special options.

The Offset Option

Add space between the anchor and the floating element:

<!-- 10 pixels of space below the button -->
<div x-anchor.bottom.offset.10="$refs.button">
  I have breathing room!
</div>

The Gap Option

Similar to offset, but written differently:

<!-- Using gap modifier -->
<div x-anchor.bottom.gap.8="$refs.button">
  8 pixels of gap!
</div>

Offset Comparison

graph LR
    A["Button"] --> B["No Offset"]
    A --> C["offset.10 = 10px gap"]
    A --> D["offset.20 = 20px gap"]

Complete Configuration Example

<div x-data="{ showTip: false }">
  <button
    x-ref="trigger"
    @mouseenter="showTip = true"
    @mouseleave="showTip = false">
    Hover over me
  </button>

  <div
    x-show="showTip"
    x-anchor.top.offset.8="$refs.trigger"
    x-transition
    class="tooltip">
    This tooltip appears above
    with 8px spacing!
  </div>
</div>

All Configuration Options

🎓 Putting It All Together

Let’s build a complete dropdown menu!

<div x-data="{ menuOpen: false }">
  <!-- The Anchor (our button) -->
  <button
    x-ref="menuBtn"
    @click="menuOpen = !menuOpen"
    class="btn">
    Open Menu ▼
  </button>

  <!-- The Floating Menu -->
  <div
    x-show="menuOpen"
    x-anchor.bottom-start.offset.4="$refs.menuBtn"
    x-transition
    @click.outside="menuOpen = false"
    class="dropdown">

    <a href="#">Profile</a>
    <a href="#">Settings</a>
    <a href="#">Logout</a>
  </div>
</div>

What Each Part Does

graph TD
    A["x-ref=menuBtn"] --> B["Names our anchor"]
    C["x-anchor.bottom-start"] --> D["Menu goes below, left-aligned"]
    E[".offset.4"] --> F["4px gap between button and menu"]
    G["x-transition"] --> H["Smooth animation"]
    I["@click.outside"] --> J["Closes when clicking away"]

🚀 Quick Reference

Basic Syntax

x-anchor="$refs.anchorName"

With Position

x-anchor.bottom="$refs.anchorName"
x-anchor.top-end="$refs.anchorName"

With Offset

x-anchor.bottom.offset.10="$refs.anchorName"

🎉 You Did It!

Now you understand Alpine.js Anchor Positioning! Remember:

1. Basics - Use x-anchor to stick elements to anchors
2. Modifiers - Use .top, .bottom, .left, .right to control position
3. Options - Use .offset.N to add spacing

Think of it like a loyal pet that always follows you but stays at just the right distance! 🐕

💡 Pro Tips

Tip 1: Always use x-ref to name your anchor element

Tip 2: Combine with x-transition for smooth animations

Tip 3: Use @click.outside to close floating elements when clicking away