Helpers

Pulsar helpers are a quick way to include and configure components into your user interface, there are Twig and React variants available, depending on your UI environment.

caution

The React helpers are still in development and may not offer the same 1:1 functionality as the Twig helpers, please raise a ticket for any missing functionality you need

The Pulsar team often make improments to components, either by fixing bugs or improving accessiblity by changing the underlying markup. You should use helpers as much as possible to take advantage of these improments without having to go back and make changes to your hardcoded HTML.

Pulsar helpers also have accessibility support baked in where possible, certain attributes and aria roles may be added automatically depending on the options you supply and it’s very easy to miss these out if you're using hardcoded HTML. Your first instinct should always be to use the helpers where possible.

How to use

The options are usually passed as the first argument to the helper, however for some simple helpers (like icon) it may be the second. Each component may have specialised options and, unless otherwise stated, they should all accept the common helper options.

Twig example

{{
  html.button({
    'label': 'My Action',
    'class': 'btn--primary btn--small',
    'id': 'foo',
    'disabled': true,
    'data-toggle': 'an-action'
  })
}}

React example

<Button
  disabled
  className="btn--primary btn--small"
  id="foo"
  data-toggle="an-action"
>
  My Action
</Button>

Common options

The majority of Pulsar helpers accept the common options, unless otherwise stated in the component's documentation.

Option	Type (default)	Applies to	Description
autofocus	boolean (false)	button, input, select, select2, textarea	Automatically focuses the element after the page has finished loading
autocomplete	boolean (false)	text, textarea	Indicates whether controls in this form can by default have their values automatically completed by the browser
class	string	All	A space-separated list of additional class names, these will be added to whatever classes the component requires for its own styling
data-*	string	All	Data attributes can be added as required, eg: 'data-foo': 'bar'
disabled	boolean (false)	All	Indicates whether the component is disabled or not. The strategy used to disable a component may vary but in general they won't respond to user actions, cannot be focused and will be visually styled to represent the disabled state (usually greyed out). In the case of form elements the values will not be submitted with the parent form
error	string	Form helpers	Descriptive help text to explain an error or validation failure. Will also add the required error state styling to the component
form	string	Form helpers	The form element that the input element is associated with (its form owner). The value of the attribute must be an id of a <form> element in the same document. If this attribute isn't used, the <input> element is associated with its nearest ancestor <form> element, if any. This attribute lets you to place <input> elements anywhere within a document, not just as descendants of form elements. An input can be associated with at most one form
help	string	Form helpers	Additional guidance information to be displayed next to a form component, used to help the user understand what information they’re expected to provide and in what format
href	string	link, button	a URL or a URL fragment that the hyperlink points to Only available for button link type
id	string	All	A unique identifier which must be unique in the whole document. A helper may also use this ID to create other attributes (such as linking the for attribute of an form labels to the id of the related input)
label	string	Form helpers	The human-readable text label for an element, the position of this will vary depending on the helper and will not be added as a HTML attribute
name	string	Form helpers	The machine-readable name for an element, used by the server to identify fields in form submissions
placeholder	string	input, select2, textarea	Provides a hint to the user of what can be entered in the field, help text is preferred over placeholders for accessibility reasons
required	boolean (false)	Form helpers *	Specifies that the user must fill in a value before submitting a form and adds a visual indicator to the label. Cannot be used when the type option is hidden, image or a button type ( submit, reset, or button)
show-label	boolean (true)	Form helpers	If false, hides the label element of a form component without affecting the position of the input
value	string	Form helpers	Defines a default value which will be displayed in the element on page load