Skip to content

Open source website builder and Webflow alternative. Webstudio is an advanced visual builder that connects to any headless CMS, supports all CSS properties, and can be hosted anywhere, including with us.

experimental: Stagger Animation (#5066)

Ivan Starkov3f5041a974b7
diff --git a/packages/icons/icons/stagger-animation.svg b/packages/icons/icons/stagger-animation.svg
new file mode 100644
index 0000000000..4a88660085
--- /dev/null
+++ b/packages/icons/icons/stagger-animation.svg
@@ -0,0 +1,20 @@
+<svg
+ width="16"
+ height="16"
+ viewBox="0 0 16 16"
+ fill="none"
+ xmlns="http://www.w3.org/2000/svg"
+>
+ <path
+ d="M14.2222 5H8.77778C8.34822 5 8 5.34822 8 5.77778V11.2222C8 11.6518 8.34822 12 8.77778 12H14.2222C14.6518 12 15 11.6518 15 11.2222V5.77778C15 5.34822 14.6518 5 14.2222 5Z"
+ stroke="currentColor"
+ stroke-linecap="round"
+ stroke-linejoin="round"
+ />
+ <path
+ d="M5.44444 6H1.55556C1.24873 6 1 6.24873 1 6.55556V10.4444C1 10.7513 1.24873 11 1.55556 11H5.44444C5.75127 11 6 10.7513 6 10.4444V6.55556C6 6.24873 5.75127 6 5.44444 6Z"
+ stroke="currentColor"
+ stroke-linecap="round"
+ stroke-linejoin="round"
+ />
+</svg>
diff --git a/packages/icons/src/__generated__/components.tsx b/packages/icons/src/__generated__/components.tsx
index f0c017f94b..78bb0e630a 100644
--- a/packages/icons/src/__generated__/components.tsx
+++ b/packages/icons/src/__generated__/components.tsx
@@ -4356,6 +4356,30 @@ export const SpinnerIcon: IconComponent = forwardRef(
);
SpinnerIcon.displayName = "SpinnerIcon";
+export const StaggerAnimationIcon: IconComponent = forwardRef(
+ ({ fill = "none", size = 16, ...props }, forwardedRef) => {
+ return (
+ <svg
+ xmlns="http://www.w3.org/2000/svg"
+ viewBox="0 0 16 16"
+ width={size}
+ height={size}
+ fill={fill}
+ {...props}
+ ref={forwardedRef}
+ >
+ <path
+ stroke="currentColor"
+ strokeLinecap="round"
+ strokeLinejoin="round"
+ d="M14.222 5H8.778A.778.778 0 0 0 8 5.778v5.444c0 .43.348.778.778.778h5.444c.43 0 .778-.348.778-.778V5.778A.778.778 0 0 0 14.222 5ZM5.444 6H1.556A.556.556 0 0 0 1 6.556v3.888c0 .307.249.556.556.556h3.888A.556.556 0 0 0 6 10.444V6.556A.556.556 0 0 0 5.444 6Z"
+ />
+ </svg>
+ );
+ }
+);
+StaggerAnimationIcon.displayName = "StaggerAnimationIcon";
+
export const StopIcon: IconComponent = forwardRef(
({ fill = "none", size = 16, ...props }, forwardedRef) => {
return (
diff --git a/packages/icons/src/__generated__/svg.ts b/packages/icons/src/__generated__/svg.ts
index f7f9447391..1b99efa7ec 100644
--- a/packages/icons/src/__generated__/svg.ts
+++ b/packages/icons/src/__generated__/svg.ts
@@ -320,6 +320,8 @@ export const SlotComponentIcon = `<svg xmlns="http://www.w3.org/2000/svg" fill="
export const SpinnerIcon = `<svg xmlns="http://www.w3.org/2000/svg" id="e2CRglijn891" shape-rendering="geometricPrecision" text-rendering="geometricPrecision" viewBox="0 0 128 128" fill="currentColor" width="100%" height="100%" style="display: block;"><style>@keyframes e2CRglijn892_tr__tr{0%{transform:translate(64px,64px) rotate(90deg);animation-timing-function:cubic-bezier(.42,0,.58,1)}50%{transform:translate(64px,64px) rotate(810deg);animation-timing-function:cubic-bezier(.42,0,.58,1)}to{transform:translate(64px,64px) rotate(1530deg)}}@keyframes e2CRglijn892_s_p{0%,to{stroke:#39fbbb}25%{stroke:#4a4efa}50%{stroke:#e63cfe}75%{stroke:#ffae3c}}@keyframes e2CRglijn892_s_do{0%{stroke-dashoffset:251.89}2.5%,52.5%{stroke-dashoffset:263.88;animation-timing-function:cubic-bezier(.42,0,.58,1)}25%,75%{stroke-dashoffset:131.945}to{stroke-dashoffset:251.885909}}#e2CRglijn892_tr{animation:e2CRglijn892_tr__tr 3000ms linear infinite normal forwards}#e2CRglijn892{animation-name:e2CRglijn892_s_p,e2CRglijn892_s_do;animation-duration:3000ms;animation-fill-mode:forwards;animation-timing-function:linear;animation-direction:normal;animation-iteration-count:infinite}</style><g id="e2CRglijn892_tr" transform="translate(64,64) rotate(90)"><circle id="e2CRglijn892" r="42" fill="none" stroke="#39fbbb" stroke-dasharray="263.89" stroke-dashoffset="251.89" stroke-linecap="round" stroke-width="16" transform="scale(-1,1) translate(0,0)"/></g></svg>`;
+export const StaggerAnimationIcon = `<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 16 16" width="100%" height="100%" style="display: block;"><path stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" d="M14.222 5H8.778A.778.778 0 0 0 8 5.778v5.444c0 .43.348.778.778.778h5.444c.43 0 .778-.348.778-.778V5.778A.778.778 0 0 0 14.222 5ZM5.444 6H1.556A.556.556 0 0 0 1 6.556v3.888c0 .307.249.556.556.556h3.888A.556.556 0 0 0 6 10.444V6.556A.556.556 0 0 0 5.444 6Z"/></svg>`;
+
export const StopIcon = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" fill="currentColor" width="100%" height="100%" style="display: block;"><rect width="9" height="9" x="3.5" y="3.5" fill="currentColor" rx="1"/></svg>`;
export const StretchVerticalIcon = `<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 16 16" width="100%" height="100%" style="display: block;"><path stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" d="M5.4 4.097H4.1c-.72 0-1.302.582-1.302 1.3v7.807c0 .719.583 1.301 1.301 1.301H5.4c.719 0 1.301-.582 1.301-1.3V5.397c0-.719-.582-1.301-1.3-1.301ZM11.906 4.097h-1.301c-.719 0-1.301.582-1.301 1.3v3.254c0 .718.582 1.3 1.3 1.3h1.302c.718 0 1.3-.582 1.3-1.3V5.398c0-.719-.582-1.301-1.3-1.301ZM14.497 1.495h-13"/></svg>`;
diff --git a/packages/sdk-components-animation/private-src b/packages/sdk-components-animation/private-src
index c699f5968c..7c4f1daec2 160000
--- a/packages/sdk-components-animation/private-src
+++ b/packages/sdk-components-animation/private-src
@@ -1 +1 @@
-Subproject commit c699f5968c7a36ab2bb2334829537c58ecce664a
+Subproject commit 7c4f1daec2e5c8b7d50aea5f6f01cf566f37ccef
diff --git a/packages/sdk-components-animation/src/__generated__/animate-text.props.ts b/packages/sdk-components-animation/src/__generated__/animate-text.props.ts
index 24c6bebe02..dfb460d710 100644
--- a/packages/sdk-components-animation/src/__generated__/animate-text.props.ts
+++ b/packages/sdk-components-animation/src/__generated__/animate-text.props.ts
@@ -2,6 +2,7 @@ import type { PropMeta } from "@webstudio-is/sdk";
export const props: Record<string, PropMeta> = {
easing: {
+ description: "Easing function applied within the sliding window.",
required: false,
control: "select",
type: "string",
@@ -20,12 +21,16 @@ export const props: Record<string, PropMeta> = {
],
},
slidingWindow: {
+ description:
+ "Size of the sliding window for the animation:\n- 0: Typewriter effect (no animation).\n- (0..1]: Animates one part of the text at a time.\n- (1..n]: Animates multiple parts of the text within the sliding window.",
required: false,
control: "number",
type: "number",
defaultValue: 5,
},
splitBy: {
+ description:
+ "Defines how the text is split for animation (e.g., by character, space, or symbol).",
required: false,
control: "select",
type: "string",
diff --git a/packages/sdk-components-animation/src/__generated__/stagger-animation.props.ts b/packages/sdk-components-animation/src/__generated__/stagger-animation.props.ts
new file mode 100644
index 0000000000..cefe2e8777
--- /dev/null
+++ b/packages/sdk-components-animation/src/__generated__/stagger-animation.props.ts
@@ -0,0 +1,31 @@
+import type { PropMeta } from "@webstudio-is/sdk";
+
+export const props: Record<string, PropMeta> = {
+ easing: {
+ description: "Easing function applied within the sliding window.",
+ required: false,
+ control: "select",
+ type: "string",
+ defaultValue: "linear",
+ options: [
+ "linear",
+ "easeIn",
+ "easeInCubic",
+ "easeInQuart",
+ "easeOut",
+ "easeOutCubic",
+ "easeOutQuart",
+ "ease",
+ "easeInOutCubic",
+ "easeInOutQuart",
+ ],
+ },
+ slidingWindow: {
+ description:
+ "Size of the sliding window for the animation:\n- 0: Typewriter effect (no animation).\n- (0..1]: Animates one child at a time.\n- (1..n]: Animates multiple children within the sliding window.",
+ required: false,
+ control: "number",
+ type: "number",
+ defaultValue: 1,
+ },
+};
diff --git a/packages/sdk-components-animation/src/animate-text.tsx b/packages/sdk-components-animation/src/animate-text.tsx
index c83c5b2a45..2d82c944f5 100644
--- a/packages/sdk-components-animation/src/animate-text.tsx
+++ b/packages/sdk-components-animation/src/animate-text.tsx
@@ -21,9 +21,24 @@ const split = {
};
type AnimateChildrenProps = {
+ /**
+ * Size of the sliding window for the animation:
+ * - 0: Typewriter effect (no animation).
+ * - (0..1]: Animates one part of the text at a time.
+ * - (1..n]: Animates multiple parts of the text within the sliding window.
+ */
slidingWindow?: number;
+ /**
+ * Easing function applied within the sliding window.
+ */
easing?: keyof typeof easings;
+ /**
+ * Text content to animate.
+ */
children: React.ReactNode;
+ /**
+ * Defines how the text is split for animation (e.g., by character, space, or symbol).
+ */
splitBy?: keyof typeof split;
};
diff --git a/packages/sdk-components-animation/src/components.ts b/packages/sdk-components-animation/src/components.ts
index ee855f0ad1..5ef758a6e2 100644
--- a/packages/sdk-components-animation/src/components.ts
+++ b/packages/sdk-components-animation/src/components.ts
@@ -1,2 +1,3 @@
export { AnimateChildren } from "./animate-children";
export { AnimateText } from "./animate-text";
+export { StaggerAnimation } from "./stagger-animation";
diff --git a/packages/sdk-components-animation/src/metas.ts b/packages/sdk-components-animation/src/metas.ts
index 1f24252cfc..c85691298d 100644
--- a/packages/sdk-components-animation/src/metas.ts
+++ b/packages/sdk-components-animation/src/metas.ts
@@ -1,2 +1,3 @@
export { meta as AnimateChildren } from "./animate-children.ws";
export { meta as AnimateText } from "./animate-text.ws";
+export { meta as StaggerAnimation } from "./stagger-animation.ws";
diff --git a/packages/sdk-components-animation/src/props.ts b/packages/sdk-components-animation/src/props.ts
index 9f32425fcc..ebb43716c7 100644
--- a/packages/sdk-components-animation/src/props.ts
+++ b/packages/sdk-components-animation/src/props.ts
@@ -1,2 +1,3 @@
export { propsMeta as AnimateChildren } from "./animate-children.ws";
export { propsMeta as AnimateText } from "./animate-text.ws";
+export { propsMeta as StaggerAnimation } from "./stagger-animation.ws";
diff --git a/packages/sdk-components-animation/src/stagger-animation.tsx b/packages/sdk-components-animation/src/stagger-animation.tsx
new file mode 100644
index 0000000000..e3ae0bca47
--- /dev/null
+++ b/packages/sdk-components-animation/src/stagger-animation.tsx
@@ -0,0 +1,43 @@
+import { forwardRef, type ElementRef } from "react";
+
+const easings = {
+ linear: true,
+ easeIn: true,
+ easeInCubic: true,
+ easeInQuart: true,
+ easeOut: true,
+ easeOutCubic: true,
+ easeOutQuart: true,
+ ease: true,
+ easeInOutCubic: true,
+ easeInOutQuart: true,
+};
+
+type StaggerAnimationProps = {
+ /**
+ * Size of the sliding window for the animation:
+ * - 0: Typewriter effect (no animation).
+ * - (0..1]: Animates one child at a time.
+ * - (1..n]: Animates multiple children within the sliding window.
+ */
+ slidingWindow?: number;
+ /**
+ * Easing function applied within the sliding window.
+ */
+ easing?: keyof typeof easings;
+ /**
+ * Text content to animate.
+ */
+ children: React.ReactNode;
+};
+
+export const StaggerAnimation = forwardRef<
+ ElementRef<"div">,
+ StaggerAnimationProps
+>(({ slidingWindow = 1, easing = "linear", ...props }, ref) => {
+ // Implementation is located in private-src
+ return <div ref={ref} {...props} />;
+});
+
+const displayName = "StaggerAnimation";
+StaggerAnimation.displayName = displayName;
diff --git a/packages/sdk-components-animation/src/stagger-animation.ws.ts b/packages/sdk-components-animation/src/stagger-animation.ws.ts
new file mode 100644
index 0000000000..f8b18f779d
--- /dev/null
+++ b/packages/sdk-components-animation/src/stagger-animation.ws.ts
@@ -0,0 +1,25 @@
+import { StaggerAnimationIcon } from "@webstudio-is/icons/svg";
+import type { WsComponentMeta, WsComponentPropsMeta } from "@webstudio-is/sdk";
+import { props } from "./__generated__/stagger-animation.props";
+
+export const meta: WsComponentMeta = {
+ category: "animations",
+ type: "container",
+ description:
+ "Stagger animation allows you to animate children elements with a sliding window.",
+ icon: StaggerAnimationIcon,
+ order: 6,
+ label: "Stagger Animation",
+ constraints: [
+ { relation: "parent", component: { $eq: "AnimateChildren" } },
+ {
+ relation: "child",
+ text: false,
+ },
+ ],
+};
+
+export const propsMeta: WsComponentPropsMeta = {
+ props,
+ initialProps: ["slidingWindow", "easing"],
+};