feat(presence): add support skipping initial

packages/react/CHANGELOG.md

@@ -6,6 +6,11 @@ description: All notable changes will be documented in this file.
 
 ## [Unreleased]
 
+### Added
+
+- **Presence**: Added support for skipping the initial animation when the component is mounted. This can be used in all
+  disclosure components (e.g., `Dialog`, `DatePicker`, `Menu` etc).
+
 ## [5.4.0] - 2025-03-28
 
 ### Added

packages/react/src/components/presence/examples/skip-animation-on-mount.tsx

@@ -0,0 +1,16 @@
+import { Presence } from '@ark-ui/react/presence'
+import { useState } from 'react'
+
+export const SkipAnimationOnMount = () => {
+  const [present, setPresent] = useState(true)
+  return (
+    <>
+      <button type="button" onClick={() => setPresent(!present)}>
+        Toggle
+      </button>
+      <Presence present={present} skipAnimationOnMount>
+        Content
+      </Presence>
+    </>
+  )
+}

packages/react/src/components/presence/presence.stories.tsx

@@ -9,4 +9,5 @@ export default meta
 export { Basic } from './examples/basic'
 export { LazyMount } from './examples/lazy-mount'
 export { LazyMountAndUnmountOnExit } from './examples/lazy-mount-and-unmount-on-exit'
+export { SkipAnimationOnMount } from './examples/skip-animation-on-mount'
 export { UnmountOnExit } from './examples/unmount-on-exit'

packages/react/src/components/presence/split-presence-props.ts

@@ -2,4 +2,11 @@ import { createSplitProps } from '../../utils/create-split-props'
 import type { UsePresenceProps } from './use-presence'
 
 export const splitPresenceProps = <T extends UsePresenceProps>(props: T) =>
-  createSplitProps<UsePresenceProps>()(props, ['immediate', 'lazyMount', 'onExitComplete', 'present', 'unmountOnExit'])
+  createSplitProps<UsePresenceProps>()(props, [
+    'immediate',
+    'lazyMount',
+    'onExitComplete',
+    'present',
+    'skipAnimationOnMount',
+    'unmountOnExit',
+  ])

packages/react/src/components/presence/use-presence.ts

@@ -5,11 +5,17 @@ import type { Optional } from '../../types'
 import type { RenderStrategyProps } from '../../utils/render-strategy'
 import { useEvent } from '../../utils/use-event'
 
