Relevant source files

The following files were used as context for generating this wiki page: - [src/hooks/use-selected-element.ts](https://github.com/Flash-Brew-Digital/webflow-extension-starter/blob/main/src/hooks/use-selected-element.ts) - [src/app.tsx](https://github.com/Flash-Brew-Digital/webflow-extension-starter/blob/main/src/app.tsx) - [src/hooks/use-element-snapshot.ts](https://github.com/Flash-Brew-Digital/webflow-extension-starter/blob/main/src/hooks/use-element-snapshot.ts) - [README.md](https://github.com/Flash-Brew-Digital/webflow-extension-starter/blob/main/README.md) - [AGENTS.md](https://github.com/Flash-Brew-Digital/webflow-extension-starter/blob/main/AGENTS.md) - [tsconfig.json](https://github.com/Flash-Brew-Digital/webflow-extension-starter/blob/main/tsconfig.json)

# useSelectedElement Hook The `useSelectedElement` hook is a custom React hook designed to subscribe to and retrieve the currently selected element within the Webflow Designer. It provides a reactive way for the extension's UI to update in response to user selections on the Webflow canvas. This hook is a core feature of the starter template, encapsulating the logic for interacting with the Webflow Designer API's selection events. This hook works in tandem with other custom hooks like `useElementSnapshot` to provide a rich, interactive experience. By managing the state of the selected element, it enables other parts of the application to fetch additional details or perform actions based on the user's current context in the Designer. Sources: [src/hooks/use-selected-element.ts](), [README.md:13-14](), [src/app.tsx:5]() ## Implementation Details The hook utilizes React's `useState` and `useEffect` primitives to manage its state and side effects. On component mount, it establishes a subscription to the Webflow Designer's `selectedelement` event. When a user selects an element on the canvas, the event fires, and the hook's callback function is invoked to update the state with the new element object. A crucial part of its implementation is the cleanup function returned by `useEffect`. This function unsubscribes from the event when the component unmounts, preventing memory leaks and ensuring the application behaves correctly. Sources: [src/hooks/use-selected-element.ts:18-25](), [AGENTS.md:110-114]() ### Hook Logic Flow The following diagram illustrates the sequence of events from component mount to state update. ```mermaid sequenceDiagram participant Component as React Component participant Hook as useSelectedElement participant WebflowAPI as Webflow Designer API Component->>Hook: Hook is called during render activate Hook Note over Hook: `element` state is `null` initially deactivate Hook Component-->>Component: Component mounts activate Hook Hook->>WebflowAPI: webflow.subscribe('selectedelement', callback) WebflowAPI-->>Hook: Returns unsubscribe function deactivate Hook Note over WebflowAPI: User selects an element in Designer WebflowAPI->>Hook: Triggers 'selectedelement' event activate Hook Hook->>WebflowAPI: await webflow.getSelectedElement() WebflowAPI-->>Hook: Returns selected element object Hook->>Hook: setElement(el) deactivate Hook Note over Component: React re-renders with new element state Component-->>Component: Component unmounts activate Hook Hook->>WebflowAPI: Calls unsubscribe() deactivate Hook ``` This diagram shows the lifecycle of the `useSelectedElement` hook, including the initial subscription, handling an element selection event, and the final cleanup on unmount. Sources: [src/hooks/use-selected-element.ts:18-25]() ### Return Value The hook returns a single value which is the stateful representation of the selected element. | Value | Type | Description - | :-------- | :------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `element` | `AnyElement | null` | The currently selected Webflow element object, or `null` if no element is selected. The `AnyElement` type is provided by the `@webflow/designer-extension-typings` package. | Sources: [src/hooks/use-selected-element.ts:16, 27](), [tsconfig.json:16]() ### Source Code ```typescript // src/hooks/use-selected-element.ts import { useEffect, useState } from "react"; /** * Subscribes to the currently selected element in the Webflow Designer. * * This hook listens for selection changes and automatically updates * the returned element whenever the user selects a different element. * * @returns The currently selected Webflow element, or `null` if nothing is selected. * * @example * ```tsx * const element = useSelectedElement(); * * if (!element) return

No element selected

; * return

Selected: {element.type}

; * ``` */ export function useSelectedElement() { const [element, setElement] = useState(null); useEffect(() => { const unsubscribe = webflow.subscribe("selectedelement", async () => { const el = await webflow.getSelectedElement(); setElement(el); }); return () => unsubscribe(); }, []); return element; } ``` Sources: [src/hooks/use-selected-element.ts]() ## Usage and Integration The `useSelectedElement` hook is consumed by the main `App` component to drive the UI. The returned `selectedElement` object is used for two main purposes: 1. **Conditional Rendering**: The UI displays different content based on whether an element is selected. If `selectedElement` is `null`, an "empty state" message is shown. Otherwise, a card with details about the element is rendered. 2. **Passing Data to Other Hooks**: The `selectedElement` object is passed as an argument to the `useElementSnapshot` hook, which then fetches a screenshot of that specific element. Sources: [src/app.tsx:5, 8, 59, 79]() ### Data Flow within the Application This diagram shows how data from `useSelectedElement` flows through the application to other components and hooks. ```mermaid graph TD subgraph Webflow Designer A[User Selection] end subgraph React App B(useSelectedElement) C(App Component) D(useElementSnapshot) E[UI: Element Card] F[UI: Empty State] end A -- "Triggers 'selectedelement' event" --> B B -- "Returns 'selectedElement' state" --> C C -- "Passes 'selectedElement' to" --> D C -- "If selectedElement is not null" --> E C -- "If selectedElement is null" --> F D -- "Fetches snapshot for element" --> E ``` This flow demonstrates that `useSelectedElement` acts as the primary source of truth for the user's current selection, enabling other parts of the application to react accordingly. Sources: [src/app.tsx:5, 8, 59](), [src/hooks/use-element-snapshot.ts:100]() ### Example Usage in `App.tsx` ```tsx // src/app.tsx import { useElementSnapshot } from "@/hooks/use-element-snapshot"; import { useSelectedElement } from "@/hooks/use-selected-element"; // ... export function App() { const selectedElement = useSelectedElement(); const { snapshot, isLoading, error } = useElementSnapshot(selectedElement); // ... return ( // ... {selectedElement ? (

Selected Element {selectedElement.type}

{/* ... snapshot rendering logic ... */}

) : (

No element selected Select an element on the canvas to see its type and a screenshot of it here.

)} // ... ); } ``` This snippet from `App.tsx` shows the direct consumption of the hook and how its return value is used for conditional rendering and as an input for the `useElementSnapshot` hook. Sources: [src/app.tsx:2, 5, 8, 59-78]() ## Conclusion The `useSelectedElement` hook is a fundamental building block in this Webflow Extension starter. It cleanly abstracts the subscription logic for the Webflow Designer's selection events into a reusable and declarative React hook. By providing a real-time stream of the user's selected element, it enables the creation of dynamic and context-aware user interfaces that respond instantly to actions within the Webflow Designer. Sources: [README.md:13-14](), [src/hooks/use-selected-element.ts]()