---
title: Server Components
description: >-
  Learn how to pass server-side components into client-side interactive
  boundaries to build high-performance layouts.
---
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jaspr.site/llms.txt
> Use this file to discover all available pages before exploring further.

When building modern web applications, we want both rich, fluid interactivity and fast initial page loads. 

Typically, once you make a parent component interactive by decorating it with `@client`, Jaspr must compile it and **all of its nested children** so they can run in the browser. Without Server Components, the moment a layout or parent container needs some client-side interactivity, every single child in its subtree gets pulled into the client-side bundle—even if those children are completely static.

**Server Components** solve this by enabling **surgical hydration**. They allow you to render server-side-only components inside parts of an interactive, hydrated client-side application. With this pattern, you can build interactive client-side wrappers (like expandable cards, navigation shells, sidebars, or tabs) while completely skipping compiling or shipping the static or heavy content inside them.

As a result:
- **Reduced Bundle Size:** The Dart code for server-only components is never compiled to JavaScript/Wasm or shipped to the browser, significantly reducing the application's client-side footprint.
- **Surgical Interactivity:** You only ship the parts of the code to the client that actually need to be interactive, skipping parts that are static.
- **Faster Page Loading:** Less code to download, parse, and execute means faster page loading for your users.
- **Access to Server Resources:** The server components within the client wrapper can safely fetch database records or read files using native APIs like `dart:io`.

## How to use Server Component

It is important to understand that **Server Components are not a separate API** in Jaspr. There is no special annotation, and you don't need to inherit from a special class.

Instead, Server Components are a design paradigm enabled by Jaspr's compilation and hydration model. You achieve this simply by **passing components as parameters** (such as a `child` component, or lists/maps of components) to a component annotated with [`@client`](/api/utils/at_client).

