# useTheme

## Usage

Programmatic access to theme tokens for non-CSS consumers like SVG, canvas, Vega, D3, maps, or chart libraries that need values in JavaScript instead of CSS custom property references.

```ts
import { useTheme } from '@astryx-vue/core/Theme'
```

```ts
const { mode, token, tokens } = useTheme()

const accent = token('--color-accent')
const categorical = tokens.value['--color-data-categorical-blue']
```

## Best practices

| Guidance | Practices |
| --- | --- |
| Do | Use `tokens` or `token(name)` when integrating theme colors into SVG attributes, canvas drawing, chart options, or other non-CSS configuration objects inside Vue components. |
| Do | Prefer CSS variables for ordinary component styling; use this hook only when JavaScript needs token values. |
| Do | Use data visualization tokens such as `--color-data-categorical-blue` for chart series instead of arbitrary UI colors. |
| Don't | Hardcode light/dark colors in data visualizations: resolve them through the current theme instead. |
| Don't | Assume the hook reflects every CSS cascade override. It resolves tokens for the current `Theme` mode; local media-surface overrides and arbitrary external CSS may not be represented. |

## Examples

Common configurations, variations, and states.

### useTheme — Token Values

Read resolved theme token values with useTheme for non-CSS consumers like SVG charts.

```vue
<script setup lang="ts">
import { Code } from '@astryx-vue/core/Code'
import { HStack, VStack } from '@astryx-vue/core/Stack'
import { Text } from '@astryx-vue/core/Text'
import { useTheme } from '@astryx-vue/core/Theme'

const theme = useTheme()

const samples = ['--color-accent', '--color-background-surface', '--color-text-primary']
</script>

<template>
  <VStack :gap="3">
    <Text color="secondary">
      {{ theme.name.value }} · {{ theme.mode.value }}
    </Text>
    <Text weight="semibold">
      Resolved token values
    </Text>
    <HStack
      v-for="name in samples"
      :key="name"
      :gap="4"
      align="center"
      justify="between"
    >
      <Code color="secondary">
        {{ name }}
      </Code>
      <Code>{{ theme.token(name) }}</Code>
    </HStack>
  </VStack>
</template>
```

## Returns

| Name | Type | Description |
| --- | --- | --- |
| `name` | `ComputedRef<string>` | Name of the nearest theme, or `neutral` when no `Theme` is present. |
| `mode` | `ComputedRef<'light' \| 'dark'>` | Resolved effective color mode. `system` is resolved to `light` or `dark`. |
| `token` | `(name: string) => string` | Resolve a single design token to its current CSS value for the effective mode. Outside a `Theme`, it reads the document's custom properties. |
| `tokens` | `ComputedRef<Record<string, string>>` | Tokens declared by the nearest theme, resolved for the effective mode. A `[light, dark]` tuple becomes one value. Stable until the active theme or mode changes. |

Token names may be written either way: <code>--color-accent</code> or <code>--astryx-color-accent</code>.