-export interface UsePresenceProps extends Optional<presence.Props, 'present'>, RenderStrategyProps {}
+export interface UsePresenceProps extends Optional<presence.Props, 'present'>, RenderStrategyProps {
+  /**
+   * Whether to allow the initial presence animation.
+   * @default false
+   */
+  skipAnimationOnMount?: boolean
+}
 export type UsePresenceReturn = ReturnType<typeof usePresence>
 
 export const usePresence = (props: UsePresenceProps = {}) => {
-  const { lazyMount, unmountOnExit, present, ...rest } = props
+  const { lazyMount, unmountOnExit, present, skipAnimationOnMount = false, ...rest } = props
   const wasEverPresent = useRef(false)
   const machineProps: Partial<presence.Props> = {
     ...rest,
@@ -28,7 +34,7 @@ export const usePresence = (props: UsePresenceProps = {}) => {
     (!api.present && !wasEverPresent.current && lazyMount) || (unmountOnExit && !api.present && wasEverPresent.current)
 
   const getPresenceProps = () => ({
-    'data-state': present ? 'open' : 'closed',
+    'data-state': api.skip && skipAnimationOnMount ? undefined : present ? 'open' : 'closed',
     hidden: !api.present,
   })
 

packages/solid/CHANGELOG.md

@@ -6,6 +6,11 @@ description: All notable changes will be documented in this file.
 
 ## [Unreleased]
 
+### Added
+
+- **Presence**: Added support for skipping the initial animation when the component is mounted. This can be used in all
+  disclosure components (e.g., `Dialog`, `DatePicker`, `Menu` etc).
+
 ## [5.4.0] - 2025-03-28
 
 ### Added

packages/solid/src/components/presence/examples/skip-animation-on-mount.tsx

@@ -0,0 +1,17 @@
+import { Presence } from '@ark-ui/solid/presence'
+import { createSignal } from 'solid-js'
+
+export const SkipAnimationOnMount = () => {
+  const [present, setPresent] = createSignal(true)
+
+  return (
+    <>
+      <button type="button" onClick={() => setPresent(!present)}>
+        Toggle
+      </button>
+      <Presence present={present()} skipAnimationOnMount>
+        Content
+      </Presence>
+    </>
+  )
+}

packages/solid/src/components/presence/presence.stories.tsx

@@ -9,4 +9,5 @@ export default meta
 export { Basic } from './examples/basic'
 export { LazyMount } from './examples/lazy-mount'
 export { LazyMountAndUnmountOnExit } from './examples/lazy-mount-and-unmount-on-exit'
+export { SkipAnimationOnMount } from './examples/skip-animation-on-mount'
 export { UnmountOnExit } from './examples/unmount-on-exit'

packages/solid/src/components/presence/split-presence-props.ts

@@ -2,4 +2,11 @@ import { createSplitProps } from '../../utils/create-split-props'
 import type { UsePresenceProps } from './use-presence'
 
 export const splitPresenceProps = <T extends UsePresenceProps>(props: T) =>
-  createSplitProps<UsePresenceProps>()(props, ['immediate', 'lazyMount', 'onExitComplete', 'present', 'unmountOnExit'])
+  createSplitProps<UsePresenceProps>()(props, [
+    'immediate',
+    'lazyMount',
+    'onExitComplete',
+    'present',
+    'skipAnimationOnMount',
+    'unmountOnExit',
+  ])

packages/solid/src/components/presence/use-presence.ts

@@ -5,11 +5,17 @@ import type { MaybeAccessor, Optional } from '../../types'
 import { type RenderStrategyProps, splitRenderStrategyProps } from '../../utils/render-strategy'
 import { runIfFn } from '../../utils/run-if-fn'
 
-export interface UsePresenceProps extends Optional<presence.Props, 'present'>, RenderStrategyProps {}
+export interface UsePresenceProps extends Optional<presence.Props, 'present'>, RenderStrategyProps {
+  /**
+   * Whether to allow the initial presence animation.
+   * @default false
+   */
+  skipAnimationOnMount?: boolean
+}
 export interface UsePresenceReturn extends ReturnType<typeof usePresence> {}
 
 export const usePresence = (props: MaybeAccessor<UsePresenceProps>) => {
-  const [renderStrategyProps, context] = splitRenderStrategyProps(runIfFn(props))
+  const [renderStrategyProps, localProps] = splitRenderStrategyProps(runIfFn(props))
   const [wasEverPresent, setWasEverPresent] = createSignal(false)
 
   const service = useMachine(presence.machine, props)
@@ -28,7 +34,7 @@ export const usePresence = (props: MaybeAccessor<UsePresenceProps>) => {
     ref: api().setNode,
     presenceProps: {
       hidden: !api().present,
-      'data-state': context.present ? 'open' : 'closed',
+      'data-state': api().skip && localProps.skipAnimationOnMount ? undefined : localProps.present ? 'open' : 'closed',
     },
   }))
 }

packages/svelte/package.json

@@ -49,7 +49,7 @@
   },
   "scripts": {
     "build": "svelte-kit sync && svelte-package",
-    "dev": "vite dev",
+    "dev": "storybook dev -p 6006",
     "storybook": "storybook dev -p 6006",
     "test": "vitest",
     "test:coverage": "vitest run --coverage",

packages/svelte/src/lib/components/presence/examples/skip-animation-on-mount.svelte

@@ -0,0 +1,14 @@
+<script lang="ts">
+  import { Presence, type PresenceProps } from '@ark-ui/svelte/presence'
+
+  const props: PresenceProps = $props()
+  let present = $state(true)
+
+  function toggle() {
+    present = !present
+  }
+</script>
+
+<button onclick={toggle}>Toggle</button>
+
+<Presence {...props} {present} skipAnimationOnMount>Content</Presence>

packages/svelte/src/lib/components/presence/presence.stories.ts

@@ -2,6 +2,7 @@ import type { Meta } from '@storybook/svelte'
 import BasicExample from './examples/basic.svelte'
 import LazyMountAndUnmountOnExitExample from './examples/lazy-mount-and-unmount-on-exit.svelte'
 import LazyMountExample from './examples/lazy-mount.svelte'
+import SkipAnimationOnMountExample from './examples/skip-animation-on-mount.svelte'
 import UnmountOnExitExample from './examples/unmount-on-exit.svelte'
 
 const meta = {
@@ -33,3 +34,9 @@ export const LazyMountAndUnmountOnExit = {
     Component: LazyMountAndUnmountOnExitExample,
   }),
 }
