# 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
- TYPO3 13+
- PHP 8.3+
- Basic familiarity with [Fluid Components](https://docs.typo3.org/other/typo3fluid/fluid/main/en-us/Usage/Components.html)
- A modern JavaScript build setup like Vite, Webpack, etc. (Recommended)
## Installation
Install both the PHP and JavaScript packages:
```bash
composer require jramke/fluid-primitives
npm install fluid-primitives
```
Version Match
Keep the Composer and npm package versions in sync to avoid compatibility issues.
### Canary Builds
Need a fix before the next release? Use the canary builds:
```bash
composer require jramke/fluid-primitives:"dev-main"
npm install fluid-primitives@next
```
## Setup
### 1. Create a Component Collection
Create a `ComponentCollection` class in your sitepackage to register your component paths and contexts:
```php
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 `` instead of ``. See [File Structure](/docs/core-concepts/file-structure.md) for details.
### 2. Register the Namespace
Add the `ui` namespace to your `ext_localconf.php`:
```php
$GLOBALS['TYPO3_CONF_VARS']['SYS']['fluid']['namespaces']['ui'][] =
'MyVendor\\MySitepackage\\Components\\ComponentCollection';
```
Namespace Array
Fluid Primitives already registers ViewHelpers under ui. Append to the array instead of overwriting it.
### 3. Include the Site Set (or TypoScript manually)
```yaml
name: vendor/myext
label: 'MyExt'
dependencies:
- jramke/fluid-primitives
```
### 4. Optional: Component Settings
Expose custom settings to component templates:
```typoscript
plugin.tx_fluidprimitives {
settings {
# Your custom settings here
}
}
```
These merge with `lib.contentElement.settings` and are available as `{settings}` in component templates.
## Your First Component
Create a simple button at `Resources/Private/Components/ui/Button/Button.html`:
```html
```
Use it anywhere in your templates:
```html
Get Started
```
**What's happening:**
- [ui:prop](/docs/viewhelpers/ui-prop.md) defines the components arguments (props) with types and defaults
- [ui:attributes](/docs/viewhelpers/ui-attributes.md) forwards any extra attributes (like `data-*`)
- [ui:cn](/docs/viewhelpers/ui-cn.md) is a helper for conditional class names
- `{class}` is automatically available for additional classes
- `` renders child content
## 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:
```html
Toggle content Hidden content that expands/collapses
```
```typescript
import { mountAll } from 'fluid-primitives';
import { Collapsible } from 'fluid-primitives/collapsible';
mountAll('collapsible', ({ props }) => {
const collapsible = new Collapsible(props);
collapsible.init();
return collapsible;
});
```
See [Hydration](/docs/core-concepts/hydration.md) for the full picture on client-side setup.
## Next Steps
- [Core Concepts](/docs/core-concepts.md) - Understand composition, context, and hydration
- [Components](/docs/components.md) - Browse available primitives
- [ViewHelpers](/docs/viewhelpers.md) - Reference for `ui:prop`, `ui:ref`, and more