# dds-text
## Overview
Body text for the interface, set in the design system's type scale: paragraphs, captions, supporting copy and inline emphasis.
`as` chooses the element, which gives the text its meaning and decides whether it sits on its own line or inside one. `size`, `weight` and `contrast` only change how it looks.
Use it for any text that needs design system styling, and a plain HTML element where it doesn't. For headings use `dds-heading`.
## Usage
### Text
#### Choosing the element
`as` decides what the text _is_; `size`, `weight` and `contrast` only decide how it looks. Headings are a separate component, not `dds-text`.
```html
Body copy.
Supporting copy.
```
`as` takes `p`, `div`, `span`, `strong`, `em` and `small`. It defaults to `span`, so text with no `as` is inline and carries no meaning of its own. `p` and `div` render as blocks; the rest render inline. `strong`, `em` and `small` give the text their meaning but not their appearance, so set `weight` where bold is wanted.
#### Inline text inside a paragraph
Put a `dds-text` inside another to style part of a line. The inner one is inline by default.
```html
Order #1042 has shipped.
```
#### Size
`size` runs from `xs` (10px) to `l` (16px) and defaults to `m` (14px). For anything larger, such as a heading, use the heading component. Each step sets its own line height, so changing `size` alone keeps the text well spaced. No step is tied to an element: choose one for how the text looks, not for what it is.
#### Alignment and wrapping
`text-align` and `text-wrap` are inherited, so a consumer can set either on the element or on any ancestor. Set the `text-align` and `text-wrap` attributes only to override what the text would inherit. `text-wrap="balance"` suits short text that wraps and `text-wrap="pretty"` suits paragraphs.
#### Spacing between blocks
`dds-text` has no margin. Space blocks with the layout around them, for example a flex or grid container with `gap`.
#### Values `as` does not accept
Any `as` outside the list above renders as a `span`, so an `as` outside the list is an inline span, not a heading. Check the value if text that should be a block comes out inline; for a heading use the heading component.
#### Contrast
`contrast` is `high` by default. Use `contrast="low"` for text that supports the main content, such as a caption or a hint, and leave the default for text the reader has to read.
```html
Prices include VAT.
```
#### Numbers that line up
Set `font-variant-numeric="tabular-nums"` on figures that sit in a column or change while the reader watches, so every digit takes the same width. `diagonal-fractions` sets fractions such as 1/4 as one compact glyph.
```html
1,204.50
98.00
```
## Properties
| Property | Attribute | Description | Type | Default |
| -------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ----------- |
| `as` | `as` | The element the text renders as, which sets its meaning and whether it is a block or inline. | `"div" \| "em" \| "p" \| "small" \| "span" \| "strong"` | `"span"` |
| `contrast` | `contrast` | How strongly the text stands out against its background. | `"high" \| "low"` | `"high"` |
| `fontVariantNumeric` | `font-variant-numeric` | The `font-variant-numeric` property controls the usage of alternate glyphs for numbers, fractions, and ordinal markers. - `auto`: The default value. The browser determines whether to use alternate glyphs based on the font and context. - `tabular-nums`: Uses fixed-width digits, which are ideal for aligning numbers in tables or lists. - `diagonal-fractions`: Uses diagonal fraction glyphs, which are ideal for displaying fractions in a more compact and visually appealing way. For more information, see the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/CSS/font-variant-numeric). | `"auto" \| "diagonal-fractions" \| "tabular-nums"` | `"auto"` |
| `size` | `size` | Which step of the type scale to render at. Each step carries its own line height. | `"l" \| "m" \| "s" \| "xs"` | `"m"` |
| `textAlign` | `text-align` | Overrides the `text-align` the text would inherit. | `"center" \| "end" \| "justify" \| "start" \| undefined` | `undefined` |
| `textWrap` | `text-wrap` | Overrides the `text-wrap` the text would inherit. | `"balance" \| "nowrap" \| "pretty" \| "wrap" \| undefined` | `undefined` |
| `weight` | `weight` | How heavy the text is. | `"bold" \| "medium" \| "normal" \| "semibold"` | `"normal"` |
## Slots
| Slot | Description |
| ---- | ----------- |
| | The text. |
## Shadow Parts
| Part | Description |
| -------- | --------------------------- |
| `"root"` | The element chosen by `as`. |
----------------------------------------------
*Built with [StencilJS](https://stenciljs.com/)*