States

Focus State

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

Part of the Global Preset:useFocusState is included in the Global Preset (useGlobalPreset) and you can configure it through the preset's focus option. For most projects, applying it via the preset is the recommended approach.

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.config.ts

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

const s = styleframe();

const { focus } = useGlobalPreset(s, {
    focus: {
        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

Horizontal Rule

Style horizontal rule elements with configurable border color, width, style, and margin using the useHrElement composable.

Selection

Style text selection with configurable background and text color using the useSelectionState composable.