diff --git a/.changeset/toolbar-self-injects-styles.md b/.changeset/toolbar-self-injects-styles.md
new file mode 100644
index 000000000..383511c6c
--- /dev/null
+++ b/.changeset/toolbar-self-injects-styles.md
@@ -0,0 +1,7 @@
+---
+"@knocklabs/react": patch
+---
+
+fix(KNO-14012): guide toolbar no longer requires importing `@knocklabs/react/dist/index.css`
+
+The guide toolbar previously rendered unstyled (or with frankenstein styling) unless the consuming app imported `@knocklabs/react/dist/index.css`. Apps that only render custom guide components have no reason to import that stylesheet, so the toolbar broke for them. The toolbar now injects its compiled styles into the document head at runtime when it becomes visible, making it plug and play without an explicit CSS import. When `dist/index.css` is imported anyway, the injected rules are identical duplicates and have no effect.
diff --git a/packages/react/src/modules/guide/components/Toolbar/V2/V2.tsx b/packages/react/src/modules/guide/components/Toolbar/V2/V2.tsx
index 9065f76c3..43c5ec47a 100644
--- a/packages/react/src/modules/guide/components/Toolbar/V2/V2.tsx
+++ b/packages/react/src/modules/guide/components/Toolbar/V2/V2.tsx
@@ -19,6 +19,7 @@ import React from "react";
import { KnockButton } from "../KnockButton";
import { TOOLBAR_Z_INDEX } from "../shared";
import "../styles.css";
+import { useToolbarStyles } from "../useToolbarStyles";
import { FocusChin } from "./FocusChin";
import { GuideContextDetails } from "./GuideContextDetails";
@@ -90,6 +91,8 @@ export const V2 = ({ readyToTarget, listenForUpdates }: Props) => {
string | undefined
>();
+ useToolbarStyles(Boolean(runConfig?.isVisible));
+
React.useEffect(() => {
setExpandedGuideRowKey(undefined);
}, [displayOption]);
diff --git a/packages/react/src/modules/guide/components/Toolbar/useToolbarStyles.ts b/packages/react/src/modules/guide/components/Toolbar/useToolbarStyles.ts
new file mode 100644
index 000000000..15dcfe618
--- /dev/null
+++ b/packages/react/src/modules/guide/components/Toolbar/useToolbarStyles.ts
@@ -0,0 +1,21 @@
+import React from "react";
+
+import toolbarStyles from "./styles.css?inline";
+
+const STYLE_ELEMENT_ID = "knock-guide-toolbar-styles";
+
+// The toolbar's styles are bundled into dist/index.css, but consumers who only
+// render custom guide components have no reason to import that stylesheet.
+// Inject the toolbar's compiled styles at runtime when it becomes visible, so
+// the toolbar works without an explicit CSS import. When dist/index.css is
+// imported anyway, the injected rules are identical duplicates and harmless.
+export const useToolbarStyles = (enabled: boolean) => {
+ React.useEffect(() => {
+ if (!enabled || document.getElementById(STYLE_ELEMENT_ID)) return;
+
+ const styleElement = document.createElement("style");
+ styleElement.id = STYLE_ELEMENT_ID;
+ styleElement.textContent = toolbarStyles;
+ document.head.appendChild(styleElement);
+ }, [enabled]);
+};
diff --git a/packages/react/test/guide/Toolbar/V2/V2.test.tsx b/packages/react/test/guide/Toolbar/V2/V2.test.tsx
new file mode 100644
index 000000000..2ea3e017e
--- /dev/null
+++ b/packages/react/test/guide/Toolbar/V2/V2.test.tsx
@@ -0,0 +1,56 @@
+import { render } from "@testing-library/react";
+import { afterEach, describe, expect, test, vi } from "vitest";
+
+import { V2 } from "../../../../src/modules/guide/components/Toolbar/V2/V2";
+
+vi.mock("@knocklabs/react-core", async () => {
+ const actual = await vi.importActual("@knocklabs/react-core");
+ return {
+ ...actual,
+ useGuideContext: () => ({
+ client: {
+ store: { state: {} },
+ setDebug: vi.fn(),
+ unsetDebug: vi.fn(),
+ },
+ }),
+ };
+});
+
+vi.mock(
+ "../../../../src/modules/guide/components/Toolbar/V2/useInspectGuideClientStore",
+ async () => {
+ const actual = await vi.importActual(
+ "../../../../src/modules/guide/components/Toolbar/V2/useInspectGuideClientStore",
+ );
+ return {
+ ...actual,
+ useInspectGuideClientStore: () => null,
+ };
+ },
+);
+
+const getStyleElement = () =>
+ document.getElementById("knock-guide-toolbar-styles");
+
+afterEach(() => {
+ getStyleElement()?.remove();
+ window.history.replaceState({}, "", "/");
+});
+
+describe("Toolbar V2", () => {
+ test("injects toolbar styles when launched via the toolbar url param", () => {
+ window.history.replaceState({}, "", "/?knock_guide_toolbar=true");
+
+ render();
+
+ expect(getStyleElement()).not.toBeNull();
+ expect(getStyleElement()?.parentElement).toBe(document.head);
+ });
+
+ test("does not inject toolbar styles without the toolbar url param", () => {
+ render();
+
+ expect(getStyleElement()).toBeNull();
+ });
+});
diff --git a/packages/react/test/guide/Toolbar/useToolbarStyles.test.ts b/packages/react/test/guide/Toolbar/useToolbarStyles.test.ts
new file mode 100644
index 000000000..b654ed1e8
--- /dev/null
+++ b/packages/react/test/guide/Toolbar/useToolbarStyles.test.ts
@@ -0,0 +1,44 @@
+import { renderHook } from "@testing-library/react";
+import { afterEach, describe, expect, test } from "vitest";
+
+import { useToolbarStyles } from "../../../src/modules/guide/components/Toolbar/useToolbarStyles";
+
+const getStyleElement = () =>
+ document.getElementById("knock-guide-toolbar-styles");
+
+afterEach(() => {
+ getStyleElement()?.remove();
+});
+
+describe("useToolbarStyles", () => {
+ test("does not inject styles when disabled", () => {
+ renderHook(() => useToolbarStyles(false));
+ expect(getStyleElement()).toBeNull();
+ });
+
+ test("injects a style element into the document head when enabled", () => {
+ renderHook(() => useToolbarStyles(true));
+ const styleElement = getStyleElement();
+ expect(styleElement).not.toBeNull();
+ expect(styleElement?.parentElement).toBe(document.head);
+ });
+
+ test("injects styles once it becomes enabled", () => {
+ const { rerender } = renderHook(
+ ({ enabled }) => useToolbarStyles(enabled),
+ { initialProps: { enabled: false } },
+ );
+ expect(getStyleElement()).toBeNull();
+
+ rerender({ enabled: true });
+ expect(getStyleElement()).not.toBeNull();
+ });
+
+ test("injects only one style element across multiple instances", () => {
+ renderHook(() => useToolbarStyles(true));
+ renderHook(() => useToolbarStyles(true));
+ expect(
+ document.querySelectorAll("#knock-guide-toolbar-styles"),
+ ).toHaveLength(1);
+ });
+});