Skip to main content
Fluid Primitives

Getting Started

Get up and running with Fluid Primitives in just a few steps. This guide covers installation, basic setup, and creating your first component.

Prerequisites

Installation

Install both the PHP and JavaScript packages:

composer require jramke/fluid-primitives
npm install fluid-primitives

Setup

1. Create a Component Collection

Create a ComponentCollection class in your sitepackage to register your component paths and contexts:

<?php

declare(strict_types=1);

namespace MyVendor\MySitepackage\Components;

use Jramke\FluidPrimitives\Component\AbstractComponentCollection;
use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;
use TYPO3Fluid\Fluid\View\TemplatePaths;

final class ComponentCollection extends AbstractComponentCollection
{
    public function getTemplatePaths(): TemplatePaths
    {
        $templatePaths = new TemplatePaths();
        $templatePaths->setTemplateRootPaths([
            ExtensionManagementUtility::extPath('my_sitepackage', 'Resources/Private/Components/ui'),
            ExtensionManagementUtility::extPath('my_sitepackage', 'Resources/Private/Components'),
        ]);
        return $templatePaths;
    }

    public function getContextNamespaces(): array
    {
        return [
            'MyVendor\\MySitepackage\\Components\\Contexts',
        ];
    }
}

Important: Use AbstractComponentCollection from Fluid Primitives, not Fluid core.

Why two template paths? This lets you use <ui:button> instead of <ui:ui.button>. See File Structure for details.

2. Register the Namespace

Add the ui namespace to your ext_localconf.php:

$GLOBALS['TYPO3_CONF_VARS']['SYS']['fluid']['namespaces']['ui'][] =
    'MyVendor\\MySitepackage\\Components\\ComponentCollection';

3. Optional: Component Settings

Expose custom settings to component templates:

plugin.tx_fluidprimitives {
    settings {
        # Your custom settings here
    }
}

These merge with lib.contentElement.settings and are available as {settings} in templates.

Your First Component

Create a simple button at Resources/Private/Components/ui/Button/Button.html:

<ui:prop name="variant" type="string" optional="{true}" default="primary" />
<ui:prop name="type" type="string" optional="{true}" default="button" />

<button type="{type}" class="{ui:cn(value: 'btn btn--{variant} {class}')}" {ui:attributes()}>
    <f:slot />
</button>

Use it anywhere in your templates:

<ui:button variant="secondary" data-analytics="cta"> Get Started </ui:button>

What's happening:

Adding Interactive Components

For components with client-side behavior (accordion, dialog, tabs, etc.), you'll also need to initialize them in JavaScript.

Example with a collapsible:

<ui:collapsible.root>
    <ui:collapsible.trigger>Toggle content</ui:collapsible.trigger>
    <ui:collapsible.content> Hidden content that expands/collapses </ui:collapsible.content>
</ui:collapsible.root>

import { mount } from 'fluid-primitives';
import { Collapsible } from 'fluid-primitives/collapsible';

mount('collapsible', ({ props }) => {
    const collapsible = new Collapsible(props);
    collapsible.init();
    return collapsible;
});

See Hydration for the full picture on client-side setup.

Next Steps