# Form (controles de formulario)

> Documentación de QuicklyCSS V2 2.0.0-alpha.2. Versión preliminar.

- Página canónica: https://quicklycss.cl/docs/component-form.php
- Catálogo de API: https://quicklycss.cl/quicklycss-api.json
- Índice para IA: https://quicklycss.cl/llms.txt

Componentes · Entrada

Construye campos legibles con etiquetas, ayuda, validación y estados de foco consistentes.

v2.0

Aa
## Etiqueta visible
Cada control conserva un nombre persistente.

⌨
## Foco claro
Inputs, selects y textareas comparten un ring accesible.

!
## Error asociado
La validación combina estado visual y texto explicativo.

i
## Etiqueta siempre visible
Placeholder es una ayuda temporal y no reemplaza `.q-label`. Asocia cada label con su control.

Código + resultado

## Ejemplo aplicado de Form
El código mostrado corresponde exactamente al componente renderizado en el panel de resultado.

HTML

```html
<form class="q-form rounded-20 grid grid-col-2 grid-col-640-1 g-16 shadow-box-s">
  <header class="q-form__header grid-col-span-2 grid-col-span-640-1">
    <h3 class="q-form__title">
      Información del proyecto
    </h3>
    <p class="q-form__description">
      Configura los datos principales y su visibilidad.
    </p>
  </header>
  <label class="q-field">
    <span class="q-label">
      Nombre
    </span>
    <input class="q-input rounded-12" type="text" placeholder="Tu nombre" aria-describedby="form-name-help">
    <small class="q-field__help" id="form-name-help">
      Se mostrará en tu perfil.
    </small>
  </label>
  <label class="q-field">
    <span class="q-label">
      Correo
    </span>
    <input class="q-input rounded-12" type="email" placeholder="nombre@dominio.cl" aria-describedby="form-email-help">
    <small class="q-field__help" id="form-email-help">
      Recibirás aquí las notificaciones.
    </small>
  </label>
  <label class="q-field grid-col-span-2 grid-col-span-640-1">
    <span class="q-label">
      Mensaje
    </span>
    <textarea class="q-textarea rounded-12" placeholder="Escribe una descripción breve">
    </textarea>
  </label>
  <label class="q-field">
    <span class="q-label">
      Estado
    </span>
    <select class="q-select rounded-12">
      <option>
        Activo
      </option>
      <option>
        Pendiente
      </option>
    </select>
  </label>
  <label class="q-field">
    <span class="q-label">
      Visibilidad
    </span>
    <select class="q-select rounded-12">
      <option>
        Público
      </option>
      <option>
        Privado
      </option>
    </select>
  </label>
  <div class="q-form__actions grid-col-span-2 grid-col-span-640-1">
    <button class="btn btn-light btn-fs-01" type="reset">
      Cancelar
    </button>
    <button class="btn btn-primary btn-fs-01" type="submit">
      Guardar cambios
    </button>
  </div>
</form>
```

Resultado aplicado   Form · composición de campos

Componente real

### Información del proyecto
Configura los datos principales y su visibilidad.

Nombre   Se mostrará en tu perfil.    Correo   Recibirás aquí las notificaciones.    Mensaje      Estado   Activo  Pendiente     Visibilidad   Público  Privado

Construido únicamente con clases de QuicklyCSS V2 y HTML semántico.

Referencia

## Clases disponibles
La anatomía define las piezas estables; las utilidades de Quickly ajustan layout, espacio, tamaño y comportamiento responsive.

| Clase o atributo | Función | Uso recomendado |
| --- | --- | --- |
| .q-form | Superficie | Agrupa y presenta el formulario como una unidad visual. |
| .q-form__header | Introducción | Separa el contexto de los campos editables. |
| .q-form__title | Título | Define el propósito inmediato del formulario. |
| .q-form__description | Descripción | Explica brevemente la tarea antes de editar. |
| .q-form__actions | Acciones | Alinea las decisiones al final del flujo. |
| .q-field | Campo | Agrupa etiqueta, control y ayuda. |
| .q-label | Etiqueta | Nombre visible del control. |
| .q-input | Entrada | Campo input base. |
| .q-select | Selección | Control select base. |
| .q-textarea | Texto extenso | Control multilínea. |
| .q-field__help | Ayuda | Instrucción complementaria. |
| .q-field__error | Error | Mensaje de validación. |
| .grid | Layout auxiliar | Activa la cuadrícula del formulario. |
| .grid-col-2 | Columnas | Distribuye los campos en dos columnas. |
| .grid-col-640-1 | Responsive | Reduce el formulario a una columna. |
| .grid-col-span-2 | Extensión | Hace que una sección ocupe ambas columnas. |
| .grid-col-span-640-1 | Extensión responsive | Ajusta las secciones al ancho móvil. |
| .g-16 | Separación | Aplica 16px entre campos. |
| .shadow-box-s | Sombra opcional | Añade elevación mediante una utilidad independiente. |
| .btn | Botón base | Clase compartida de la acción. |
| .btn-light | Acción secundaria | Presenta la opción de cancelar sin competir con el envío. |
| .btn-primary | Acción principal | Destaca el envío del formulario. |
| .btn-fs-01 | Escala | Mantiene una acción legible y proporcionada. |
| [aria-invalid="true"] | Estado inválido | Comunica y representa errores. |
| .bc-{token} | Color de acento | Sincroniza el título y el foco de los controles. |
| .rounded-20 | Radio del formulario | Redondea la superficie principal. |
| .rounded-12 | Radio de controles | Redondea inputs, selects y textarea. |

Recomendaciones

## Buenas prácticas de Form

01
### Labels reales
Conecta cada etiqueta con su control.

02
### Ayuda antes del error
Explica formato o restricciones antes del envío.

03
### Tipo correcto
Usa email, tel, number y demás tipos nativos.

04
### Errores concretos
Indica qué campo falló y cómo corregirlo.