---
title: Component System
description: An overview of Jaspr's component system.
---
> ## 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.

---

**Jaspr** comes with a component system that is very similar to Flutter's widgets. This is a core design decision of jaspr, in order to look and feel very familiar to developers coming from Flutter. You might think of it as just replacing the word 'Widget' with 'Component' *(which actually was a small part of Jaspr's development process 😉)*, while keeping the same structure and behavior.

<Warning>
The following page and other documentation assumes, that you have already a basic understanding of Flutter's widget system, especially the widget tree and the three base widgets: StatelessWidget, StatefulWidget and InheritedWidget.
</Warning>

When building an app or website with **Jaspr** you will mostly use these **three** basic components:

## StatelessComponent

A custom component that does not require any mutable state and looks like this:

```dart
class MyComponent extends StatelessComponent {
  const MyComponent({Key? key}): super(key: key);

  @override
  Component build(BuildContext context) {
    return p([ .text('Hello World') ]);
  }
}
```

Similar to Flutter, this component:

- extends the abstract `StatelessComponent` class,
- has a constructor receiving a `Key` and optionally some custom parameters,
- has a `build()` method receiving a `BuildContext`.

## StatefulComponent

A custom component that has mutable state and looks like this:

```dart
class MyComponent extends StatefulComponent {
  const MyComponent({Key? key}): super(key: key);

  @override
  State createState() => MyComponentState();
}

class MyComponentState extends State<MyComponent> {

  @override
  Component build(BuildContext context) {
    return p([ .text('Hello World') ]);
  }
}
```

Similar to Flutter, this component:

- extends the abstract `StatefulComponent` class,
- has a constructor receiving a `Key` and optionally some custom parameters,
- has a `createState()` method returning an instance of its custom state class

and has an associated state class that:

- extends the abstract `State<T>` class,
- has a `build()` method inside the state class receiving a `BuildContext`,
- can have optional `initState()`, `didChangeDependencies()`, and other lifecycle methods.

## InheritedComponent

A base class for components that efficiently propagate information down the tree and looks like this:

```dart
class MyInheritedComponent extends InheritedComponent {
  const MyInheritedComponent({required super.child, super.key}) ;

  static MyInheritedComponent of(BuildContext context) {
    final MyInheritedComponent? result = context.dependOnInheritedComponentOfExactType<MyInheritedComponent>();
    assert(result != null, 'No MyInheritedComponent found in context');
    return result!;
  }

  @override
  bool updateShouldNotify(covariant MyInheritedComponent oldComponent) {
    return false;
  }
}
```

In every aspect, this component behaves the same as Flutter's `InheritedWidget`.


## Foundation Components

Jaspr has three foundational component types, which are accessible through factory constructors on the `Component` class: `Component.element()`, `Component.text()` and `Component.fragment()`. Additionally, there are two more `Component.empty()` and `Component.apply()` which are all explained below.

<Info>
Unlike Flutter, Jaspr has a fixed number of foundational components which make up all other components and represent the core building blocks of HTML: element nodes and text nodes. Flutter is different because it allows you to write custom render objects with your own layouting and painting logic. This isn't possible in Jaspr because with HTML, the browser handles both layouting and painting. 
</Info>

### Component.element()

The foundational component that renders a single html element with a tag, attributes and other parameters, as well as a list of child components.

The `Component.element()` factory constructor always creates a component of type `DomComponent`.

<Info>
In general, it is recommended to use [HTML components](/concepts/html) like `div()`, `button()`. You can use `Component.element()` directly for lower-level control (mainly by specifying the tag as a `String`), but is more verbose. 
</Info>

```dart
final component = Component.element(
  tag: 'div',
  id: 'my-id',
  classes: 'class-a class-b',
  styles: Styles(color: Colors.black),
  attributes: {'my-attribute': 'my-value'},
  events: {'click': (e) => print('clicked')},
  children: [
    /* ... */
  ],
);

// The same component, but using HTML components instead.
final component2 = div(
  id: 'my-id', 
  classes: 'class-a class-b',
  styles: Styles(color: Colors.black),
  attributes: {'my-attribute': 'my-value'},
  events: {'click': (e) => print('clicked')},
  [
    /* ... */
  ],
);
```

Either component renders the following HTML:

```html
<div id="my-id" class="class-a class-b" style="color: black;" my-attribute="my-value">
  ...
</div>
```

See [Writing HTML](/concepts/html) for more details and examples.

### Component.text()

A simple component that renders a text node. A text node in html is just some standalone string that is placed inside another html element. Therefore the `Component.text()` constructor also only receives a single string to render to the page.

The `Component.text()` factory constructor always creates a component of type `Text`.

<Info>