You can also pass components inside custom data classes by using `ComponentMount` with the [`@decoder`](/api/utils/at_encoder_decoder#decoding-models-with-component-fields-server-components) annotation.

## A Simple Example: Expandable Card

Let's build a client-side component called `ExpandableCard`. It features a button that lets users toggle the visibility of the card's content. To do this, the card must be interactive and annotated with `@client`. However, the content inside the card is static content that doesn't need client-side interactivity.

Here is the interactive card component:

```dart title="lib/components/expandable_card.dart"
import 'package:jaspr/dom.dart';
import 'package:jaspr/jaspr.dart';

@client
class ExpandableCard extends StatefulComponent {
  const ExpandableCard({required this.title, required this.content, super.key});

  final String title;
  final Component content;

  @override
  State<ExpandableCard> createState() => _ExpandableCardState();
}

class _ExpandableCardState extends State<ExpandableCard> {
  bool isExpanded = false;

  @override
  Component build(BuildContext context) {
    return div(classes: 'card', [
      div(classes: 'card-header', [
        h3([.text(component.title)]),
        button(
          onClick: () => setState(() => isExpanded = !isExpanded),
          [.text(isExpanded ? 'Collapse' : 'Expand')],
        ),
      ]),
      // We toggle visibility using a CSS class (like display: none in styles).
      // This ensures the server component is rendered during SSR,
      // and can then be shown or hidden interactively on the client.
      div(
        classes: 'card-content ${isExpanded ? 'expanded' : 'collapsed'}',
        [component.content],
      ),
    ]);
  }
}
```

Here is how you use the `ExpandableCard` component on the server, passing in a server-only component as a parameter:

```dart title="lib/main.server.dart"
import 'package:jaspr/dom.dart';
import 'package:jaspr/server.dart';
import 'components/expandable_card.dart';

void main() {
  Jaspr.initializeApp(options: defaultServerOptions);

  runApp(
    Document(
      title: 'My Dashboard',
      body: ExpandableCard(
        title: 'Server Component Info',
        content: div(classes: 'card-details', [
          p([.text('This content is static and rendered entirely on the server.')]),
          p([.text('It is not compiled to JavaScript or shipped to the browser.')]),
        ]),
      ),
    ),
  );
}
```

### Where is each part rendered?

Understanding where each component is built and executed is key to mastering this paradigm:

- **`Document`**: The root component of the server application. It is built and rendered **only on the server**.
- **`ExpandableCard` (@client Component)**: Built first on the server to generate the initial HTML, then **hydrated and executed on the client** to handle the expansion state and click events.
- **`ExpandableCard.content` parameter (`div` with static content)**: Evaluated and rendered to HTML on the server. The client-side framework receives this pre-rendered HTML DOM structure and simply mounts it at the correct position inside the hydrated `ExpandableCard`. The client browser never builds the `div` component or any of its children.

---

## Component Scopes

This rendering boundary behavior aligns directly with Jaspr's concept of **Component Scopes**. As described in [Server-Side Jaspr (Component Scopes)](/dev/server#component-scopes), your application is split into the **Server Scope** and the **Client Scope**.

Usually, once a component is in the Client Scope (by being nested inside a `@client` component), its entire subtree is also in the Client Scope and compiled to JavaScript. However, passing a component as a parameter to a `@client` component breaks this inheritance. It lets you transition parts of the subtree back into the Server Scope, creating alternating boundaries:

```mermaid
graph TD
    Root["main.server.dart<br><b>Server Scope</b>"] --> Card["ExpandableCard @client<br><b>Client Scope</b>"]
    Card --> Content["content component (CardDetails)<br><b>Server Scope</b>"]
    Content --> Button["InteractiveButton @client<br><b>Client Scope</b>"]
```

---

## Advanced Example: Tab Bar (List of Components)

You can also pass lists of components. For instance, a client-side `TabBar` that manages the active tab index, but renders the tab content panels entirely on the server.

Define the tabs client component:

```dart title="lib/components/tab_bar.dart"
import 'package:jaspr/dom.dart';
import 'package:jaspr/jaspr.dart';

@client
class TabBar extends StatefulComponent {
  const TabBar({required this.children, super.key});

  final List<Component> children;

  @override
  State<TabBar> createState() => _TabBarState();
}

class _TabBarState extends State<TabBar> {
  int activeIndex = 0;

  @override
  Component build(BuildContext context) {
    return div([
      div(classes: 'tab-headers', [
        button(onClick: () => setState(() => activeIndex = 0), [.text('Home')]),
        button(onClick: () => setState(() => activeIndex = 1), [.text('Profile')]),
        button(onClick: () => setState(() => activeIndex = 2), [.text('Settings')]),
      ]),
      div(classes: 'tab-content', [
        // We render all children to ensure they are built and hydrated on the server,
        // and toggle their visibility on the client using CSS classes.
        for (var i = 0; i < component.children.length; i++)
          div(
            classes: 'tab-pane ${i == activeIndex ? 'active' : 'hidden'}',
            [component.children[i]],
          ),
      ]),
    ]);
  }
}
```

Used on the server:

```dart title="lib/main.server.dart"
TabBar(
  children: [
    HomeTabContent(),      // Renders on server
    ProfileTabContent(),   // Renders on server
    SettingsTabContent(),  // Renders on server
  ],
)
```

---

## Hydration & How it Works

The following happens behind the scenes to link these components:

1. **Pre-Rendering**: The server renders the root component tree downwards. When it encounters a `@client` component, the `ClientComponentAdapter` takes any component parameters (such as `content`), renders them to HTML, and registers a `ServerComponentAdapter`.
2. **Markers**: The server wraps the rendered output of the server component in HTML comment boundary markers:
   ```html
   <!--s@1-->
   <div>Server-rendered Card Details</div>
   <!--/s@1-->
   ```
3. **Serialization**: The parameters of the `@client` component are serialized into JSON in its start marker. The `content` parameter is encoded using the server component's ID: `data={"content":"s@1"}`.
4. **Hydration**: The browser parses the HTML and loads the JavaScript bundle. The client-side framework locates the client markers, decodes the parameters, and reads the server component boundary comments as `ServerComponentAnchor` nodes.
5. **Mounting**: When the client component builds and calls `params.mount('s@1')`, the framework matches the ID to the parsed anchor and returns a `SlottedChildView` pointing directly to the pre-rendered HTML DOM nodes, avoiding any client-side execution of the server component's build code.

---

## Nested Client Components

Server components are not limited to static content. A component inside a Server Component subtree can itself be annotated with `@client`. 

During hydration, Jaspr compiles and hydrates the nested client component as normal, letting you embed complex client-side interactivity inside server-rendered templates.

---

## Conditional Rendering during SSR

Because Server Components are executed only on the server, **they must be pre-rendered during the initial Server-Side Rendering (SSR) phase**. 

If a Server Component is passed to a client component but is not evaluated or rendered in the component's build method (for example, if it is placed inside an `if` block where the condition is `false` during the initial server render), it cannot be constructed later on the client:

```dart
@client
class ConditionalCard extends StatefulComponent {
  const ConditionalCard({required this.content, super.key});
  final Component content;

  @override
  State<ConditionalCard> createState() => _ConditionalCardState();
}

class _ConditionalCardState extends State<ConditionalCard> {
  bool showContent = false; // Evaluates to false on the server

  @override
  Component build(BuildContext context) {
    return div([
      button(onClick: () => setState(() => showContent = true), [.text('Reveal')]),
      // WARNING: If showContent is false during SSR, 'component.content' is not built on the server.
      // When showContent becomes true on the client, it will render as EMPTY because 
      // the client does not have the Dart code to construct the server component.
      if (showContent) component.content, 
    ]);
  }
}
```

Always ensure that any Server Components passed as parameters are rendered/evaluated during the initial server-side build. If you need conditional visibility on the client, control it using CSS (e.g. `display: none`) or wrap the content in a client-side component instead.
