`clientOnly()`

Environment: client, server

vike-react/vike-vue/vike-solid

You need vike-react/vike-vue/vike-solid to be able to use the clientOnly() helper. If you don't use vike-{react,vue,solid} then see Without vike-{react,vue,solid}.

The clientOnly() helper enables you to load and render a component only on the client-side.

⛔
The clientOnly() will soon be deprecated, use <ClientOnly> instead.

Alternatively, you can set ssr: false to load and render the entire page on the client-side only.

React
Vue
Solid

import { clientOnly } from 'vike-react/clientOnly'
 
const SomeComponent = clientOnly(() => import('./SomeComponent.jsx'))
/* If the component isn't the default export:
const SomeComponent = clientOnly(async () => (await import('some-library')).SomeComponent)
*/
 
function SomeWrapper() {
  return <SomeComponent fallback={<Loading />} />
}

import { clientOnly } from 'vike-react/clientOnly'
 
const SomeComponent = clientOnly(() => import('./SomeComponent.tsx'))
/* If the component isn't the default export:
const SomeComponent = clientOnly(async () => (await import('some-library')).SomeComponent)
*/
 
function SomeWrapper() {
  return <SomeComponent fallback={<Loading />} />
}

Props:

fallback: Content shown while the component is being loaded.
All other props are passed to the loaded component.

⚠️

Don't call clientOnly() inside a component — always call it at your module's top level. (Otherwise the component's state isn't preserved.)

function SomeWrapper() {
  // ❌ Bad: Don't call inside components
  const SomeComponent = clientOnly(() => import('./SomeComponent.jsx'))
  return <SomeComponent />
}

function SomeWrapper() {
  // ❌ Bad: Don't call inside components
  const SomeComponent = clientOnly(() => import('./SomeComponent.tsx'))
  return <SomeComponent />
}

// ✅ Good: Called at the module's top level
const SomeComponent = clientOnly(() => import('./SomeComponent.jsx'))
function SomeWrapper() {
  return <SomeComponent />
}

// ✅ Good: Called at the module's top level
const SomeComponent = clientOnly(() => import('./SomeComponent.tsx'))
function SomeWrapper() {
  return <SomeComponent />
}

Props

All props are passed to the loaded component.

Slots

fallback: Content shown while the component is being loaded.
client-only-fallback: Use it instead of the #fallback slot in case of conflicts.

All slots are passed to the loaded component.

import { clientOnly } from 'vike-solid/clientOnly'
 
const SomeComponent = clientOnly(() => import('./SomeComponent.jsx'))
/* If the component isn't the default export:
const SomeComponent = clientOnly(async () => (await import('some-library')).SomeComponent)
*/
 
function SomeWrapper() {
  return <SomeComponent fallback={<Loading />} />
}

import { clientOnly } from 'vike-solid/clientOnly'
 
const SomeComponent = clientOnly(() => import('./SomeComponent.tsx'))
/* If the component isn't the default export:
const SomeComponent = clientOnly(async () => (await import('some-library')).SomeComponent)
*/
 
function SomeWrapper() {
  return <SomeComponent fallback={<Loading />} />
}

Props:

fallback: Content shown while the component is being loaded.
All other props are passed to the loaded component.

Use cases

Common use cases:

Library components that don't support SSR. A solution is to render and load the component only on the client-side.

Most component libraries nowadays support SSR but some don't. Some even crash when they're merely loaded on the server-side (for example if the library has a hard reference to browser-only APIs such as window).
Performance. clientOnly() allows you to defer loading heavy components, such as a complex interactive map. That way, your users can already interact with your page before even the browser starts loading that heavy component.

Vite code-splits dynamic imports such as const { SomeComponent } = await import('./SomeComponent'). In other words, the code of <SomeComponent /> isn't included in the initial JavaScript client bundle: it's loaded only when/if import() is called.

Without `vike-{react,vue,solid}`

If you don't use a UI framework Vike extension vike-react/vike-vue/vike-solid, you can implement the clientOnly() helper yourself.

See, for example, the source code at:

clientOnly()

Props

Slots

Use cases

Without vike-{react,vue,solid}

See also

`clientOnly()`

Without `vike-{react,vue,solid}`