Components

Components let a club on the Pro plan write its own website sections in code: a countdown to your season launch, a fixtures ladder in your colours, anything the built-in sections don't do. You write a component in TypeScript and React, ClubHelix checks and builds it, and once you publish and install it, it goes on any page like a built-in section.

An interactive component, the default, runs in an isolated frame on a separate domain. It can't see your admin, your members' details or anyone's login, and it reads only the public information you allow it to. A static component is turned into plain HTML ahead of time and shown as part of the page, with no script running in the visitor's browser.

Who can use this

• Your organisation's administrators can create, edit, build, publish, install, switch off and archive components.
• A moderator who has been given the Create & edit components permission can open the page and look, but can't change anything.
• Components are part of the Pro plan, and you switch them on under Features first.

What's on the page

Website management → Components lists your components: each one's latest version, where its build has got to (in words, such as "Build passed, not yet published") and whether it's installed on your site. Create a new component from the form at the top.

Open a component to see:

• Source: your files, with index.tsx first. It must default-export the component.
• Manifest (component.json): the component's name, version, the data it may read, where it can go on a page and its tallest height.
• Example settings: sample settings the build renders your component with. The preview uses the first one.
• Build: each step of the last build and every message it produced, with the file and line.
• Preview: once a build has passed, the component running in the same kind of frame your website uses.
• Versions: every version and its state. Pick one to open it.
• On your site: install, switch off, uninstall or archive.

Step by step

Choose static or interactive

Set renderMode in the manifest:

• Interactive ("interactive", the default) runs in the visitor's browser, in its own frame. Choose it for anything people click or that changes by itself: tabs, calculators, countdowns, carousels.
• Static ("static") is rendered once into plain HTML with your organisation's public data, and shown as part of the page. Search engines and screen readers read it like the rest of the page. None of its code runs in the visitor's browser, so nothing in it is interactive: clicks, timers and live updates do nothing, and effects (useEffect) never run, so it always shows its first render.

A static component is rendered after you save a page that uses it, and again when the information it shows changes: news, events and their venues, sponsors, teams, programs, fixtures and results, or your organisation's name and logo. A new render usually shows on your site within about ten minutes, and the same component is rendered at most once every five minutes. While a new render is being made, visitors keep seeing the last one, so the component never goes blank, and if a new render fails the last good one stays up. Until the first render is ready, visitors see nothing in its place and your admins see "Preparing this component".

A static component can style itself with a component.css file. Those styles apply inside the component only, never to the rest of your page. The built-in Heading and Text set their own colour and size from your theme, so a rule like h2 { color: … } won't change them. Style your own elements or class names instead, or add !important to the rule.

Write and build a component

1. Type a name in the form at the top of the page and click Create component. It starts as a working example you can change.
2. Edit index.tsx. Declare the settings people fill in with a zod schema exported as propsSchema.
3. Change the manifest if you need to: for example, add "events:read" to data to read your events.
4. Click Save draft, then Build. A build usually starts within a minute and the page updates on its own.
5. If the build fails, read the messages under Build, fix the file and line they name, save and build again.

Ask the assistant to draft one

Open Helix Assistant on this page and describe what you want, such as "Build a countdown to our season launch on 7 March". It shows you the files and what the component will read. When you click Apply, it saves a draft and starts a build, and the assistant shows how the build is going. If the build fails, click Fix the build errors and the assistant gets the build's own messages and sends back a corrected draft. Each round uses one of your daily prompts, and you get up to five rounds per component in a chat. The assistant never publishes or installs a component. You check the preview and do those yourself.

Publish and install it

1. When the build has passed, check the Preview, then click Publish. A published version can't be changed; later changes go into a new version (Start a new version).
2. Under On your site, read what the component will be able to see, then click Install.
3. In the page editor, add a Custom component section, choose your component and fill in its settings.
4. Save the page. A static component appears on it within a few minutes of the save.

Move your site to a new version

1. Click Start a new version, make your changes, then build and publish it.
2. Under On your site, click Switch the site to the new version. Every page showing the component moves to it at once, so there's nothing to change on the pages.
3. If the new version changed its settings, check each page that uses it. A section whose settings the new version won't accept stops showing until you fix them in the page editor.

Take it off your site

• Switch off stops it showing everywhere straight away. Switch back on returns it.
• Uninstall removes the install. Archive hides the component and switches it off.

Field reference

What a component can import. react, zod and @clubhelix/component-sdk (headings, text, buttons, images, a countdown and more, styled by your theme), plus its own files. Other packages can't be installed.

What a static component can't keep. When it's put into your page, forms, inputs, frames, SVG, event handlers and srcset are removed, and so are CSS custom properties in a style attribute. In component.css, :host can't be positioned or moved. Images must come from your own media library.

What the build refuses. Network requests, reading cookies or the page around it, eval, raw HTML, scripts and frames, code that looks deliberately hidden, and anything over 64 KB compressed. Each refusal names the file and line.

Tips & FAQ

• Why can't I edit a published version? So the code on your site is always exactly what was checked. Start a new version, build it, publish it, then switch the site to it.
• Will search engines read my component? A static one, yes: it's part of the page's HTML. An interactive one runs in a frame, so not reliably. Keep anything people search for in a static component or an ordinary section.
• Why hasn't my static component changed? It refreshes after you save the page and after the information it shows changes, usually within about ten minutes. Some changes happen without anyone editing anything, and those don't refresh it: an event that has started, a sponsor past its end date, or a fixture that has become a result stays as it was until the next edit or page save. If it's been longer than that, save the page again.
• Why is data empty in the preview? The preview doesn't load your site's data yet. It shows the component with your example settings only.
• Can other clubs use my component? Not yet. Components belong to your organisation.
• Can the Helix Assistant build one for me? It can draft one, build it and fix what the build reports, and explain what a build message means. Publishing and installing are always your click.
• What happens if we leave Pro? Your components stop showing to visitors straight away. They're kept, and they come back when you upgrade. You can still switch them off or uninstall them.
• For colours and fonts that components pick up, see Theme.