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

// 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',
        },
      },
    }
  }
}

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

See the default theme here;

Theme structure

You can read about Tailwind's Theme structure in Tailwind's documentation.

Captain aims to offer the exact same functionality that Tailwind's core plugins provide. If it works in Tailwind, it most likely works in Captain too.

Captain plugins

Captain provides a number of plugins that add new keys to the theme object.

See the theme configuration reference or the default theme for a complete list of theme options.

For example, the stack key lets you customize options for the stack, such as the gap size between items. This sets which classes will be generated.

module.exports = {
  theme: {
    stack: (theme) => ({
      gap: {
        DEFAULT: '1rem',
        ...theme('space'),
      },
    }),
  }
}

The keys determine the suffix for the generated classes, and the values determine the value of the actual CSS declaration.

The example stack and gap configuration above would generate the following CSS classes:

.stack > * + * { --stack-space: 1rem }
.stack--0 > * + * { --stack-space: 0px }
.stack--0.5 > * + * { --stack-space: 0.125rem }
.stack--1 > * + * { --stack-space: 0.25rem }
.stack--1.5 > * + * { --stack-space: 0.375rem }
.stack--2 > * + * { --stack-space: 0.5rem }
//...etc

You'll notice that using a key of DEFAULT in the theme configuration created the class stack with no suffix. This is a common convention in Tailwind and is supported by all Captain's plugins.

To learn more about customizing a specific plugin from Captain, visit the documentation for that plugin.

For a complete reference of available theme properties and their default values, see the default theme configuration.

Customizing the default theme

Out of the box, your project will automatically inherit the values from the default theme configuration. If you would like to customize the default theme, you have a few different options depending on your goals.

Captain works the same as Tailwind's core plugins, allowing you to extend or override in exactly same way.

Extending the default theme

If you'd like to preserve the default values for a theme option but also add new values, add your extensions under the extend key in the theme section of your configuration file.

For example, if you wanted to add an extra breakpoint to the wrapper object, while preserving the existing ones, you could extend the wrapper property:

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      // Adds a new wrapper width in addition to the default wrapper widths
      wrapper: {
        maxWidth: {
          md: '980px',
        },
      }
    }
  }
}

Overriding the default theme

To override an option in the default theme, add your overrides directly under the theme section of your tailwind.config.js:

// tailwind.config.js
module.exports = {
  theme: {
    // Replaces all of the default `opacity` values
    wrapper: {
      maxWidth: {
        DEFAULT: '1220px',
        md: '980px',
      }
    }
  }
}

This will completely replace Captain's default configuration for that key, so in the example above none of the default wrapper width utilities would be generated.

However, Tailwind v2.0 is clever and will perform a deep merge, meaning that the other keys under wrapper will be unaffected, such as padding.

Furthermore, any keys you do not provide will be inherited from the default theme, so in the above example, the default theme configuration for things like stack, cluster or frame would be preserved.

You can of course both override some parts of the default theme and extend other parts of the default theme within the same configuration:

// tailwind.config.js
module.exports = {
  theme: {
    wrapper: {
      padding: {
        sm: '24px',
        md: '48px',
        lg: '60px',
      },
    },
    extend: {
      wrapper: {
        maxWidth: {
          md: '980px',
        }
      }
    }
  }
}

Referencing other values

If you need to reference another value in your theme, you can do so by providing a closure instead of a static value. The closure will receive a theme() function that you can use to look up other values in your theme using dot notation.

For example, you could generate stack gap utilities for every gap in your space palette by referencing theme('space') in your stack.gap configuration:

// tailwind.config.js
module.exports = {
  theme: {
    stack: (theme) => ({
      gap: theme('space'),
    }),
  }
}

The theme() function attempts to find the value you are looking for from the fully merged theme object, so it can reference your own customizations as well as the default theme values. It also works recursively, so as long as there is a static value at the end of the chain it will be able to resolve the value you are looking for.

Disabling an entire Captain plugin

If you don't want to generate any classes for a certain Captain plugin, it's better to set that plugin to false in your captain.plugins configuration than to provide an empty object for that key in your theme configuration.

// tailwind.config.js
module.exports = {
  theme: {
    stack: {},
  }
}

Disabling using an empty object in the theme configuration may still output classes, whereas disabling it in captain.plugins will mean it won't output anything at all.

Configuration reference

All of the keys in the theme object map to one of Captain's plugins.

All of these keys are also available under the theme.extend key to enable extending the default theme.