0
# Reference Handling
1

2
Reference element handling functionality that marks DOM elements as reference points for positioning. The Reference component registers elements with the Manager context and provides render props for attaching refs to DOM elements.
3

4
## Capabilities
5

6
### Reference Component
7

8
Marks a DOM element as the reference point for positioning. Uses render props pattern to provide ref that must be attached to the target element.
9

10
```typescript { .api }
11
/**
12
 * Marks an element as the reference point for positioning
13
 * @param children - Render prop function receiving ref to attach to DOM element
14
 * @param innerRef - Optional ref to the reference element for external access
15
 * @returns React element that registers reference with Manager context
16
 */
17
function Reference({ children, innerRef }: ReferenceProps): React.Node;
18

19
interface ReferenceProps {
20
  /** Render prop function that receives props for the reference element */
21
  children: (props: ReferenceChildrenProps) => React.ReactNode;
22
  /** Optional ref for external access to the reference element */
23
  innerRef?: React.Ref<any>;
24
}
25

26
interface ReferenceChildrenProps {
27
  /** Ref that must be attached to the DOM element that serves as reference */
28
  ref: React.Ref<any>;
29
}
30
```
31

32
**Usage Examples:**
33

34
```tsx
35
import React from "react";
36
import { Manager, Reference, Popper } from "react-popper";
37

38
// Basic reference usage
39
function BasicReference() {
40
  return (
41
    <Manager>
42
      <Reference>
43
        {({ ref }) => (
44
          <button ref={ref} type="button">
45
            Reference Element
46
          </button>
47
        )}
48
      </Reference>
49
      {/* Popper component would go here */}
50
    </Manager>
51
  );
52
}
53

54
// Reference with external ref access
55
function ReferenceWithExternalRef() {
56
  const buttonRef = React.useRef(null);
57

58
  const handleClick = () => {
59
    if (buttonRef.current) {
60
      buttonRef.current.focus();
61
    }
62
  };
63

64
  return (
65
    <Manager>
66
      <Reference innerRef={buttonRef}>
67
        {({ ref }) => (
68
          <button ref={ref} onClick={handleClick}>
69
            Button with external ref
70
          </button>
71
        )}
72
      </Reference>
73
    </Manager>
74
  );
75
}
76

77
// Reference with complex elements
78
function ComplexReference() {
79
  return (
80
    <Manager>
81
      <Reference>
82
        {({ ref }) => (
83
          <div ref={ref} className="complex-reference">
84
            <img src="icon.png" alt="Icon" />
85
            <span>Complex Reference Content</span>
86
          </div>
87
        )}
88
      </Reference>
89
    </Manager>
90
  );
91
}
92
```
93

94
### Ref Types
95

96
Reference handling supports both callback refs and ref objects:
97

98
```typescript { .api }
99
/** Callback function for handling refs */
100
type RefHandler = (ref: HTMLElement | null) => void;
101

102
/** Ref object with current property */
103
type RefObject = { current?: HTMLElement | null };
104

105
/** Union type for React refs */
106
type Ref = RefHandler | RefObject;
107
```
108

109
## Integration with Manager Context
110

111
The Reference component integrates with Manager context to:
112

113
1. **Register reference elements**: Automatically registers the ref'd element with Manager
114
2. **Handle cleanup**: Removes reference from context when component unmounts
115
3. **Provide warnings**: Warns in development if used outside Manager
116

117
## Error Handling and Validation
118

119
The Reference component includes built-in safeguards:
120

121
- **Context validation**: Warns if Reference is used outside of Manager component
122
- **Cleanup handling**: Automatically cleans up refs on component unmount
123
- **Ref safety**: Handles both callback and object refs safely
124

125
## Best Practices
126

127
1. **Always use within Manager:**
128
   ```tsx
129
   // ✅ Correct
130
   <Manager>
131
     <Reference>{({ ref }) => <button ref={ref}>Button</button>}</Reference>
132
   </Manager>
133

134
   // ❌ Incorrect - will show warning
135
   <Reference>{({ ref }) => <button ref={ref}>Button</button>}</Reference>
136
   ```
137

138
2. **Attach ref to actual DOM element:**
139
   ```tsx
140
   // ✅ Correct - ref on DOM element
141
   <Reference>
142
     {({ ref }) => <button ref={ref}>Button</button>}
143
   </Reference>
144

145
   // ❌ Incorrect - ref on React component
146
   <Reference>
147
     {({ ref }) => <MyComponent ref={ref} />}
148
   </Reference>
149
   ```
150

151
3. **Use innerRef for external access:**
152
   ```tsx
153
   // ✅ Good for external control
154
   const myRef = useRef(null);
155
   <Reference innerRef={myRef}>
156
     {({ ref }) => <button ref={ref}>Button</button>}
157
   </Reference>
158
   ```
159

160
4. **Handle dynamic references:**
161
   ```tsx
162
   // ✅ Handle conditional rendering
163
   <Reference>
164
     {({ ref }) => (
165
       <div>
166
         {showButton ? (
167
           <button ref={ref}>Dynamic Button</button>
168
         ) : (
169
           <span ref={ref}>Fallback Element</span>
170
         )}
171
       </div>
172
     )}
173
   </Reference>
174
   ```