General Buttons
Last updated
Last updated
There are currently two core button components and the rest of the more specialized button components extend upon these core buttons.
The two core button components are:
(renders a basic anchor link element <a> that looks like a button)
(renders a basic button element <button>)
Some of the specialized buttons that extend from the above core button components are:
We'll review what makes each different and how to use them in the following section.
The LinkButton component is one of the core button components and if used it will output a very basic button anchor link <a> with minimal styles.
When used, you should use Tailwind classes to further style the button, adding a background color and active|focus|hover states, etc.
This component has two required properties:
href: a URL string for the destination link
text: a string for the button text
Example component use:
Example HTML output:
Example rendered output:
If the href URL passed to the LinkButton component is an external URL, the component will automatically add appropriate attributes (target and rel) and values to allow the link to open in a new browser tab. If you do not want an external link to open in a new browser tab, or alternatively, if you want internal links to open in a new browser tab you can override the default behavior by passing the appropriate attributes and values using the attributes property. You can see this in LinkButton example above.
The ElementButton component is one of the core button components and if used it will output a very basic button element <button> with minimal styles.
When used, you should use Tailwind classes to further style the button, adding a background color and active|focus|hover states, etc.
This component has one required property:
text: a string for the button text
Example component use:
Example HTML output:
Example rendered output:
By default, the ElementButton will output a <button type="button"> with a type of button. However, you can pass a type property to the component to output a submit button for use in forms as we do in the ElementButton example above.
The PrimaryButton component outputs a pre-configured "primary styled" button. It extends the LinkButton or ElementButton depending on the properties supplied, and outputs a link or element button respectively, with all the styling to make it visually render as a "primary styled" button with associated visual states.
Primary buttons have a blurple background and border with white text, along with associated pseudo state styles. You can pass additional Tailwind classes to further style the padding, text size, etc of the button, but you should not be overriding colors and other styles that specifically define it as a primary button.
This component has one required property:
text: a string for the button text
This type of button should be used for clicking to submit data, launch a link to a URL or show/hide interface elements, without changing its visual appearance as a "primary styled" button.
When used to show/hide interface elements, the button will alternate between its default visual appearance and its "active" visual appearance.
While only the text property is required for the PrimaryButton, to generate this button as a LinkButton an href property is required.
Example component use:
Example HTML output:
Example rendered output:
Only the text property is required to generate the PrimaryButton as an ElementButton.
Example component use:
Example HTML output:
Example rendered output:
The SecondaryButton component outputs a pre-configured "secondary styled" button. It extends the LinkButton or ElementButton depending on the properties supplied, and outputs a link or element button respectively, with all the styling to make it visually render as a "secondary styled" button with associated visual states.
Secondary buttons have a white background with a blurple colored border and text, along with associated pseudo state styles. You can pass additional Tailwind classes to further style the padding, text size, etc of the button, but you should not be overriding colors and other styles that specifically define it as a secondary button.
This component has one required property:
text: a string for the button text
This type of button should be used for clicking to submit data, launch a link to a URL or show/hide interface elements, without changing its visual appearance as a "secondary styled" button.
When used to show/hide interface elements, the button will alternate between its default visual appearance and its "active" visual appearance.
While only the text property is required for the SecondaryButton, to generate this button as a LinkButton an href property is required.
Example component use:
Example HTML output:
Example rendered output:
Only the text property is required to generate the PrimaryButton as an ElementButton.
Example component use:
Example HTML output:
Example rendered output:
The ToggleButton component outputs a pre-configured button that is capable of being toggled on and off. It extends the ElementButton component and outputs an element button, with all the styling to make it visually render as a "primary styled" button with associated visual states when toggled off and as a "secondary styled" button with associated visual states when toggled on.
This component has two required properties:
activateText: a string displayed when toggled off; to indicate clicking will activate
deactivateText: a string displayed when toggled on; to indicate clicking will decactivate
This type of button should be used specifically for toggling data items that distinctly have both an "on" and an "off" state. Examples would include "subscribing" or "unsubscribing" from an email newsletter, or to allow users to "follow" or "unfollow" a cause space.
The use case above, indicating the requirements of an on/off state is what separates the ToggleButton from how PrimaryButton and SecondaryButton can be used to show/hide interface elements.
Example component use:
Example HTML output:
Example rendered output:
However, in regards to these core buttons, since there is no single, common component that they themselves extend from, it made sense to utilize a composed btn class that defines these very basic styles in a single place. Having to specify this series of styles in each core component separately would inevitably lead to discrepancies.
Additionally, there are still some places in Phoenix where we need to support styles for buttons output in PHP, and having an accessible base btn class made sense to allow use outside of just React components. However, even in JavaScript and React components it could also be useful to have this composed class available for any button needs that fall outside of our core button components.
It is possible that this composed btn class approach, and the need to have it available changes in the future as the codebase evolves, and we will be sure to note changes in this documentation.
If you need a button that can be disabled in the interface, please use a button component that outputs a <button> element, like the component.
The core button components, and both utilize the btn composed class which can be found in the base stylesheet (base.scss). All the buttons that extend from these core button components will also have this composed class applied. This composed class helps define some very basic styles that all buttons that are links or elements should have applied to them.
Our preference when styling components is to use classes as much as possible, and when there's more specific styles that cannot be applied via Tailwind, then we should be using within the component itself.
