CaptainCSS on GitHub

Configuration

A guide to configuring and customizing your Captain installation.

Captain follows in Tailwind's footsteps, ensuring it's completely configurable to allow for the building of completely bespoke user interfaces.

Captain uses Tailwind's tailwind.config.js at the root of the project for all its own theme and config options.

// Example `tailwind.config.js` file with Captain settings added
module.exports = {
  theme: {
    frame: {
      ratios: {
        '4:3': '1:1',
        '16:9': '16:9',
        golden: '1.618:1',
      },
    },
    fontFamily: {
      sans: ['Graphik', 'sans-serif'],
      serif: ['Merriweather', 'serif'],
    },
    extend: {
      borderRadius: {
        '4xl': '2rem',
      },
      cluster: {
        gap: {
          'tag': '1.5rem',
        },
      },
    }
  },
  variants: {
    cluster: [],
    extend: {
      borderColor: ['focus-visible'],
      opacity: ['disabled'],
    }
  },
  captain: {
    plugins: {
      stack: false,
    },
  },
}

Like Tailwind, every section of the config file is optional, so you only have to specify what you'd like to change. Any missing sections will fall back to Captain's default configuration.

Creating your configuration file

If you don't already have a Tailwind configuration file, follow Tailwind's instructions to generate one.

Adding the entire default configuration

For most users we encourage you to keep your config file as minimal as possible, and only specify the things you want to customize.

If you'd rather add a complete configuration file that includes all of Captain's default configuration, copy the default settings from the defaultConfig, here.

Theme

The theme section is where you define the settings related to the visuals of your site.

Most of Captain's objects have size or spacing configurations, and where sensible they inherit from existing theme configuration.

// tailwind.config.js
module.exports = {
  theme: {
    stack: (theme) => ({
      gap: {
        DEFAULT: '1rem',
        ...theme('space'),
      },
    }),
    wrapper: {
      padding: {
        DEFAULT: '16px',
        md: '32px',
        lg: '40px',
        xl: '64px',
      },
    },
    extend: {
      wrapper: {
        maxWidth: {
          md: '980',
        },
      },
    }
  }
}

Learn more about the default theme and how to customize it in the theme configuration guide.

Variants

The variants section lets you control which variants are generated for each core plugin added by Captain.

Most of Tailwind's native variants don't apply to Captain, as the layout objects have no visual representation. However, Tailwind allows that any variant can be applied to any of Captain's utilities, if you desire.

You may also wish to disable some default variants, such as responsive, by using an empty array for them.

// tailwind.config.js
module.exports = {
  variants: {
    cluster: [],
    stack: [],
  },
}

Learn more in Tailwind's variants configuration guide.

Presets

The presets section allows you to specify your own custom base configuration instead of using Tailwind's default base configuration.

This extends to Captain as well, so you can add any of Captain's configuration to a preset for reuse too.

// tailwind.config.js
module.exports = {
  presets: [
    require('@acmecorp/base-tailwind-captain-config')
  ],

  // Project-specific customizations
  theme: {
    //...
  },
  // ...
}

Learn more about presets in Tailwind's presets documentation.

Prefix

As a Tailwind plugin, Captain fully supports prefixing its class names with Tailwind's prefix option.

Learn more about prefixes in Tailwind's prefixes documentation.

Captain

Captain uses the captain section of Tailwind's config to configure the plugin.

Plugins

The captain.plugins section allows you to completely disable classes that Captain would normally generate by default if you don't need them for your project.

If you don't provide any captain.plugins configuration, all core plugins will be enabled by default:

// tailwind.config.js
module.exports = {
  // ...
}

If you'd like to disable specific plugins, provide an object for captain.plugins that sets those plugins to false:

// tailwind.config.js
module.exports = {
  captain: {
    plugins: {
      stack: false,
      cluster: false,
    },
  },
}

If you'd like to safelist which plugins should be enabled, provide an array that includes a list of the plugins you'd like to use:

// tailwind.config.js
module.exports = {
  captain: {
    plugins: [
      'stack',
      'cluster',
      'wrapper',
      // ...
    ],
  },
}

If you'd like to disable all of Captain's core plugins, provide an empty array:

// tailwind.config.js
module.exports = {
  captain: {
    plugins: [],
  },
}

Here's a list of every plugin provided by Captain for reference:

Captain PluginDescription
clusterThe cluster object
frameThe frame object
skipLinkThe skip link object
stackThe stack object
wrapperThe wrapper object
activeBreakpointThe activeBreakpoint helper utility for showing what screen breakpoint is currently active
intrinsicCenterThe intrinsic-center utility to center flow content by its intrinsic width