Castle Components

Drupal component library using TailwindCSS and AlpineJS. View the online documentation.

[!WARNING]
This module is under active development, and is not ready to be used in production.

Install

Install as any Drupal module. It's recommended to use composer.

composer install smithsonian/castle_components

Extend

To use the components in your theme you'll need to include the module's libraries in your theme's info.yml file.

For example:

# my_theme.info.yml
name: my_theme
type: theme
libraries:
  - castle_components/scripts
  - castle_components/tailwind
dependencies:
  - castle_components:castle_components

Note: Including the castle_components/tailwind library will use the package's default TailwindCSS styles. Normally, you'll want to exclude this library, and instead, create a Tailwind config in your custom theme to customize the way components are styled in your theme. An example config:

// tailwind.config.js
const colors = require('tailwindcss/colors')
/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    '../../../modules/contrib/castle_components/components/**/*.twig',
    './templates/**/*.twig',
  ],
  darkMode: 'selector',
  theme: {
    colors: {
      primary: colors.blue,    
      secondary: colors.slate,
      accent: colors.red,
      success: 'hsl(160, 84%, 39%)',
      warning: 'hsl(38, 92%, 50%)',
      error: 'hsl(0, 84%, 60%)',
    }
  },
  plugins: [require('@tailwindcss/typography')],
}

Usage

Once configured you can use components in your Drupal theme using Twig embed.

{% embed 'castle_components:button' with { size: 'large' } only %}
  {% block content %}
    This is a Castle button
  {% endblock %}
{% endembed %}

or Twig include

{{ include ('castle_components:icon', { 'name': 'download' }, with_context=false ) }}

AlpineJS

Many of the Castle components use AlpineJS for interactivity, transitions, and event handling.

You'll want to add the following style to you're HTML head to prevent unstyled components appearing before Alpine is initialized.

<style>
  [x-cloak] {
    display: none !important;
  }
</style>

Visual Studio Code

For autocomplete helpers copy the .vscode/castle-components.code-snippets Snippets file from the module directory into your VSCode project root. More information about creating your own snippets.

Development