> ## Documentation Index
> Fetch the complete documentation index at: https://better-styled.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference for creating styled contexts

> Creates a context for sharing variants between parent and child components.

## Signature

```tsx theme={"theme":{"light":"min-light","dark":"synthwave-84"}}
function createStyledContext<T extends StyledContextInput>(
  variants: T
): StyledContext<T>
```

## Parameters

<ParamField path="variants" type="object" required>
  An object defining the variant names and their possible values.

  Each key is a variant name. Each value is an array of possible values.

  ```tsx theme={"theme":{"light":"min-light","dark":"synthwave-84"}}
  {
    size: ["sm", "md", "lg"],
    variant: ["primary", "secondary"],
    disabled: ["boolean"],
  }
  ```
</ParamField>

### Special Values

<ParamField path="[&#x22;boolean&#x22;]" type="array">
  Use `["boolean"]` for true/false variants. This produces a proper `boolean` type instead of `"true" | "false"`.

  ```tsx theme={"theme":{"light":"min-light","dark":"synthwave-84"}}
  createStyledContext({
    disabled: ["boolean"],  // Type: boolean
    loading: ["boolean"],   // Type: boolean
  });
  ```
</ParamField>

## Returns

<ParamField path="StyledContext" type="object">
  An object with:
</ParamField>

<ParamField path="Context" type="React.Context">
  The underlying React context. Rarely needed directly.
</ParamField>

<ParamField path="Provider" type="React.Provider">
  The context provider component. Used internally by styled components.
</ParamField>

<ParamField path="useVariants" type="function">
  Hook to read current variant values. Returns `null` outside a provider.

  ```tsx theme={"theme":{"light":"min-light","dark":"synthwave-84"}}
  const context = createStyledContext({ size: ["sm", "lg"] });

  function Child() {
    const variants = context.useVariants();
    // variants: { size: "sm" | "lg" } | null
  }
  ```
</ParamField>

<ParamField path="variantKeys" type="T">
  The original variants object. Used for type inference.
</ParamField>

## Examples

### Basic

```tsx theme={"theme":{"light":"min-light","dark":"synthwave-84"}}
import { createStyledContext } from "better-styled";

const CardContext = createStyledContext({
  size: ["sm", "md", "lg"],
  elevated: ["boolean"],
});
```

### With styled()

```tsx theme={"theme":{"light":"min-light","dark":"synthwave-84"}}
const CardContext = createStyledContext({
  variant: ["default", "outlined"],
});

const CardRoot = styled("div", {
  context: CardContext,
  variants: {
    variant: {
      default: { className: "bg-white shadow" },
      outlined: { className: "border-2 border-gray-200" },
    },
  },
});

const CardTitle = styled("h2", {
  context: CardContext,
  base: { className: "font-bold" },
  variants: {
    variant: {
      default: { className: "text-gray-900" },
      outlined: { className: "text-gray-700" },
    },
  },
});
```

### Multiple Variants

```tsx theme={"theme":{"light":"min-light","dark":"synthwave-84"}}
const ButtonContext = createStyledContext({
  size: ["xs", "sm", "md", "lg", "xl"],
  variant: ["solid", "outline", "ghost", "link"],
  colorScheme: ["blue", "red", "green", "gray"],
  disabled: ["boolean"],
  loading: ["boolean"],
});
```

### Using useVariants

```tsx theme={"theme":{"light":"min-light","dark":"synthwave-84"}}
const TabsContext = createStyledContext({
  size: ["sm", "lg"],
});

function TabIndicator() {
  const variants = TabsContext.useVariants();

  if (!variants) return null;

  return (
    <div className={variants.size === "lg" ? "h-1" : "h-0.5"} />
  );
}
```

## Type Inference

Types are automatically inferred from the arrays:

```tsx theme={"theme":{"light":"min-light","dark":"synthwave-84"}}
const ctx = createStyledContext({
  size: ["sm", "md", "lg"],        // "sm" | "md" | "lg"
  disabled: ["boolean"],           // boolean
  variant: ["a", "b", "c", "d"],   // "a" | "b" | "c" | "d"
});

// Inferred type:
// {
//   size: "sm" | "md" | "lg"
//   disabled: boolean
//   variant: "a" | "b" | "c" | "d"
// }
```

No `as const` needed.

## Notes

<Note>
  Context values are provided when a parent component with `context` receives variant props **or** has `defaultVariants` defined. Children automatically inherit these values.
</Note>

<Note>
  Only variants defined here will propagate to children. You can define additional **local variants** in `styled()` that stay on a single component. See [Local Variants](/concepts/context#local-variants).
</Note>

<Warning>
  Always define arrays inline in `createStyledContext()`. Assigning them to variables first can break type inference.

  ```tsx theme={"theme":{"light":"min-light","dark":"synthwave-84"}}
  // ✅ Correct
  createStyledContext({ size: ["sm", "lg"] });

  // ❌ Wrong - loses literal types
  const sizes = ["sm", "lg"];
  createStyledContext({ size: sizes });
  ```
</Warning>

## See Also

* [Context Concept Guide](/concepts/context)
* [styled()](/api/styled)