+
+export const SkipAnimationOnMount = {
+  render: () => ({
+    Component: SkipAnimationOnMountExample,
+  }),
+}

packages/svelte/src/lib/components/presence/split-presence-props.svelte.ts

@@ -2,4 +2,11 @@ import { createSplitProps } from '$lib/utils/create-split-props'
 import type { UsePresenceProps } from './use-presence.svelte'
 
 export const splitPresenceProps = <T extends UsePresenceProps>(props: T) =>
-  createSplitProps<UsePresenceProps>()(props, ['immediate', 'lazyMount', 'onExitComplete', 'present', 'unmountOnExit'])
+  createSplitProps<UsePresenceProps>()(props, [
+    'immediate',
+    'lazyMount',
+    'onExitComplete',
+    'present',
+    'skipAnimationOnMount',
+    'unmountOnExit',
+  ])

packages/svelte/src/lib/components/presence/use-presence.svelte.ts

@@ -1,9 +1,15 @@
 import type { Optional } from '$lib/types'
 import { type RenderStrategyProps, splitRenderStrategyProps } from '$lib/utils/render-strategy'
 import * as presence from '@zag-js/presence'
-import { normalizeProps, reflect, useMachine } from '@zag-js/svelte'
-
-export interface UsePresenceProps extends Optional<presence.Props, 'present'>, RenderStrategyProps {}
+import { normalizeProps, useMachine } from '@zag-js/svelte'
+
+export interface UsePresenceProps extends Optional<presence.Props, 'present'>, RenderStrategyProps {
+  /**
+   * Whether to allow the initial presence animation.
+   * @default false
+   */
+  skipAnimationOnMount?: boolean
+}
 export interface UsePresenceReturn extends ReturnType<typeof usePresence> {}
 
 export const usePresence = (props: UsePresenceProps) => {
@@ -28,7 +34,7 @@ export const usePresence = (props: UsePresenceProps) => {
 
   const result = $derived(() => ({
     getPresenceProps: () => ({
-      'data-state': props.present ? 'open' : 'closed',
+      'data-state': api.skip && props.skipAnimationOnMount ? undefined : props.present ? 'open' : 'closed',
       hidden: !api.present,
     }),
     present: api.present,

packages/vue/CHANGELOG.md

@@ -6,6 +6,11 @@ description: All notable changes will be documented in this file.
 
 ## [Unreleased]
 
+### Added
+
+- **Presence**: Added support for skipping the initial animation when the component is mounted. This can be used in all
+  disclosure components (e.g., `Dialog`, `DatePicker`, `Menu` etc).
+
 ## [5.4.0] - 2025-03-28
 
 ### Added

packages/vue/src/components/presence/examples/skip-animation-on-mount.vue

@@ -0,0 +1,13 @@
+<script setup lang="ts">
+import { Presence } from '@ark-ui/vue/presence'
+import { ref } from 'vue'
+
+const isPresent = ref(true)
+</script>
+
+<template>
+  <div>
+    <button @click="isPresent = !isPresent">Toggle</button>
+    <Presence :present="isPresent" skip-animation-on-mount>Content</Presence>
+  </div>
+</template>

packages/vue/src/components/presence/presence.stories.vue

@@ -2,6 +2,7 @@
 import Basic from './examples/basic.vue'
 import LazyMountAndUnmountOnExit from './examples/lazy-mount-and-unmount-on-exit.vue'
 import LazyMount from './examples/lazy-mount.vue'
+import SkipAnimationOnMount from './examples/skip-animation-on-mount.vue'
 import UnmountOnExit from './examples/unmount-on-exit.vue'
 </script>
 <template>
@@ -18,5 +19,8 @@ import UnmountOnExit from './examples/unmount-on-exit.vue'
     <Variant title="LazyMountAndUnmountOnExit">
       <LazyMountAndUnmountOnExit />
     </Variant>
+    <Variant title="SkipAnimationOnMount">
+      <SkipAnimationOnMount />
+    </Variant>
   </Story>
 </template>

packages/vue/src/components/presence/presence.types.ts

@@ -1,6 +1,7 @@
 export interface RootProps {
   /**
    * Whether to synchronize the present change immediately or defer it to the next frame
+   * @default false
    */
   immediate?: boolean
   /**
@@ -10,8 +11,14 @@ export interface RootProps {
   lazyMount?: boolean
   /**
    * Whether the node is present (controlled by the user)
+   * @default false
    */
   present?: boolean
+  /**
+   * Whether to allow the initial presence animation.
+   * @default false
+   */
+  skipAnimationOnMount?: boolean
   /**
    * Whether to unmount on exit.
    * @default false

packages/vue/src/components/presence/presence.vue

@@ -24,6 +24,7 @@ const props = withDefaults(defineProps<PresenceProps>(), {
   immediate: undefined,
   lazyMount: undefined,
   present: undefined,
+  skipAnimationOnMount: undefined,
   unmountOnExit: undefined,
 } satisfies BooleanDefaults<RootProps>)
 

packages/vue/src/components/presence/use-presence.ts

@@ -15,6 +15,11 @@ export interface UsePresenceProps extends Optional<presence.Props, 'present'> {
    * @default false
    */
   unmountOnExit?: boolean
+  /**
+   * Whether to allow the initial presence animation.
+   * @default false
+   */
+  skipAnimationOnMount?: boolean
 }
 
 export type UsePresenceReturn = ReturnType<typeof usePresence>
@@ -61,7 +66,8 @@ export const usePresence = (props: MaybeRef<UsePresenceProps>, emit?: EmitFn<Roo
       presenceProps: {
         ref: nodeRef,
         hidden: !api.value.present,
-        'data-state': localProps?.present ? 'open' : 'closed',
+        'data-state':
+          api.value.skip && localProps.skipAnimationOnMount ? undefined : localProps?.present ? 'open' : 'closed',
       },
     }
   })

website/src/content/types/react/color-picker.types.json

@@ -294,6 +294,12 @@
       },
       "readOnly": { "type": "boolean", "isRequired": false, "description": "Whether the color picker is read-only" },
       "required": { "type": "boolean", "isRequired": false, "description": "Whether the color picker is required" },
+      "skipAnimationOnMount": {
+        "type": "boolean",
+        "defaultValue": "false",
+        "isRequired": false,
+        "description": "Whether to allow the initial presence animation."
+      },
       "unmountOnExit": {
         "type": "boolean",
         "defaultValue": "false",
@@ -333,6 +339,12 @@
         "isRequired": false,
         "description": "Whether the node is present (controlled by the user)"
       },
+      "skipAnimationOnMount": {
+        "type": "boolean",
+        "defaultValue": "false",
+        "isRequired": false,
+        "description": "Whether to allow the initial presence animation."
+      },
       "unmountOnExit": {
         "type": "boolean",
         "defaultValue": "false",

website/src/content/types/react/combobox.types.json

@@ -326,6 +326,12 @@
         "isRequired": false,
         "description": "The behavior of the combobox input when an item is selected\n\n- `replace`: The selected item string is set as the input value\n- `clear`: The input value is cleared\n- `preserve`: The input value is preserved"
       },
+      "skipAnimationOnMount": {
+        "type": "boolean",
+        "defaultValue": "false",
+        "isRequired": false,
+        "description": "Whether to allow the initial presence animation."
+      },
       "translations": {
         "type": "IntlTranslations",
         "isRequired": false,
@@ -373,6 +379,12 @@
         "isRequired": false,
         "description": "Whether the node is present (controlled by the user)"
       },
+      "skipAnimationOnMount": {
+        "type": "boolean",
+        "defaultValue": "false",
+        "isRequired": false,
+        "description": "Whether to allow the initial presence animation."
+      },
       "unmountOnExit": {
         "type": "boolean",
         "defaultValue": "false",