Composables

Focus State

Apply consistent focus-visible outline styles across all elements with configurable color, width, style, and offset using the useFocusState composable.

Overview

The useFocusState composable applies a consistent :focus-visible outline to all focusable elements. It creates CSS custom properties for the outline color, width, style, and offset, making focus indicators easy to customize per-theme.

`useFocusState`

function useFocusState(
    s: Styleframe,
    options?: WithThemes<FocusStateConfig>
): FocusStateResult

styleframe.config.ts

import { styleframe } from 'styleframe';
import { useFocusState } from '@styleframe/theme';

const s = styleframe();

const {
    focusOutlineColor,
    focusOutlineWidth,
    focusOutlineStyle,
    focusOutlineOffset,
} = useFocusState(s);

export default s;

styleframe/index.css

:root {
    --focus--outline-color: var(--color--primary);
    --focus--outline-width: 2px;
    --focus--outline-style: solid;
    --focus--outline-offset: 2px;
}

:focus-visible {
    outline-color: var(--focus--outline-color);
    outline-width: var(--focus--outline-width);
    outline-style: var(--focus--outline-style);
    outline-offset: var(--focus--outline-offset);
}

Default Values

Option	Default	Variable	Export
`outlineColor`	`"@color.primary"`	`--focus--outline-color`	`focusOutlineColor`
`outlineWidth`	`"2px"`	`--focus--outline-width`	`focusOutlineWidth`
`outlineStyle`	`"solid"`	`--focus--outline-style`	`focusOutlineStyle`
`outlineOffset`	`"2px"`	`--focus--outline-offset`	`focusOutlineOffset`

Custom Values

styleframe.config.ts

import { styleframe } from 'styleframe';
import { useFocusState } from '@styleframe/theme';

const s = styleframe();

const { focusOutlineColor, focusOutlineWidth } = useFocusState(s, {
    outlineColor: '@color.info',
    outlineWidth: '3px',
    outlineOffset: '3px',
});

export default s;

styleframe/index.css

:root {
    --focus--outline-color: var(--color--info);
    --focus--outline-width: 3px;
    --focus--outline-style: solid;
    --focus--outline-offset: 3px;
}

:focus-visible {
    outline-color: var(--focus--outline-color);
    outline-width: var(--focus--outline-width);
    outline-style: var(--focus--outline-style);
    outline-offset: var(--focus--outline-offset);
}

Best Practices

Use :focus-visible over :focus: The composable targets :focus-visible to show outlines only for keyboard navigation, not mouse clicks.
Keep outlines visible: Use your primary or info color for outlines to meet WCAG 2.1 focus indicator requirements.
Add offset for spacing: The default 2px offset prevents the outline from overlapping element borders.
Customize per-theme: Use theme overrides to adjust outline color for dark mode, ensuring focus indicators remain visible against darker backgrounds.

Edit this pageorReport an issue

Definition Lists

Style definition list elements (dl, dt, dd) with configurable margin, font weight, and spacing using the useDlElement, useDtElement, and useDdElement composables.

Headings

Style heading elements h1 through h6 with configurable font family, weight, line height, color, and per-level sizes using the useHeadingElement composable.