Borders and Outlines
Purpose and Scope
This page is a practical reference for Tailwind CSS utilities that affect borders, table border spacing, and outlines. In Tailwind terminology, a utility class is a small class name that maps to one focused CSS declaration or declaration group, such as setting a border style to dashed or hiding an outline while preserving forced-colors behavior. Border and outline utilities are often combined with color, width, radius, focus, responsive, and dark-mode variants, so the important skill is understanding which utility controls which part of the final visual treatment.
The official documentation groups these APIs under border-related pages and table pages. The supplied docs evidence explicitly covers border-style, divider border styles, border-spacing, directional border spacing, and outline-style. The broader page title also includes the common companion families developers normally reach for in the same workflow: border width, border color, border radius, border collapse, outline width, outline offset, and outline color. Treat the concrete quick reference below as a working map of the classes evidenced here, and use the related pages for theme, colors, variants, and table-specific behavior when composing larger UI patterns.
A typical component uses several of these families together. A card might combine a radius, a subtle border color, and a hover state. A table might use separate borders with controlled horizontal and vertical spacing. A form control might remove the native focus outline only after replacing it with an accessible custom focus ring, border, or outline state. Because Tailwind utilities are composable, border and outline styling is rarely a single class; it is a small sequence of intent-revealing classes applied directly in markup.
Relevant Source Files
packages/@tailwindcss-upgrade/src/codemods/template/migrate-max-width-screen.ts— Shows the upgrade tool working with Tailwind class candidates throughDesignSystem.parseCandidateandDesignSystem.printCandidate, which is the source-backed signal for how migration code treats utility class strings as structured candidates rather than opaque text.
Sources: packages/@tailwindcss-upgrade/src/codemods/template/migrate-max-width-screen.ts
Utility Families at a Glance
Border style utilities control the border-style declaration for an element. The documented classes are border-solid, border-dashed, border-dotted, border-double, border-hidden, and border-none. These are useful when the border already has a width and color, because the style determines whether that border is rendered as a solid line, dashed line, dotted line, double line, hidden border, or no border. The official examples pair classes like border-2 border-solid and border-4 border-double, which illustrates the normal composition pattern: width and color establish the presence of the border, while style changes its visual texture.
Divider style utilities apply the same concept between children instead of around a single element. The documented divider classes are divide-solid, divide-dashed, divide-dotted, divide-double, divide-hidden, and divide-none; they target child separators with a selector shaped like direct children except the last child. This makes them a better fit for stacked lists, grids, menus, and grouped controls where the border belongs between items. In practice, divider utilities are commonly paired with directional divider width classes such as divide-x or divide-y and a color class such as divide-indigo-500.
Border spacing utilities are table-focused. They control the CSS border-spacing property, which only has a visible effect when the table uses separate borders rather than collapsed borders. The documented base form is border-spacing-<number>, where the number is multiplied by Tailwind’s spacing variable, and arbitrary forms such as border-spacing-[<value>] or custom-property forms such as border-spacing-(<custom-property>) are available when the design calls for a value outside the scale. Directional forms split the axes: border-spacing-x-<number> sets horizontal spacing while preserving the vertical variable, and border-spacing-y-<number> does the reverse.
Outline style utilities affect the outline drawn around an element, often for focus indication. The documented style classes are outline-solid, outline-dashed, outline-dotted, outline-double, outline-none, and outline-hidden. The distinction between outline-none and outline-hidden matters for accessibility. outline-none removes the browser outline entirely, so it should only be used when you provide another visible focus style. outline-hidden hides the regular outline by using a transparent outline and offset, while preserving behavior in forced-colors mode. For focusable controls, this distinction helps avoid making keyboard navigation invisible.
Compact Reference
| Family | Documented class patterns | CSS effect | Common pairing |
|---|---|---|---|
| Border style | border-solid, border-dashed, border-dotted, border-double, border-hidden, border-none | Sets border-style | Border width, border color, responsive variants |
| Divider style | divide-solid, divide-dashed, divide-dotted, divide-double, divide-hidden, divide-none | Sets child separator border style | divide-x, divide-y, divider color |
| Border spacing | border-spacing-<number>, border-spacing-[<value>], border-spacing-(<custom-property>) | Sets table border-spacing on both axes | border-separate, table cell borders |
| Border spacing X | border-spacing-x-<number>, border-spacing-x-[<value>], border-spacing-x-(<custom-property>) | Sets horizontal spacing and preserves vertical spacing | Tables with wider column gaps |
| Border spacing Y | border-spacing-y-<number>, border-spacing-y-[<value>], border-spacing-y-(<custom-property>) | Sets vertical spacing and preserves horizontal spacing | Tables with row separation |
| Outline style | outline-solid, outline-dashed, outline-dotted, outline-double, outline-none, outline-hidden | Sets or suppresses outline style | Focus variants, outline width, outline offset, outline color |
Use the table as a decision aid rather than a complete design recipe. For borders, style classes only describe the line type; they do not by themselves choose a color palette token, width scale, or rounded corner. For outlines, style classes usually need a width and offset to produce a visible focus treatment that feels intentional. For tables, spacing utilities need the table’s border model to be compatible with spacing. If a border-spacing-* class appears to have no effect, check whether the table is using separate borders rather than collapsed borders.
Composition Patterns
The simplest border pattern is to combine width, style, and color. For example, a dashed card border can be expressed as a class list shaped like border border-dashed border-gray-300, with variants such as dark:border-gray-700 layered in for color mode. The style utility is the part covered directly by the supplied border-style docs, while the width and color utilities come from neighboring Tailwind families. This separation is intentional: it keeps each class predictable and lets a component change one aspect of the border without rewriting the rest of the visual system.
For dividers, put the utilities on the parent rather than repeating border classes on each child. A grid like grid grid-cols-3 divide-x-3 divide-dashed divide-indigo-500 communicates that the parent owns the separators between columns. That is different from putting a full border around every child, which can double up interior lines and make spacing harder to reason about. Divider style classes follow the same style vocabulary as border style classes, so divide-dotted and border-dotted mean visually similar things but apply to different targets.
For tables, use border-separate before relying on spacing utilities. The official border-spacing example combines border-separate border-spacing-2 with border classes on the table and cells, producing visible gaps between cell borders. Axis-specific classes such as border-spacing-x-3 and border-spacing-y-2 are useful when column rhythm and row rhythm need different values. Arbitrary and custom-property forms are escape hatches for design-system integration, especially when spacing needs to follow a runtime CSS variable instead of Tailwind’s spacing scale.
For focus states, prefer adding accessible styling rather than merely removing browser defaults. A control can use a focus variant such as focus:outline-hidden only when another focus affordance, such as a border color, outline color, ring, or parent focus-within style, remains visible. The official outline documentation explicitly recommends applying your own focus styling when hiding or removing outlines. This is especially important for keyboard users and for high-contrast environments, where removing the default indicator without replacement can make an interface difficult or impossible to navigate.
System-to-Code Mapping
The supplied repository source for this page is an upgrade codemod rather than a border generator. It still reveals an important implementation boundary: Tailwind tools can parse a raw class string into structured candidates, inspect the candidate kind, root, and value, and then print a transformed candidate back to a class string. In the codemod, migrateMaxWidthScreen looks for a functional candidate with root max-w and a value starting with screen-; when it matches, it rewrites the value into a theme lookup and prints the result. Border and outline migrations would use the same class-candidate idea when they need reliable transformations instead of plain string replacement.
Sources: packages/@tailwindcss-upgrade/src/codemods/template/migrate-max-width-screen.ts
This matters for developers reading border and outline references because Tailwind class names are not just documentation labels. They are parsed by the design system, interpreted as candidates, and emitted as CSS according to their family and value form. A class like border-spacing-x-3 has a root-like prefix, an axis marker, and a scale value; an arbitrary value class like border-spacing-[2.75rem] carries an explicit CSS value; a style class like outline-dashed is static. Even when the concrete implementation file is outside this page’s supplied source paths, the codemod demonstrates the source-level contract that tooling treats utility candidates structurally.
The codemod also shows why upgrade tools can preserve user intent while changing syntax. Instead of searching for every occurrence of a substring, the function asks the design system to parse the raw candidate and only transforms a very specific shape. That reduces the risk of touching unrelated classes or text. When maintaining components that use many border and outline utilities, this is the same mental model to keep: each class has a defined family, allowed value forms, and variant prefixes that should be transformed through Tailwind-aware tooling when possible.
Practical Examples
A bordered button can start with a visible width and then choose a style: border-2 border-solid border-gray-400. To make the style responsive, prefix the later utility with a breakpoint variant, as in border-solid md:border-dotted. The responsive class does not create a separate component rule in your source code; it composes Tailwind’s variant system with the same border utility family. This is useful when a compact mobile layout needs a subtle solid border while a larger layout uses dotted separators or more decorative visual hierarchy.
A table with separated cells can use a class list like border-separate border-spacing-2 border border-gray-400, with cell classes such as border border-gray-300. To widen only the horizontal distance between columns, replace the all-axis spacing utility with border-spacing-x-3 and add a vertical value if needed. This pattern is best for data displays where each cell should look distinct. If the goal is a single grid with shared lines, border collapse utilities belong to the neighboring table-layout reference rather than the spacing-specific workflow described here.
A focusable input can use focus:outline-hidden when a replacement indicator is present, for example focus:border-indigo-600 on the input or focus-within:outline-2 focus-within:outline-indigo-600 on a wrapper. Use outline-none more cautiously because it fully removes the default outline. In design systems, this is often enforced through component conventions: every interactive component that suppresses the browser outline must define an alternative focus treatment in the same component or wrapper.
Next Steps
Read this page together with the theme and colors references when choosing palette tokens, because border and outline styling often depends on consistent color variables. Use the responsive-design and hover-focus-and-other-states pages when you need the same border treatment only at a breakpoint, on hover, on focus, or in dark mode. For table-specific work, pair border spacing with the tables reference so that border-separate, collapsed borders, caption placement, and cell spacing are considered as a single layout decision rather than isolated utility choices.