Since Dart 3.10 you can use [dot-shorthands](http://dart.dev/to/dot-shorthands) to shorten the syntax of text components: `.text('Hello World')` instead of `Component.text('Hello World')`.
</Info>

```dart
final component = Component.text('Hello World!');

// The same component, but using dot-shorthands instead.
final Component component2 = .text('Hello World!');
```

<Info>
As usual for web, styling is done through a combination of CSS attributes, either in a **Stylesheet** or inline though the **`styles` attribute** of the parent elements.
</Info>

### Component.fragment()

A component that renders its child components without any wrapper element.

This is meant to be used in places where you want to render multiple components / elements, but only a single component is allowed by the API, like in the `build()` method of stateless and stateful components.

The `Component.fragment()` factory constructor always creates a component of type `Fragment`.


<Info>
Since Dart 3.10 you can use [dot-shorthands](http://dart.dev/to/dot-shorthands) to shorten the syntax of fragment components: `.fragment([ ... ])` instead of `Component.fragment([ ... ])`.
</Info>

```dart
final component = Component.fragment([
  Component.element(tag: 'h1', children: [Component.text('Welcome')]),
  Component.element(tag: 'p', children: [Component.text('Hello World')]),
]);

// The same component, but using dot-shorthands and HTML components instead.
final Component component2 = .fragment([
  h1([ .text('Welcome')]),
  p([ .text('Hello World')]),
]);
```

Either component renders the following HTML:

```html
<h1>Welcome</h1>
<p>Hello World</p>
```

### Component.empty()

A helper constructor that creates an empty fragment, thus rendering nothing.

This is useful when you want to return "nothing" from a build method.

```dart
final component = Component.empty();
```

### Component.apply()

A component which applies its attributes and parameters (like `classes`, `styles`, etc.) to its target element(s).

This does not create an HTML element itself. All properties are merged with the respective target element's properties, with the target's properties taking precedence where there are conflicts.

```dart
final component = Component.apply(
  classes: 'wrapping-class',
  styles: Styles(backgroundColor: Colors.blue, padding: Padding.all(8.px)),
  child: div(
    classes: 'some-class',
    styles: Styles(backgroundColor: Colors.red),
    [
      .text('Hello World'),
    ],
  ),
);
```

The above component renders the following HTML:

```html
<div class="some-class wrapping-class" style="background-color: red; padding: 8px;">
  Hello World
</div>
```

By default, `Component.apply()` targets all of its direct children. You can change this by using the `ApplyTarget target` parameter to target elements, either direct children or descendants, by tag, id or class names.

```dart
final component = Component.apply(
  target: ApplyTarget.descendantWith(tag: 'p'),
  styles: Styles(color: Colors.blue),
  child: div([
    p([
      .text('Hello World'),
    ]),
  ]),
);
```

The above component renders the following HTML:

```html
<div>
  <p style="color: blue;">Hello World</p>
</div>
```

#### Precedence and Merging Rules

When properties are applied, the following rules and special cases apply:

- **Target Precedence**: Properties defined on the target element always take precedence over applied properties. Where multiple nested `Component.apply()` components target the same element, inner (closer) wrappers take precedence over outer ones.
- **Classes**: Applied class names are merged as a set of whitespace-separated tokens with the target's classes. If a target element specifies class names via `attributes: {'class': ...}`, classes from `Component.apply()` are **never applied** to that element to preserve raw attributes and prevent duplicate HTML attributes.
- **Styles**: Applied styles are merged on a per-property basis. Any style property already defined on the target element is preserved. If a target element specifies raw inline styles via `attributes: {'style': ...}`, styles from `Component.apply()` are **never applied** to that element to avoid corrupting raw style declarations or unsafe mixing of structured and raw styles.
- **ID & Attributes**: An `id` or other attributes defined on the target element (or in its `attributes` map) are never overwritten by applied values.
- **Events**: Event listeners on the target element take precedence; applied listeners are added as supplementary listeners if not already bound.

## Formatting Whitespace

When pre-rendering your components in **server** and **static** mode, Jaspr will output cleanly formatted html on a best-effort basis. This means it will add newlines and indentations to your html element, while trying to not affect the way the html is rendered.

For example let's look at this simple Jaspr code:

```dart
div([
  b([ .text('A') ]),
  em([ .text('B') ]),
  span([ .text('C') ]),
])
```

Which will generate the following html:

```html
<div>
  <b>A</b>
  <em>B</em>
  <span>C</span>
</div>
```

Here Jaspr adds newlines and indentation for each child element. However in some cases, you might not want Jaspr to introduce extra whitespace because it would affect the way the html is rendered.

If you don't want Jaspr to format the output html for a part of your code, wrap it in a `<span>` element. This works since Jaspr will not apply any additional formatting to `<span>` elements.

So for example this code:

```dart
span([
  b([ .text('A') ]),
  em([ .text('B') ]),
  span([ .text('C') ]),
]),
```

will generate to following html:

```html
<span><b>A</b><em>B</em><span>C</span></span>
```
