@whop/elements 0.0.0 → 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Whop, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,29 @@
+# @whop/elements
+
+Embed Whop in any site. Elements are hosted, themeable UI components across Whop's
+product surface, with the catalog growing steadily. This package is a tiny loader plus
+the full typed API: the element code itself is served from Whop's CDN and stays up to
+date without you re-installing anything.
+
+```ts
+import { loadWhop } from '@whop/elements';
+
+const whop = (await loadWhop())({ locale: 'en' });
+```
+
+Every element group hangs off the instance — create a handle, mount elements, listen to
+events. The full catalog, live demos, and per-element API live in the docs.
+
+Or warm the script from your document head:
+
+```ts
+import { preloadHints } from '@whop/elements';
+// render as <link> tags: [{ rel: 'preconnect', ... }, { rel: 'preload', ... }]
+```
+
+Using React? [`@whop/elements-react`](https://www.npmjs.com/package/@whop/elements-react)
+wraps the same elements as components.
+
+## Documentation
+
+https://docs.whop.com/elements/latest

package/_framework.d.cts

@@ -0,0 +1,179 @@
+/** The locales this app's elements are built with (the default locale first) — element UI
+ *  text ships in each of these. Any other value falls back to the default locale. Validate
+ *  dynamic strings with `WHOP_ELEMENTS_LOCALES.includes(...)` from the package root. */
+export type WhopElementsLocale = "en" | "es" | "zh" | "nl" | "pt" | "de" | "it" | "fr" | "ja" | "pl" | "tr";
+
+/**
+ * A CSS property value, as a string (include units: `"12px"`, not `12`).
+ */
+export type CSSValue = string;
+
+/**
+ * A style declaration object that maps CSS properties to values, like React's `CSSProperties`.
+ * Property names can use camel case (`fontWeight`) or kebab case (`font-weight`). The framework
+ * normalizes each name and checks it against the list of safe properties before applying it.
+ */
+export type CSSProps = Record<string, CSSValue>;
+
+/**
+ * Style declarations for each `whop-*` class name. Each entry restyles one documented part of an
+ * element. See the Styling section on each element page for its class list. The framework checks
+ * each declaration, then injects the sanitized result inside the element's frame because page
+ * stylesheets cannot reach it.
+ *
+ * @example
+ * ```typescript
+ * classes: {
+ *   "whop-TipSummary": { fontWeight: "600", borderRadius: "8px" },
+ * }
+ * ```
+ */
+export type Classes = Record<string, CSSProps>;
+
+/**
+ * CSS custom properties (variables) that can be used to customize element styles.
+ * Keys must start with `--` prefix.
+ */
+export type Variables = Record<`--${string}`, string>;
+
+/**
+ * Available accent colors for theming elements.
+ *
+ * These colors are used for primary UI elements like buttons, links, and highlights.
+ */
+export type AccentColor =
+	| "ruby"
+	| "blue"
+	| "red"
+	| "yellow"
+	| "green"
+	| "gray"
+	| "tomato"
+	| "crimson"
+	| "pink"
+	| "plum"
+	| "purple"
+	| "violet"
+	| "iris"
+	| "cyan"
+	| "teal"
+	| "jade"
+	| "grass"
+	| "brown"
+	| "orange"
+	| "indigo"
+	| "sky"
+	| "mint"
+	| "amber"
+	| "lime"
+	| "lemon"
+	| "magenta"
+	| "gold"
+	| "bronze";
+
+/**
+ * Theme configuration for customizing the visual appearance of elements.
+ *
+ * @example
+ * ```typescript
+ * const theme: Theme = {
+ *   appearance: "dark",
+ *   accentColor: "blue",
+ *   grayColor: "slate",
+ * };
+ * ```
+ */
+export type Theme = {
+	/**
+	 * The color scheme to use.
+	 * - `"light"` - Light mode with dark text on light backgrounds
+	 * - `"dark"` - Dark mode with light text on dark backgrounds
+	 */
+	appearance?: "light" | "dark";
+	/**
+	 * The primary accent color used for interactive elements.
+	 */
+	accentColor?: AccentColor;
+	/**
+	 * The gray color palette to use for neutral elements.
+	 * Use `"auto"` to automatically match the accent color.
+	 */
+	grayColor?: "gray" | "mauve" | "slate" | "sage" | "olive" | "sand" | "auto";
+	/**
+	 * The color used for error states and destructive actions.
+	 */
+	dangerColor?: "ruby" | "red" | "tomato";
+	/**
+	 * The color used for warning states.
+	 */
+	warningColor?: "yellow" | "amber";
+	/**
+	 * The color used for success states.
+	 */
+	successColor?: "green" | "teal" | "jade" | "grass";
+	/**
+	 * The color used for informational states.
+	 */
+	infoColor?: "sky" | "blue";
+};
+
+/**
+ * Configuration for customizing the visual appearance of Whop elements.
+ *
+ * Use this to match the embedded components to your application's design.
+ *
+ * @example
+ * ```typescript
+ * const appearance: Appearance = {
+ *   theme: {
+ *     appearance: "dark",
+ *     accentColor: "blue",
+ *   },
+ * };
+ *
+ * const whopElements = WhopElements({ appearance });
+ * ```
+ */
+export type Appearance = {
+	/**
+	 * CSS custom properties to override default styles.
+	 */
+	variables?: Variables | null;
+	/**
+	 * Custom CSS classes to apply to elements.
+	 */
+	classes?: Classes | null;
+	/**
+	 * Theme settings for colors and appearance mode.
+	 */
+	theme?: Theme | null;
+};
+
+/**
+ * Framework-provided global config — NOT authored. Set on `WhopElements(config)` and
+ * delivered by the framework: `theme`/`locale` ride the iframe URL params (so the boot
+ * script applies them before first paint — anti-flash), `appearance` rides `init`, and
+ * `baseUrl` selects the element origin. Merged with any Root app globals (currently none).
+ */
+export interface FrameworkGlobals {
+	/** Visual customization for every element — `theme` (light/dark + palettes), `variables`
+	 *  (CSS custom properties), and `classes` (per-part style declarations). The color scheme is
+	 *  applied before an element's first paint, so dark pages never flash light. */
+	appearance?: Appearance;
+	/** Locale for element UI text — one of the app's built locales; any other value falls back
+	 *  to the default locale. @default "en" */
+	locale?: WhopElementsLocale;
+	/** Which Whop API environment the elements talk to — `"sandbox"` targets the sandbox API
+	 *  (test data; no real money moves). Choosing an environment is the only way to change where
+	 *  the elements send what a buyer types, and both environments are Whop's own. The sandbox
+	 *  environment is not yet generally available. @default "production" */
+	environment?: "production" | "sandbox";
+	/** Whether elements may show toast notifications on your page — brief status messages
+	 *  ("Payment method added", "Payment failed") rendered in the bottom-right corner. Set
+	 *  `false` to turn them off entirely. @default true */
+	toasts?: boolean;
+	/** Origin serving the hosted element pages — for testing against a different environment.
+	 *  Cannot change after load.
+	 *  @internal */
+	baseUrl?: string;
+}

package/_framework.d.ts

@@ -0,0 +1,179 @@
+/** The locales this app's elements are built with (the default locale first) — element UI
+ *  text ships in each of these. Any other value falls back to the default locale. Validate
+ *  dynamic strings with `WHOP_ELEMENTS_LOCALES.includes(...)` from the package root. */
+export type WhopElementsLocale = "en" | "es" | "zh" | "nl" | "pt" | "de" | "it" | "fr" | "ja" | "pl" | "tr";
+
+/**
+ * A CSS property value, as a string (include units: `"12px"`, not `12`).
+ */
+export type CSSValue = string;
+
+/**
+ * A style declaration object that maps CSS properties to values, like React's `CSSProperties`.
+ * Property names can use camel case (`fontWeight`) or kebab case (`font-weight`). The framework
+ * normalizes each name and checks it against the list of safe properties before applying it.
+ */
+export type CSSProps = Record<string, CSSValue>;
+
+/**
+ * Style declarations for each `whop-*` class name. Each entry restyles one documented part of an
+ * element. See the Styling section on each element page for its class list. The framework checks
+ * each declaration, then injects the sanitized result inside the element's frame because page
+ * stylesheets cannot reach it.
+ *
+ * @example
+ * ```typescript
+ * classes: {
+ *   "whop-TipSummary": { fontWeight: "600", borderRadius: "8px" },
+ * }
+ * ```
+ */
+export type Classes = Record<string, CSSProps>;
+
+/**
+ * CSS custom properties (variables) that can be used to customize element styles.
+ * Keys must start with `--` prefix.
+ */
+export type Variables = Record<`--${string}`, string>;
+
+/**
+ * Available accent colors for theming elements.
+ *
+ * These colors are used for primary UI elements like buttons, links, and highlights.
+ */
+export type AccentColor =
+	| "ruby"
+	| "blue"
+	| "red"
+	| "yellow"
+	| "green"
+	| "gray"
+	| "tomato"
+	| "crimson"
+	| "pink"
+	| "plum"
+	| "purple"
+	| "violet"
+	| "iris"
+	| "cyan"
+	| "teal"
+	| "jade"
+	| "grass"
+	| "brown"
+	| "orange"
+	| "indigo"
+	| "sky"
+	| "mint"
+	| "amber"
+	| "lime"
+	| "lemon"
+	| "magenta"
+	| "gold"
+	| "bronze";
+
+/**
+ * Theme configuration for customizing the visual appearance of elements.
+ *
+ * @example
+ * ```typescript
+ * const theme: Theme = {
+ *   appearance: "dark",
+ *   accentColor: "blue",
+ *   grayColor: "slate",
+ * };
+ * ```
+ */
+export type Theme = {
+	/**
+	 * The color scheme to use.
+	 * - `"light"` - Light mode with dark text on light backgrounds
+	 * - `"dark"` - Dark mode with light text on dark backgrounds
+	 */
+	appearance?: "light" | "dark";
+	/**
+	 * The primary accent color used for interactive elements.
+	 */
+	accentColor?: AccentColor;
+	/**
+	 * The gray color palette to use for neutral elements.
+	 * Use `"auto"` to automatically match the accent color.
+	 */
+	grayColor?: "gray" | "mauve" | "slate" | "sage" | "olive" | "sand" | "auto";
+	/**
+	 * The color used for error states and destructive actions.
+	 */
+	dangerColor?: "ruby" | "red" | "tomato";
+	/**
+	 * The color used for warning states.
+	 */
+	warningColor?: "yellow" | "amber";
+	/**
+	 * The color used for success states.
+	 */
+	successColor?: "green" | "teal" | "jade" | "grass";
+	/**
+	 * The color used for informational states.
+	 */
+	infoColor?: "sky" | "blue";
+};
+
+/**
+ * Configuration for customizing the visual appearance of Whop elements.
+ *
+ * Use this to match the embedded components to your application's design.
+ *
+ * @example
+ * ```typescript
+ * const appearance: Appearance = {
+ *   theme: {
+ *     appearance: "dark",
+ *     accentColor: "blue",
+ *   },
+ * };
+ *
+ * const whopElements = WhopElements({ appearance });
+ * ```
+ */
+export type Appearance = {
+	/**
+	 * CSS custom properties to override default styles.
+	 */
+	variables?: Variables | null;
+	/**
+	 * Custom CSS classes to apply to elements.
+	 */
+	classes?: Classes | null;
+	/**
+	 * Theme settings for colors and appearance mode.
+	 */
+	theme?: Theme | null;
+};
+
+/**
+ * Framework-provided global config — NOT authored. Set on `WhopElements(config)` and
+ * delivered by the framework: `theme`/`locale` ride the iframe URL params (so the boot
+ * script applies them before first paint — anti-flash), `appearance` rides `init`, and
+ * `baseUrl` selects the element origin. Merged with any Root app globals (currently none).
+ */
+export interface FrameworkGlobals {
+	/** Visual customization for every element — `theme` (light/dark + palettes), `variables`
+	 *  (CSS custom properties), and `classes` (per-part style declarations). The color scheme is
+	 *  applied before an element's first paint, so dark pages never flash light. */
+	appearance?: Appearance;
+	/** Locale for element UI text — one of the app's built locales; any other value falls back
+	 *  to the default locale. @default "en" */
+	locale?: WhopElementsLocale;
+	/** Which Whop API environment the elements talk to — `"sandbox"` targets the sandbox API
+	 *  (test data; no real money moves). Choosing an environment is the only way to change where
+	 *  the elements send what a buyer types, and both environments are Whop's own. The sandbox
+	 *  environment is not yet generally available. @default "production" */
+	environment?: "production" | "sandbox";
+	/** Whether elements may show toast notifications on your page — brief status messages
+	 *  ("Payment method added", "Payment failed") rendered in the bottom-right corner. Set
+	 *  `false` to turn them off entirely. @default true */
+	toasts?: boolean;
+	/** Origin serving the hosted element pages — for testing against a different environment.
+	 *  Cannot change after load.
+	 *  @internal */
+	baseUrl?: string;
+}