Show

import { Show } from '@cerberus/react'

Usage

The Show component takes a when prop that determines whether the children or the fallback content should be rendered. If when is true, the children are rendered. If when is false, the fallback content is rendered.

Eager Loading

When passing elements as children, they are rendered eagerly into the Virtual DOM.

'use client'

import { Button, Show, Text, ToggleParts } from '@cerberus/react'
import { VStack } from 'styled-system/jsx'
import { useState } from 'react'

export default function ShowPreview() {
  const [authenticated, setAuthenticated] = useState<boolean>(false)

  function handleChange(state: boolean) {
    setAuthenticated(state)
  }

  return (
    <VStack w="1/2">
      <ToggleParts.Root
        onPressedChange={handleChange}
        pressed={authenticated}
        asChild
      >
        <Button type="button">
          <ToggleParts.Indicator fallback={<>Sign in</>}>
            Sign out
          </ToggleParts.Indicator>
        </Button>
      </ToggleParts.Root>

      <Show
        when={authenticated}
        fallback={<Text>You are not allowed to enter!</Text>}
      >
        <Text>You are authenticated and can enter the gates of Hades!</Text>
      </Show>
    </VStack>
  )
}

Lazy Loading

To defer rendering until the condition is true, you can pass a function as children. This function will only be called when the when condition is true.

'use client'

function LazyPreview() {
  const [loaded, setLoaded] = useState<boolean>(false)

  function handleLoad() {
    setLoaded(true)
  }

  return (
    <VStack w="1/2">
      <Button type="button" onClick={handleLoad}>
        Load Content
      </Button>

      <Show when={loaded}>{() => <LazyComponent />}</Show>
    </VStack>
  )
}

function LazyComponent() {
  console.log('Lazy component executed')
  return <Text>This is a lazy loaded component!</Text>
}

API

export interface ShowProps {
  children: ReactNode | (() => ReactNode)
  when: boolean | null | undefined
  fallback?: ReactNode
}

define function Show(props: ShowProps): ReactNode | null

Props

The Show component accepts the following props:

Understanding React Rendering: Eager vs. Lazy Execution

This section explains a fundamental concept in React development that affects when your components run their code, especially when using conditional rendering wrappers like <Show>. Understanding this difference is key to writing high-performance code and correctly controlling side effects, like data fetching.

The Core Misunderstanding: Execution vs. Rendering

When a component updates, React goes through two main steps:

1. Execution: The JavaScript function of your component runs.
2. Rendering/V-DOM Update: The component's return value.

1. Eager Execution

The JavaScript function of your component runs. (This is where your useState, useEffect, and data fetching logic execute). This pattern is what most developers instinctively use, but it causes the component's internal logic to run even if it's never shown on the screen.

<Show when={isLoggedIn}>
  <DashboardThatFetchesData />
</Show>

What Happens Under the Hood (Compilation)

The reason this is called Eager Execution is because the JavaScript compiler (like Babel, which processes JSX) must resolve all props for the <Show> component before it can call the Show function.

1.Parent Renders: The parent component of <Show> runs.

2.Eager Prop Evaluation: The compiler sees <DashboardThatFetchesData /> and immediately executes the DashboardThatFetchesData component function to figure out what to pass as the children prop.

3.Side Effects Run: Any logic or side effects within DashboardThatFetchesData (like a network request in useEffect) will run now.

4.Show Renders: The <Show> component function runs. It receives an already-executed React Element object as props.children. Since isLoggedIn is false, it returns null or the fallback, and the Dashboard is not rendered in the DOM.

2. The Lazy Execution

To gain control over the Execution step, we must pass a function instead of an element object. This is known as the Render Prop pattern.

<Show when={isLoggedIn}>
  {() => <DashboardThatFetchesData />}
</Show>

What Happens Under the Hood (Compilation)

1.Parent Renders: The parent component of <Show> runs.

2.Lazy Prop Evaluation: The compiler sees the prop value is a plain JavaScript function (() => <DashboardThatFetchesData />). It does not execute the function; it simply passes the function object as the children prop to <Show>.

3.Show Renders: The <Show> function runs.

• If isLoggedIn is false: It returns null or the fallback. The children function is never called, never executed. Execution is successfully skipped.
• If isLoggedIn is true: It calls the function: props.children(). This is the first moment the DashboardThatFetchesData function executes, and its side effects begin.